iOS Developer Library

Developer

Foundation Framework Reference NSURLConnectionDelegate Protocol Reference

Options
Deployment Target:

On This Page
Language:

NSURLConnectionDelegate

Inheritance


Not Applicable

Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in iOS 5.0 and later.

The NSURLConnectionDelegate protocol defines methods common to the NSURLConnectionDataDelegate and NSURLConnectionDownloadDelegate protocols.

Delegates of NSURLConnection objects should implement either the data or download delegate protocol (including the methods described in this protocol). Specifically:

  • If you are using NSURLConnection in conjunction with Newsstand Kit’s downloadWithDelegate: method, the delegate class should implement the NSURLConnectionDownloadDelegate protocol.

  • Otherwise, the delegate class should implement the NSURLConnectionDataDelegate protocol.

Delegates that wish to perform custom authentication handling should implement the connection:willSendRequestForAuthenticationChallenge: method, which is the preferred mechanism for responding to authentication challenges. (See NSURLAuthenticationChallenge Class Reference for more information on authentication challenges.) If connection:willSendRequestForAuthenticationChallenge: is not implemented, the older, deprecated methods connection:canAuthenticateAgainstProtectionSpace:, connection:didReceiveAuthenticationChallenge:, and connection:didCancelAuthenticationChallenge: are called instead.

The connection:didFailWithError: method is called at most once if an error occurs during the loading of a resource. The connectionShouldUseCredentialStorage: method is called once, just before the loading of a resource begins.

  • Tells the delegate that the connection will send a request for an authentication challenge.

    Declaration

    Swift

    optional func connection(_ connection: NSURLConnection, willSendRequestForAuthenticationChallenge challenge: NSURLAuthenticationChallenge)

    Objective-C

    - (void)connection:(NSURLConnection *)connection willSendRequestForAuthenticationChallenge:(NSURLAuthenticationChallenge *)challenge

    Parameters

    connection

    The connection sending the message.

    challenge

    The authentication challenge for which a request is being sent.

    Discussion

    This method allows the delegate to make an informed decision about connection authentication at once. If the delegate implements this method, it has no need to implement connection:canAuthenticateAgainstProtectionSpace: or connection:didReceiveAuthenticationChallenge:. In fact, those other methods are not invoked (except on older operating systems, where applicable).

    In this method,you must invoke one of the challenge-responder methods (NSURLAuthenticationChallengeSender protocol):

    You might also want to analyze challenge for the authentication scheme and the proposed credential before calling a NSURLAuthenticationChallengeSender method. You should never assume that a proposed credential is present. You can either create your own credential and respond with that, or you can send the proposed credential back. (Because this object is immutable, if you want to change it you must copy it and then modify the copy.)

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later.

  • Sent to determine whether the delegate is able to respond to a protection space’s form of authentication.

    Declaration

    Swift

    optional func connection(_ connection: NSURLConnection, canAuthenticateAgainstProtectionSpace protectionSpace: NSURLProtectionSpace) -> Bool

    Objective-C

    - (BOOL)connection:(NSURLConnection *)connection canAuthenticateAgainstProtectionSpace:(NSURLProtectionSpace *)protectionSpace

    Parameters

    connection

    The connection sending the message.

    protectionSpace

    The protection space that generates an authentication challenge.

    Return Value

    YEStrue if the delegate if able to respond to a protection space’s form of authentication, otherwise NOfalse.

    Discussion

    This method is called before connection:didReceiveAuthenticationChallenge:, allowing the delegate to inspect a protection space before attempting to authenticate against it. By returning YEStrue, the delegate indicates that it can handle the form of authentication, which it does in the subsequent call to connection:didReceiveAuthenticationChallenge:. If the delegate returns NOfalse, the system attempts to use the user’s keychain to authenticate. If your delegate does not implement this method and the protection space uses client certificate authentication or server trust authentication, the system behaves as if you returned NOfalse. The system behaves as if you returned YEStrue for all other authentication methods.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.0 and later.

    Deprecated in iOS 8.0.

    Available as part of an informal protocol prior to iOS 5.0.

  • Sent when a connection cancels an authentication challenge.

    Declaration

    Swift

    optional func connection(_ connection: NSURLConnection, didCancelAuthenticationChallenge challenge: NSURLAuthenticationChallenge)

    Objective-C

    - (void)connection:(NSURLConnection *)connection didCancelAuthenticationChallenge:(NSURLAuthenticationChallenge *)challenge

    Parameters

    connection

    The connection sending the message.

    challenge

    The challenge that was canceled.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 8.0.

    Available as part of an informal protocol prior to iOS 5.0.

  • Sent when a connection must authenticate a challenge in order to download its request.

    Declaration

    Swift

    optional func connection(_ connection: NSURLConnection, didReceiveAuthenticationChallenge challenge: NSURLAuthenticationChallenge)

    Objective-C

    - (void)connection:(NSURLConnection *)connection didReceiveAuthenticationChallenge:(NSURLAuthenticationChallenge *)challenge

    Parameters

    connection

    The connection sending the message.

    challenge

    The challenge that connection must authenticate in order to download its request.

    Discussion

    This method gives the delegate the opportunity to determine the course of action taken for the challenge: provide credentials, continue without providing credentials, or cancel the authentication challenge and the download.

    The delegate can determine the number of previous authentication challenges by sending the message previousFailureCount to challenge.

    If the previous failure count is 0 and the value returned by proposedCredential is nil, the delegate can create a new NSURLCredential object, providing information specific to the type of credential, and send a useCredential:forAuthenticationChallenge: message to [challenge sender], passing the credential and challenge as parameters. If proposedCredential is not nil, the value is a credential from the URL or the shared credential storage that can be provided to the user as feedback.

    The delegate may decide to abandon further attempts at authentication at any time by sending [challenge sender] a continueWithoutCredentialForAuthenticationChallenge: or a cancelAuthenticationChallenge: message. The specific action is implementation dependent.

    If the delegate implements this method, the download will suspend until [challenge sender] is sent one of the following messages: useCredential:forAuthenticationChallenge:, continueWithoutCredentialForAuthenticationChallenge: or cancelAuthenticationChallenge:.

    If the delegate does not implement this method the default implementation is used. If a valid credential for the request is provided as part of the URL, or is available from the NSURLCredentialStorage the [challenge sender] is sent a useCredential:forAuthenticationChallenge: with the credential. If the challenge has no credential or the credentials fail to authorize access, then continueWithoutCredentialForAuthenticationChallenge: is sent to [challenge sender] instead.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 8.0.

    Available as part of an informal protocol prior to iOS 5.0.

  • Sent to determine whether the URL loader should use the credential storage for authenticating the connection.

    Declaration

    Swift

    optional func connectionShouldUseCredentialStorage(_ connection: NSURLConnection) -> Bool

    Objective-C

    - (BOOL)connectionShouldUseCredentialStorage:(NSURLConnection *)connection

    Parameters

    connection

    The connection sending the message.

    Discussion

    This method is called before any attempt to authenticate is made.

    If you return NOfalse, the connection does not consult the credential storage automatically, and does not store credentials. However, in your connection:didReceiveAuthenticationChallenge: method, you can consult the credential storage yourself and store credentials yourself, as needed.

    Not implementing this method is the same as returning YEStrue.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.0 and later.

    Available as part of an informal protocol prior to iOS 5.0.

  • Sent when a connection fails to load its request successfully.

    Declaration

    Swift

    optional func connection(_ connection: NSURLConnection, didFailWithError error: NSError)

    Objective-C

    - (void)connection:(NSURLConnection *)connection didFailWithError:(NSError *)error

    Parameters

    connection

    The connection sending the message.

    error

    An error object containing details of why the connection failed to load the request successfully.

    Discussion

    Once the delegate receives this message, it will receive no further messages for connection.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    Available as part of an informal protocol prior to iOS 5.0.