Protocol: NSURLConnectionDataDelegate

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.Sent as a connection loads data incrementally.Sent when the connection has received sufficient data to construct the URL response for its request.Sent as the body (message data) of a request is transmitted (such as in an http POST request).Called when an NSURLConnection needs to retransmit a request that has a body stream to provide a new, unopened stream.Sent before the connection stores a cached response in the cache, to give the delegate an opportunity to alter it.Sent when the connection determines that it must change URLs in order to continue loading a request.Sent when a connection has finished loading successfully.

Instance Method Summary (collapse)

Instance Method Details

- (Object) connection(connection, didReceiveData:data)

Sent as a connection loads data incrementally. 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.

Parameters:

  • connection (NSURLConnection) —

    The connection sending the message.

  • data (NSData) —

    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.

Returns:

- (Object) connection(connection, didReceiveResponse:response)

Sent when the connection has received sufficient data to construct the URL response for its request. 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.

Parameters:

  • connection (NSURLConnection) —

    The connection sending the message.

  • response (NSURLResponse) —

    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.

Returns:

- (Object) connection(connection, didSendBodyData:bytesWritten, totalBytesWritten:totalBytesWritten, totalBytesExpectedToWrite:totalBytesExpectedToWrite)

Sent as the body (message data) of a request is transmitted (such as in an http POST request). 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.

Parameters:

  • connection (NSURLConnection) —

    The connection sending the message.

  • bytesWritten (Integer) —

    The number of bytes written in the latest write.

  • totalBytesWritten (Integer) —

    The total number of bytes written for this connection.

  • totalBytesExpectedToWrite (Integer) —

    The number of bytes the connection expects to write.

Returns:

- (NSInputStream) connection(connection, needNewBodyStream:request)

Called when an NSURLConnection needs to retransmit a request that has a body stream to provide a new, unopened stream. 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.

Parameters:

Returns:

  • (NSInputStream) —

    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.

- (NSCachedURLResponse) connection(connection, willCacheResponse:cachedResponse)

Sent before the connection stores a cached response in the cache, to give the delegate an opportunity to alter it.

Parameters:

Returns:

  • (NSCachedURLResponse) —

    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.

- (NSURLRequest) connection(connection, willSendRequest:request, redirectResponse:redirectResponse)

Sent when the connection determines that it must change URLs in order to continue loading a request. 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.

Parameters:

  • connection (NSURLConnection) —

    The connection sending the message.

  • request (NSURLRequest) —

    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 (NSURLResponse) —

    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.

Returns:

  • (NSURLRequest) —

    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.

- (Object) connectionDidFinishLoading(connection)

Sent when a connection has finished loading successfully.

The delegate will receive no further messages for connection.

Parameters:

Returns: