NSURLSessionDelegate Protocol Reference

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

Overview

The NSURLSessionDelegate protocol describes the methods that NSURLSession objects call on their delegates to handle session-level events. In addition to the methods defined in this protocol, most delegates should also implement some or all of the methods in the NSURLSessionTaskDelegate, NSURLSessionDataDelegate, and NSURLSessionDownloadDelegate protocols to handle task-level events.

Tasks

Delegate Methods

Instance Methods

URLSession:didBecomeInvalidWithError:

Tells the URL session that the session has been invalidated.

- (void)URLSession:(NSURLSession *)session didBecomeInvalidWithError:(NSError *)error
Parameters
session

The session object that was invalidated.

error

The error that caused invalidation, or nil if the invalidation was explicit.

Discussion

If you invalidate a session by calling its finishTasksAndInvalidate method, the session waits until after the final task in the session finishes or fails before calling this delegate method. If you call the invalidateAndCancel method, the session calls this delegate method immediately.

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

URLSession:didReceiveChallenge:completionHandler:

Requests credentials from the delegate in response to a session-level authentication request from the remote server.

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

The session containing the task that requested 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 is called in two situations:

  • When a remote server asks for client certificates or Windows NT LAN Manager (NTLM) authentication, to allow your app to provide appropriate credentials

  • When a session first establishes a connection to a remote server that uses SSL or TLS, to allow your app to verify the server’s certificate chain

If you do not implement this method, the session calls its delegate’s URLSession:task:didReceiveChallenge:completionHandler: method instead.

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

URLSessionDidFinishEventsForBackgroundURLSession:

Tells the delegate that all messages enqueued for a session have been delivered.

- (void)URLSessionDidFinishEventsForBackgroundURLSession:(NSURLSession *)session;
Parameters
session

The session that no longer has any outstanding requests.

Discussion

In iOS, when a background transfer completes or requires credentials, if your app is no longer running, your app is automatically relaunched in the background, and the app’s UIApplicationDelegate is sent an application:handleEventsForBackgroundURLSession:completionHandler: message. This call contains the identifier of the session that caused your app to be launched. Your app should then store that completion handler before creating a background configuration object with the same identifier, and creating a session with that configuration. The newly created session is automatically reassociated with ongoing background activity.

When your app later receives a URLSessionDidFinishEventsForBackgroundURLSession: message, this indicates that all messages previously enqueued for this session have been delivered, and that it is now safe to invoke the previously stored completion handler or to begin any internal updates that may result in invoking the completion handler.

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

Constants

NSURLSessionAuthChallengeDisposition

Constants passed by session or task delegates to the provided continuation block in response to an authentication challenge.

typedef NS_ENUM(NSInteger,
   NSURLSessionAuthChallengeDisposition) {
   NSURLSessionAuthChallengeUseCredential = 0,
   NSURLSessionAuthChallengePerformDefaultHandling = 1,
   NSURLSessionAuthChallengeCancelAuthenticationChallenge = 2,
   NSURLSessionAuthChallengeRejectProtectionSpace = 3,
};
Constants
NSURLSessionAuthChallengeUseCredential

Use the specified credential, which may be nil.

Available in iOS 7.0 and later.

Declared in NSURLSession.h.

NSURLSessionAuthChallengePerformDefaultHandling

Use the default handling for the challenge as though this delegate method were not implemented. The provided credential parameter is ignored.

Available in iOS 7.0 and later.

Declared in NSURLSession.h.

NSURLSessionAuthChallengeCancelAuthenticationChallenge

Cancel the entire request. The provided credential parameter is ignored.

Available in iOS 7.0 and later.

Declared in NSURLSession.h.

NSURLSessionAuthChallengeRejectProtectionSpace

Reject this challenge, and call the authentication delegate method again with the next authentication protection space. The provided credential parameter is ignored.

Available in iOS 7.0 and later.

Declared in NSURLSession.h.