NSURLSessionDataDelegate Protocol Reference

Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in iOS 7.0 and later.
Declared in
NSURLSession.h

Overview

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.

Tasks

Delegate Methods

Instance Methods

URLSession:dataTask:didBecomeDownloadTask:

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

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

Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

URLSession:dataTask:didReceiveData:

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

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

Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

URLSession:dataTask:didReceiveResponse:completionHandler:

Tells the delegate that the data task received the initial reply (headers) from the server.

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

Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

URLSession:dataTask:willCacheResponse:completionHandler:

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

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

Availability
  • Available in iOS 7.0 and later.
Declared In
NSURLSession.h

Constants

NSURLSessionResponseDisposition

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

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

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

Available in iOS 7.0 and later.

Declared in NSURLSession.h.

NSURLSessionResponseAllow

Allow the load operation to continue.

Available in iOS 7.0 and later.

Declared in NSURLSession.h.

NSURLSessionResponseBecomeDownload

Convert this request into a download task.

Available in iOS 7.0 and later.

Declared in NSURLSession.h.

Discussion

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