iOS Developer Library

Developer

Foundation Framework Reference NSURLConnectionDataDelegate Protocol Reference

Options
Deployment Target:

On This Page
Language:

NSURLConnectionDataDelegate

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

Inheritance


Not Applicable

Import Statement


import Foundation @import Foundation;

Availability


Available in iOS 5.0 and later.
  • Sent when the connection has received sufficient data to construct the URL response for its request.

    Declaration

    Swift

    optional func connection(_ connection: NSURLConnection, didReceiveResponse response: NSURLResponse)

    Objective-C

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

    Import Statement

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    Available as part of an informal protocol prior to iOS 5.0.

  • Sent as a connection loads data incrementally.

    Declaration

    Swift

    optional func connection(_ connection: NSURLConnection, didReceiveData data: NSData)

    Objective-C

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

    Import Statement

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    Available as part of an informal protocol prior to iOS 5.0.

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

    Declaration

    Swift

    optional func connection(_ connection: NSURLConnection, didSendBodyData bytesWritten: Int, totalBytesWritten totalBytesWritten: Int, totalBytesExpectedToWrite totalBytesExpectedToWrite: Int)

    Objective-C

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

    Import Statement

    import Foundation

    Availability

    Available in iOS 3.0 and later.

    Available as part of an informal protocol prior to iOS 5.0.

  • Sent when a connection has finished loading successfully.

    Declaration

    Swift

    optional func connectionDidFinishLoading(_ connection: NSURLConnection)

    Objective-C

    - (void)connectionDidFinishLoading:(NSURLConnection *)connection

    Parameters

    connection

    The connection sending the message.

    Discussion

    The delegate will receive no further messages for connection.

    Import Statement

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    Available as part of an informal protocol prior to iOS 5.0.

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

    Declaration

    Swift

    optional func connection(_ connection: NSURLConnection, willSendRequest request: NSURLRequest, redirectResponse redirectResponse: NSURLResponse?) -> NSURLRequest?

    Objective-C

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

    Import Statement

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    Available as part of an informal protocol prior to iOS 5.0.

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

    Declaration

    Swift

    optional func connection(_ connection: NSURLConnection, needNewBodyStream request: NSURLRequest) -> NSInputStream?

    Objective-C

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

    Import Statement

    import Foundation

    Availability

    Available in iOS 3.0 and later.

    Available as part of an informal protocol prior to iOS 5.0.

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

    Declaration

    Swift

    optional func connection(_ connection: NSURLConnection, willCacheResponse cachedResponse: NSCachedURLResponse) -> NSCachedURLResponse?

    Objective-C

    - (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.)

    Import Statement

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    Available as part of an informal protocol prior to iOS 5.0.