iOS Developer Library

Developer

Foundation Framework Reference NSURLSessionDelegate Protocol Reference

Options
Deployment Target:

On This Page
Language:

NSURLSessionDelegate

Inheritance


Not Applicable

Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in iOS 7.0 and later.

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.

  • Tells the URL session that the session has been invalidated.

    Declaration

    Swift

    optional func URLSession(_ session: NSURLSession, didBecomeInvalidWithError error: NSError?)

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    optional func URLSession(_ session: NSURLSession, didReceiveChallenge challenge: NSURLAuthenticationChallenge, completionHandler completionHandler: (NSURLSessionAuthChallengeDisposition, NSURLCredential!) -> Void)

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    optional func URLSessionDidFinishEventsForBackgroundURLSession(_ session: NSURLSession)

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    enum NSURLSessionAuthChallengeDisposition : Int { case UseCredential case PerformDefaultHandling case CancelAuthenticationChallenge case RejectProtectionSpace }

    Objective-C

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

    Constants

    • UseCredential

      NSURLSessionAuthChallengeUseCredential

      Use the specified credential, which may be nil.

      Available in iOS 7.0 and later.

    • PerformDefaultHandling

      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.

    • CancelAuthenticationChallenge

      NSURLSessionAuthChallengeCancelAuthenticationChallenge

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

      Available in iOS 7.0 and later.

    • RejectProtectionSpace

      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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 7.0 and later.