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
Related sample code

Overview

The NSURLConnectionDataDelegate protocol describes methods that should be implemented by the delegate for an instance of the NSURLConnection class. Many methods in this protocol existed as part of an informal protocol in previous versions of OS X and iOS.

In addition to the methods described in this protocol, an NSURLConnection delegate should also implement the methods described in the NSURLConnectionDelegate protocol.

Tasks

Handling Incoming Data

Receiving Connection Progress

Handling Redirects

Overriding Caching Behavior

Instance Methods

connection:didReceiveData:

Sent as a connection loads data incrementally.

- (void)connection:(NSURLConnection *)connection didReceiveData:(NSData *)data
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.h

connection:didReceiveResponse:

Sent when the connection has received sufficient data to construct the URL response for its request.

- (void)connection:(NSURLConnection *)connection didReceiveResponse:(NSURLResponse *)response
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. When this happens, discard (or process) all data previously delivered by connection:didReceiveData:, and prepare to handle the next part (which could potentially have a different MIME type).

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.h

connection:didSendBodyData:totalBytesWritten:totalBytesExpectedToWrite:

Sent as the body (message data) of a request is transmitted (such as in an http POST request).

- (void)connection:(NSURLConnection *)connection didSendBodyData:(NSInteger)bytesWritten totalBytesWritten:(NSInteger)totalBytesWritten totalBytesExpectedToWrite:(NSInteger)totalBytesExpectedToWrite
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.h

connection:needNewBodyStream:

Called when an NSURLConnection needs to retransmit a request that has a body stream to provide a new, unopened stream.

- (NSInputStream *)connection:(NSURLConnection *)connection needNewBodyStream:(NSURLRequest *)request;
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.h

connection:willCacheResponse:

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

- (NSCachedURLResponse *)connection:(NSURLConnection *)connection willCacheResponse:(NSCachedURLResponse *)cachedResponse
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.

Discussion

This method is called only if the NSURLProtocol handling the request decides to cache the response. As a rule, responses are cached only when all of the following are true:

  • The request is for an HTTP or HTTPS URL (or your own custom networking protocol that supports caching).

  • The request was successful (with a status code in the 200–299 range).

  • The provided response came from the server, rather than out of the cache.

  • The NSURLRequest object's cache policy allows caching.

  • The cache-related headers in the server’s response (if present) allow caching.

  • The response size is small enough to reasonably fit within the cache. (For example, if you provide a disk cache, the response must be no larger than about 5% of the disk cache size.)

Availability
  • Available in iOS 2.0 and later.
  • Available as part of an informal protocol prior to iOS 5.0.
Declared In
NSURLConnection.h

connection:willSendRequest:redirectResponse:

Sent when the connection determines that it must change URLs in order to continue loading a request.

- (NSURLRequest *)connection:(NSURLConnection *)connection willSendRequest:(NSURLRequest *)request redirectResponse:(NSURLResponse *)redirectResponse
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 called because of URL canonicalization.

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 redirectResponse is nil, the URL was canonicalized (rewritten into its standard form) by the NSURLProtocol object handling the request. Update your user interface to show the standardized form of the URL, then return the original request unmodified.

Otherwise, to cancel the redirect, call the connection object’s cancel method, then return the provided request object.

To receive the body of the redirect response itself, return nil to cancel the redirect. The connection continues to process, eventually sending your delegate a connectionDidFinishLoading or connection:didFailLoadingWithError: message, as appropriate.

To redirect the request to a different URL, create a new request object and return it.

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.h

connectionDidFinishLoading:

Sent when a connection has finished loading successfully.

- (void)connectionDidFinishLoading:(NSURLConnection *)connection
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