Mac Developer Library

Developer

Foundation Framework Reference NSURLDownloadDelegate Protocol Reference

Options
Deployment Target:

On This Page
Language:

NSURLDownloadDelegate

Inheritance


Not Applicable

Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in OS X v10.7 and later.

The NSURLDownloadDelegate protocol defines methods that allow an object to receive informational callbacks about the asynchronous load of a download’s URL request. Other delegate methods provide facilities that allow the delegate to customize the process of performing an asynchronous URL load.

Note that these delegate methods will be called on the thread that started the asynchronous load operation for the associated NSURLDownload object.

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

    Declaration

    Swift

    optional func download(_ download: NSURLDownload, canAuthenticateAgainstProtectionSpace protectionSpace: NSURLProtectionSpace) -> Bool

    Objective-C

    - (BOOL)download:(NSURLDownload *)download canAuthenticateAgainstProtectionSpace:(NSURLProtectionSpace *)protectionSpace

    Parameters

    download

    The download sending the message.

    protectionSpace

    The protection space that generates an authentication challenge.

    Discussion

    This method is called before download: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 download:didReceiveAuthenticationChallenge:. Not implementing this method is the same as returning NOfalse, in which case default authentication handling is used.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.

    Available as part of an informal protocol prior to OS X v10.7.

  • Sent if an authentication challenge is canceled due to the protocol implementation encountering an error. (required)

    Declaration

    Swift

    optional func download(_ download: NSURLDownload, didCancelAuthenticationChallenge challenge: NSURLAuthenticationChallenge)

    Objective-C

    - (void)download:(NSURLDownload *)download didCancelAuthenticationChallenge:(NSURLAuthenticationChallenge *)challenge

    Parameters

    download

    The URL download object sending the message.

    challenge

    The authentication challenge that caused the download object to cancel the download.

    Discussion

    If the delegate receives this message the download will fail and the delegate will receive a download:didFailWithError: message.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

    Available as part of an informal protocol prior to OS X v10.7.

  • Sent when the URL download must authenticate a challenge in order to download the request. (required)

    Declaration

    Swift

    optional func download(_ download: NSURLDownload, didReceiveAuthenticationChallenge challenge: NSURLAuthenticationChallenge)

    Objective-C

    - (void)download:(NSURLDownload *)download didReceiveAuthenticationChallenge:(NSURLAuthenticationChallenge *)challenge

    Parameters

    download

    The URL download object sending the message.

    challenge

    The URL authentication challenge that must be authenticated in order to download the 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 OS X v10.2 and later.

    Available as part of an informal protocol prior to OS X v10.7.

  • Sent to determine whether the URL loader should consult the credential storage to authenticate the download. (required)

    Declaration

    Swift

    optional func downloadShouldUseCredentialStorage(_ connection: NSURLDownload) -> Bool

    Objective-C

    - (BOOL)downloadShouldUseCredentialStorage:(NSURLDownload *)connection

    Parameters

    connection

    The connection sending the message.

    Discussion

    This method is called before any attempt to authenticate is made. By returning NOfalse, the delegate tells the download not to consult the credential storage and makes itself responsible for providing credentials for any authentication challenges. Not implementing this method is the same as returing YEStrue. The delegate is free to consult the credential storage itself when it receives a download:didReceiveAuthenticationChallenge: message.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.

    Available as part of an informal protocol prior to OS X v10.7.

  • The delegate receives this message when download has determined a suggested filename for the downloaded file. (required)

    Declaration

    Swift

    optional func download(_ download: NSURLDownload, decideDestinationWithSuggestedFilename filename: String)

    Objective-C

    - (void)download:(NSURLDownload *)download decideDestinationWithSuggestedFilename:(NSString *)filename

    Parameters

    download

    The URL download object sending the message.

    filename

    The suggested filename for the download.

    Discussion

    The suggested filename is either derived from the last path component of the URL and the MIME type or, if the download was encoded, from the encoding. If the delegate wishes to modify the path, it should send setDestination:allowOverwrite: to download.

    Special Considerations

    The delegate will not receive this message if setDestination:allowOverwrite: has already been called for the download.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

    Available as part of an informal protocol prior to OS X v10.7.

  • Sent immediately after a download object begins a download. (required)

    Declaration

    Swift

    optional func downloadDidBegin(_ download: NSURLDownload)

    Objective-C

    - (void)downloadDidBegin:(NSURLDownload *)download

    Parameters

    download

    The URL download object sending the message.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

    Available as part of an informal protocol prior to OS X v10.7.

  • Sent when the destination file is created. (required)

    Declaration

    Swift

    optional func download(_ download: NSURLDownload, didCreateDestination path: String)

    Objective-C

    - (void)download:(NSURLDownload *)download didCreateDestination:(NSString *)path

    Parameters

    download

    The URL download object sending the message.

    path

    The path to the destination file.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

    Available as part of an informal protocol prior to OS X v10.7.

  • Sent when a download object has received sufficient load data to construct the NSURLResponse object for the download. (required)

    Declaration

    Swift

    optional func download(_ download: NSURLDownload, didReceiveResponse response: NSURLResponse)

    Objective-C

    - (void)download:(NSURLDownload *)download didReceiveResponse:(NSURLResponse *)response

    Parameters

    download

    The URL download object sending the message.

    response

    The URL response object received as part of the download. response is immutable and will not be modified after this method is called.

    Discussion

    In some rare cases, multiple responses may be received for a single download. In this case, the client should assume that each new response resets the download progress to 0 and should check the new response for the expected content length.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

    Available as part of an informal protocol prior to OS X v10.7.

  • Sent as a download object receives data incrementally. (required)

    Declaration

    Swift

    optional func download(_ download: NSURLDownload, didReceiveDataOfLength length: Int)

    Objective-C

    - (void)download:(NSURLDownload *)download didReceiveDataOfLength:(NSUInteger)length

    Parameters

    download

    The URL download object sending the message.

    length

    The amount of data received in this increment of the download, measured in bytes.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

    Available as part of an informal protocol prior to OS X v10.7.

  • Sent when a download object determines that the downloaded file is encoded to inquire whether the file should be automatically decoded. (required)

    Declaration

    Swift

    optional func download(_ download: NSURLDownload, shouldDecodeSourceDataOfMIMEType encodingType: String) -> Bool

    Objective-C

    - (BOOL)download:(NSURLDownload *)download shouldDecodeSourceDataOfMIMEType:(NSString *)encodingType

    Parameters

    download

    The URL download object sending the message.

    encodingType

    The type of encoding used by the downloaded file. The supported encoding formats are MacBinary ("application/macbinary"), Binhex ("application/mac-binhex40") and gzip ("application/gzip").

    Return Value

    YEStrue to decode the file, NOfalse otherwise.

    Special Considerations

    The delegate may receive this message more than once if the file has been encoded multiple times. This method is not called if the downloaded file is not encoded.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

    Available as part of an informal protocol prior to OS X v10.7.

  • Sent when a download object has received a response from the server after attempting to resume a download. (required)

    Declaration

    Swift

    optional func download(_ download: NSURLDownload, willResumeWithResponse response: NSURLResponse, fromByte startingByte: Int64)

    Objective-C

    - (void)download:(NSURLDownload *)download willResumeWithResponse:(NSURLResponse *)response fromByte:(long long)startingByte

    Parameters

    download

    The URL download object sending the message.

    response

    The URL response received from the server in response to an attempt to resume a download.

    startingByte

    The location of the start of the resumed data, in bytes.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.4 and later.

    Available as part of an informal protocol prior to OS X v10.7.

  • Sent when the download object determines that it must change URLs in order to continue loading a request. (required)

    Declaration

    Swift

    optional func download(_ download: NSURLDownload, willSendRequest request: NSURLRequest, redirectResponse redirectResponse: NSURLResponse?) -> NSURLRequest?

    Objective-C

    - (NSURLRequest *)download:(NSURLDownload *)download willSendRequest:(NSURLRequest *)request redirectResponse:(NSURLResponse *)redirectResponse

    Parameters

    download

    The URL download object sending the message.

    request

    The proposed redirected request. The delegate should inspect the redirected request to verify that it meets its needs, and create a copy with new attributes to return to the connection if necessary.

    redirectResponse

    The URL response that caused the redirect. May be nil in cases where this method is not being sent as a result of involving the delegate in redirect processing.

    Return Value

    The actual URL request to use in light of the redirection response. The delegate may copy and modify request as necessary to change its attributes, return request unmodified, or return nil.

    Discussion

    If the delegate wishes to cancel the redirect, it should call the download object’s cancel method. Alternatively, the delegate method can return nil to cancel the redirect, and the download will continue to process. This has special relevance in the case where redirectResponse is not nil. In this case, any data that is loaded for the download will be sent to the delegate, and the delegate will receive a downloadDidFinish: or download:didFailWithError: message, as appropriate.

    Special Considerations

    The delegate can receive this message as a result of transforming a request’s URL to its canonical form, or for protocol-specific reasons, such as an HTTP redirect. The delegate implementation should be prepared to receive this message multiple times.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

    Available as part of an informal protocol prior to OS X v10.7.

  • Sent if the download fails or if an I/O error occurs when the file is written to disk. (required)

    Declaration

    Swift

    optional func download(_ download: NSURLDownload, didFailWithError error: NSError)

    Objective-C

    - (void)download:(NSURLDownload *)download didFailWithError:(NSError *)error

    Parameters

    download

    The URL download object sending the message.

    error

    The error that caused the failure of the download.

    Discussion

    Any partially downloaded file will be deleted.

    Special Considerations

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

    Available as part of an informal protocol prior to OS X v10.7.

  • Sent when a download object has completed downloading successfully and has written its results to disk. (required)

    Declaration

    Swift

    optional func downloadDidFinish(_ download: NSURLDownload)

    Objective-C

    - (void)downloadDidFinish:(NSURLDownload *)download

    Parameters

    download

    The URL download object sending the message.

    Discussion

    The delegate will receive no further messages for download.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

    Available as part of an informal protocol prior to OS X v10.7.