NSURLSessionTaskDelegate Protocol Reference

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

Overview

The NSURLSessionTaskDelegate protocol defines the task-specific delegate methods that you should implement when working with any type of NSURLSession task.

If you are using download tasks, also implement the methods in the NSURLSessionDownloadDelegate protocol.

If you are using data or upload tasks, also implement the methods in the NSURLSessionDataDelegate protocol.

Tasks

Delegate Methods

Instance Methods

URLSession:task:didCompleteWithError:

Tells the delegate that the task finished transferring data.

- (void)URLSession:(NSURLSession *)session task:(NSURLSessionTask *)task didCompleteWithError:(NSError *)error
Parameters
session

The session containing the task whose request finished transferring data.

task

The task whose request finished transferring data.

error

If an error occurred, an error object indicating how the transfer failed, otherwise NULL.

Discussion

Server errors are not reported through the error parameter. The only errors your delegate receives through the error parameter are client-side errors, such as being unable to resolve the hostname or connect to the host.

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

URLSession:task:didReceiveChallenge:completionHandler:

Requests credentials from the delegate in response to an authentication request from the remote server.

- (void)URLSession:(NSURLSession *)session task:(NSURLSessionTask *)task didReceiveChallenge:(NSURLAuthenticationChallenge *)challenge completionHandler:(void (^)(NSURLSessionAuthChallengeDisposition disposition, NSURLCredential *credential))completionHandler
Parameters
session

The session containing the task whose request requires authentication.

task

The task whose request requires authentication.

challenge

An object that contains the request for authentication.

completionHandler

A handler that your delegate method must call. Its parameters are:

  • disposition—One of several constants that describes how the challenge should be handled.

  • credential—The credential that should be used for authentication if disposition is NSURLSessionAuthChallengeUseCredential; otherwise, NULL.

Discussion

This method handles task-level authentication challenges. The NSURLSessionDelegate protocol also provides a session-level authentication delegate method. The method called depends on the type of authentication challenge:

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

URLSession:task:didSendBodyData:totalBytesSent:totalBytesExpectedToSend:

Periodically informs the delegate of the progress of sending body content to the server.

- (void)URLSession:(NSURLSession *)session task:(NSURLSessionTask *)task didSendBodyData:(int64_t)bytesSent totalBytesSent:(int64_t)totalBytesSent totalBytesExpectedToSend:(int64_t)totalBytesExpectedToSend
Parameters
session

The session containing the data task.

task

The data task.

bytesSent

The number of bytes sent since the last time this delegate method was called.

totalBytesSent

The total number of bytes sent so far.

totalBytesExpectedToSend

The expected length of the body data. The URL loading system can determine the length of the upload data in three ways:

  • From the length of the NSData object provided as the upload body.

  • From the length of the file on disk provided as the upload body of an upload task (not a download task).

  • From the Content-Length in the request object, if you explicitly set it.

Otherwise, the value is NSURLSessionTransferSizeUnknown (-1) if you provided a stream or body data object, or zero (0) if you did not.

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

URLSession:task:needNewBodyStream:

Tells the delegate when a task requires a new request body stream to send to the remote server.

- (void)URLSession:(NSURLSession *)session task:(NSURLSessionTask *)task needNewBodyStream:(void (^)(NSInputStream *bodyStream))completionHandler
Parameters
session

The session containing the task that needs a new body stream.

task

The task that needs a new body stream.

completionHandler

A completion handler that your delegate method should call with the new body stream.

Discussion

This delegate method is called under two circumstances:

  • To provide the initial request body stream if the task was created with uploadTaskWithStreamedRequest:

  • To provide a replacement request body stream if the task needs to resend a request that has a body stream because of an authentication challenge or other recoverable server error.

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

URLSession:task:willPerformHTTPRedirection:newRequest:completionHandler:

Tells the delegate that the remote server requested an HTTP redirect.

- (void)URLSession:(NSURLSession *)session task:(NSURLSessionTask *)task willPerformHTTPRedirection:(NSHTTPURLResponse *)response newRequest:(NSURLRequest *)request completionHandler:(void (^)(NSURLRequest *))completionHandler
Parameters
session

The session containing the task whose request resulted in a redirect.

task

The task whose request resulted in a redirect.

response

An object containing the server’s response to the original request.

request

A URL request object filled out with the new location.

completionHandler

A block that your handler should call with either the value of the request parameter, a modified URL request object, or NULL to refuse the redirect and return the body of the redirect response.

Discussion

This method is called only for tasks in default and ephemeral sessions. Tasks in background sessions automatically follow redirects.

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