NSURLConnectionDataDelegate Protocol Reference
| Conforms to | |
| Framework | /System/Library/Frameworks/Foundation.framework/ |
| Availability | Available in iOS 5.0 and later. |
| Companion guide | |
| Declared in | NSURLConnection.h |
Overview
The NSURLConnectionDataDelegate protocol describes methods that should be implemented by the delegate for an instance of NSURLConnection that is intended to download data to memory. Many methods in this protocol existed as part of an informal protocol in previous versions of OS X and iOS.
Tasks
Handling Incoming Data
Receiving Connection Progress
-
– connection:didSendBodyData:totalBytesWritten:totalBytesExpectedToWrite: -
– connectionDidFinishLoading:
Handling Redirects
Overriding Caching Behavior
Instance Methods
connection:didReceiveData:
Sent as a connection loads data incrementally.
Parameters
- connection
The connection sending the message.
- data
The newly available data. The delegate should concatenate the contents of each data object delivered to build up the complete data for a URL load.
Discussion
This method provides the only way for an asynchronous delegate to retrieve the loaded data. It is the responsibility of the delegate to retain or copy this data as it is delivered.
Availability
- Available in iOS 2.0 and later.
- Available as part of an informal protocol prior to iOS 5.0.
Declared In
NSURLConnection.hconnection:didReceiveResponse:
Sent when the connection has received sufficient data to construct the URL response for its request.
Parameters
- connection
The connection sending the message.
- response
The URL response for the connection's request. This object is immutable and will not be modified by the URL loading system once it is presented to the delegate.
Discussion
In rare cases, for example in the case of an HTTP load where the content type of the load data is multipart/x-mixed-replace, the delegate will receive more than one connection:didReceiveResponse: message. In the event this occurs, delegates should discard all data previously delivered by connection:didReceiveData:, and should be prepared to handle the, potentially different, MIME type reported by the newly reported URL response.
The only case where this message is not sent to the delegate is when the protocol implementation encounters an error before a response could be created.
Availability
- Available in iOS 2.0 and later.
- Available as part of an informal protocol prior to iOS 5.0.
Declared In
NSURLConnection.hconnection:didSendBodyData:totalBytesWritten:totalBytesExpectedToWrite:
Sent as the body (message data) of a request is transmitted (such as in an http POST request).
Parameters
- connection
The connection sending the message.
- bytesWritten
The number of bytes written in the latest write.
- totalBytesWritten
The total number of bytes written for this connection.
- totalBytesExpectedToWrite
The number of bytes the connection expects to write.
Discussion
This method provides an estimate of the progress of a URL upload.
The value of totalBytesExpectedToWrite may change during the upload if the request needs to be retransmitted due to a lost connection or an authentication challenge from the server.
Availability
- Available in iOS 3.0 and later.
- Available as part of an informal protocol prior to iOS 5.0.
Declared In
NSURLConnection.hconnection:needNewBodyStream:
Called when an NSURLConnection needs to retransmit a request that has a body stream to provide a new, unopened stream.
Parameters
- connection
The NSURLConnection that is requesting a new body stream.
Return Value
This delegate method should return a new, unopened stream that provides the body contents for the request.
If this delegate method returns NULL, the connection fails.
Discussion
On OS X, if this method is not implemented, body stream data is spooled to disk in case retransmission is required. This spooling may not be desirable for large data sets.
By implementing this delegate method, the client opts out of automatic spooling, and must provide a new, unopened stream for each retransmission.
Availability
- Available in iOS 3.0 and later.
- Available as part of an informal protocol prior to iOS 5.0.
Declared In
NSURLConnection.hconnection:willCacheResponse:
Sent before the connection stores a cached response in the cache, to give the delegate an opportunity to alter it.
Parameters
- connection
The connection sending the message.
- cachedResponse
The proposed cached response to store in the cache.
Return Value
The actual cached response to store in the cache. The delegate may return cachedResponse unmodified, return a modified cached response, or return nil if no cached response should be stored for the connection.
Availability
- Available in iOS 2.0 and later.
- Available as part of an informal protocol prior to iOS 5.0.
Declared In
NSURLConnection.hconnection:willSendRequest:redirectResponse:
Sent when the connection determines that it must change URLs in order to continue loading a request.
Parameters
- connection
The connection sending the message.
- request
The proposed redirected request. The delegate should inspect the redirected request to verify that it meets its needs, and create a copy with new attributes to return to the connection if necessary.
- redirectResponse
The URL response that caused the redirect. May be nil in cases where this method is not being sent as a result of involving the delegate in redirect processing.
Return Value
The actual URL request to use in light of the redirection response. The delegate may return request unmodified to allow the redirect, return a new request, or return nil to reject the redirect and continue processing the connection.
Discussion
If the delegate wishes to cancel the redirect, it should call the connection object’s cancel method. Alternatively, the delegate method can return nil to cancel the redirect, and the connection will continue to process. This has special relevance in the case where redirectResponse is not nil. In this case, any data that is loaded for the connection will be sent to the delegate, and the delegate will receive a connectionDidFinishLoading or connection:didFailLoadingWithError: message, as appropriate.
The delegate can receive this message as a result of modifying a request before it is sent, for example to transform the request’s URL to its canonical form. To detect this case, examine redirectResponse; if it is nil, the message was not sent due to a redirect.
The delegate should be prepared to receive this message multiple times.
Availability
- Available in iOS 2.0 and later.
- Available as part of an informal protocol prior to iOS 5.0.
Declared In
NSURLConnection.hconnectionDidFinishLoading:
Sent when a connection has finished loading successfully.
Parameters
- connection
The connection sending the message.
Discussion
The delegate will receive no further messages for connection.
Availability
- Available in iOS 2.0 and later.
- Available as part of an informal protocol prior to iOS 5.0.
Declared In
NSURLConnection.h© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-07-17)