Mac Developer Library

Developer

Foundation Framework Reference NSURLSessionDataDelegate Protocol Reference

Options
Deployment Target:

On This Page
Language:

NSURLSessionDataDelegate

The NSURLSessionDataDelegate protocol defines the methods that a delegate of an NSURLSession object can implement to handle task-level events specific to data tasks and upload tasks. Your session delegate should also implement the methods in the NSURLSessionTaskDelegate protocol to handle task-level events that are common to all task types, and methods in the NSURLSessionDelegate protocol to handle session-level events. More...

Inheritance


Not Applicable

Import Statement


import Foundation @import Foundation;

Availability


Available in OS X v10.9 and later.
  • Tells the delegate that the data task received the initial reply (headers) from the server.

    Declaration

    Swift

    optional func URLSession(_ session: NSURLSession, dataTask dataTask: NSURLSessionDataTask, didReceiveResponse response: NSURLResponse, completionHandler completionHandler: (NSURLSessionResponseDisposition) -> Void)

    Objective-C

    - (void)URLSession:(NSURLSession *)session dataTask:(NSURLSessionDataTask *)dataTask didReceiveResponse:(NSURLResponse *)response completionHandler:(void (^)(NSURLSessionResponseDisposition disposition))completionHandler

    Parameters

    session

    The session containing the data task that received an initial reply.

    dataTask

    The data task that received an initial reply.

    response

    A URL response object populated with headers.

    completionHandler

    A completion handler that your code calls to continue the transfer, passing a constant to indicate whether the transfer should continue as a data task or should become a download task.

    Discussion

    This method is optional unless you need to support the (relatively obscure) multipart/x-mixed-replace content type. With that content type, the server sends a series of parts, each of which is intended to replace the previous part. The session calls this method at the beginning of each part, and you should then display, discard, or otherwise process the previous part, as appropriate.

    If you do not provide this delegate method, the session always allows the task to continue.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.9 and later.

  • Tells the delegate that the data task was changed to a download task.

    Declaration

    Swift

    optional func URLSession(_ session: NSURLSession, dataTask dataTask: NSURLSessionDataTask, didBecomeDownloadTask downloadTask: NSURLSessionDownloadTask)

    Objective-C

    - (void)URLSession:(NSURLSession *)session dataTask:(NSURLSessionDataTask *)dataTask didBecomeDownloadTask:(NSURLSessionDownloadTask *)downloadTask

    Parameters

    session

    The session containing the task that was replaced by a download task.

    dataTask

    The data task that was replaced by a download task.

    downloadTask

    The new download task that replaced the data task.

    Discussion

    When the delegate’s URLSession:dataTask:didReceiveResponse:completionHandler: method decides to change the disposition from a data request to a download, the session calls this delegate method to provide you with the new download task. After this call, the session delegate receives no further delegate method calls related to the original data task.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.9 and later.

  • Tells the delegate that the data task has received some of the expected data.

    Declaration

    Swift

    optional func URLSession(_ session: NSURLSession, dataTask dataTask: NSURLSessionDataTask, didReceiveData data: NSData)

    Objective-C

    - (void)URLSession:(NSURLSession *)session dataTask:(NSURLSessionDataTask *)dataTask didReceiveData:(NSData *)data

    Parameters

    session

    The session containing the data task that provided data.

    dataTask

    The data task that provided data.

    data

    A data object containing the transferred data.

    Discussion

    Because the NSData object is often pieced together from a number of different data objects, whenever possible, use NSData’s enumerateByteRangesUsingBlock: method to iterate through the data rather than using the bytes method (which flattens the NSData object into a single memory block).

    This delegate method may be called more than once, and each call provides only data received since the previous call. The app is responsible for accumulating this data if needed.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.9 and later.

  • Asks the delegate whether the data (or upload) task should store the response in the cache.

    Declaration

    Swift

    optional func URLSession(_ session: NSURLSession, dataTask dataTask: NSURLSessionDataTask, willCacheResponse proposedResponse: NSCachedURLResponse, completionHandler completionHandler: (NSCachedURLResponse!) -> Void)

    Objective-C

    - (void)URLSession:(NSURLSession *)session dataTask:(NSURLSessionDataTask *)dataTask willCacheResponse:(NSCachedURLResponse *)proposedResponse completionHandler:(void (^)(NSCachedURLResponse *cachedResponse))completionHandler

    Parameters

    session

    The session containing the data (or upload) task.

    dataTask

    The data (or upload) task.

    proposedResponse

    The default caching behavior. This behavior is determined based on the current caching policy and the values of certain received headers, such as the Pragma and Cache-Control headers.

    completionHandler

    A block that your handler must call, providing either the original proposed response, a modified version of that response, or NULL to prevent caching the response. If your delegate implements this method, it must call this completion handler; otherwise, your app leaks memory.

    Discussion

    The session calls this delegate method after the task finishes receiving all of the expected data. If you do not implement this method, the default behavior is to use the caching policy specified in the session’s configuration object. The primary purpose of this method is to prevent caching of specific URLs or to modify the userInfo dictionary associated with the URL response.

    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 session configuration’s cache policy allows caching.

    • The provided NSURLRequest object's cache policy (if applicable) 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 OS X v10.9 and later.

  • Constants indicating how a data or upload session should proceed after receiving the initial headers.

    Declaration

    Swift

    enum NSURLSessionResponseDisposition : Int { case Cancel case Allow case BecomeDownload }

    Objective-C

    typedef NS_ENUM (NSInteger, NSURLSessionResponseDisposition ) { NSURLSessionResponseCancel = 0, NSURLSessionResponseAllow = 1, NSURLSessionResponseBecomeDownload = 2 };

    Constants

    • Cancel

      NSURLSessionResponseCancel

      Cancel the load. Equivalent to calling cancel on the task.

      Available in OS X v10.9 and later.

    • Allow

      NSURLSessionResponseAllow

      Allow the load operation to continue.

      Available in OS X v10.9 and later.

    • BecomeDownload

      NSURLSessionResponseBecomeDownload

      Convert this request into a download task.

      Available in OS X v10.9 and later.

    Discussion

    A data or upload task’s URLSession:dataTask:didReceiveResponse:completionHandler: delegate method passes these constants to the provided completion handler block.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.9 and later.