Mac Developer Library

Developer

Foundation Framework Reference NSURLDownload Class Reference

Options
Deployment Target:

On This Page
Language:

NSURLDownload

The NSURLDownload class downloads a request asynchronously and saves the data to a file. The interface for NSURLDownload provides methods to initialize a download, set the destination path and cancel loading the request. More...

Inheritance


Conforms To


Import Statement


import Foundation @import Foundation;

Availability


Available in OS X v10.2 with Safari 1.0 installed.
Available in OS X v10.2.7 and later.
  • Returns an initialized URL download for a URL request and begins to download the data for the request.

    Declaration

    Swift

    init(request request: NSURLRequest, delegate delegate: NSURLDownloadDelegate?)

    Objective-C

    - (instancetype)initWithRequest:(NSURLRequest *)request delegate:(id<NSURLDownloadDelegate>)delegate

    Parameters

    request

    The URL request to download. The request object is deep-copied as part of the initialization process. Changes made to request after this method returns do not affect the request that is used for the loading process.

    delegate

    The delegate for the download. This object will receive delegate messages as the download progresses. Delegate messages will be sent on the thread which calls this method. For the download to work correctly the calling thread’s run loop must be operating in the default run loop mode.

    The NSURLDownload class maintains a strong reference to this delegate object.

    Return Value

    An initialized NSURLDownload object for request.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.2 with Safari 1.0 installed.

    Available in OS X v10.2.7 and later.

  • Sets the destination path of the downloaded file.

    Declaration

    Swift

    func setDestination(_ path: String, allowOverwrite allowOverwrite: Bool)

    Objective-C

    - (void)setDestination:(NSString *)path allowOverwrite:(BOOL)allowOverwrite

    Parameters

    path

    The path for the downloaded file.

    allowOverwrite

    YEStrue if an existing file at path can be replaced, NOfalse otherwise.

    Discussion

    If allowOverwrite is NOfalse and a file already exists at path, a unique filename will be created for the downloaded file by appending a number to the filename. The delegate can implement the download:didCreateDestination: delegate method to determine the filename used when the file is written to disk.

    Special Considerations

    An NSURLDownload instance ignores multiple calls to this method.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.2 with Safari 1.0 installed.

    Available in OS X v10.2.7 and later.

  • Returns whether a URL download object can resume a download that was decoded with the specified MIME type.

    Declaration

    Swift

    class func canResumeDownloadDecodedWithEncodingMIMEType(_ MIMEType: String) -> Bool

    Objective-C

    + (BOOL)canResumeDownloadDecodedWithEncodingMIMEType:(NSString *)MIMEType

    Parameters

    MIMEType

    The MIME type the caller wants to know about.

    Return Value

    YEStrue if the URL download object can resume a download that was decoded with the specified MIME type, NOfalse otherwise.

    Discussion

    The MIME type of a file, in conjunction with the value returned by the download:shouldDecodeSourceDataOfMIMEType: delegate method, determines whether the NSURLDownload class should decode or decompress the incoming data as it is received.

    Some compression techniques, such as the DEFLATE algorithm (gzip) use symbol dictionaries that vary during the compression process, making it impractical to decompress only a portion of the data starting in the middle. For this reason, this method returns NOfalse unless both of the following conditions are met:

    • The MIME type is of a type that the NSURLDownload class knows how to decompress or decode.

    • The decoding can be safely resumed.

    In practice, this method returns YEStrue for MacBinary and BinHex, otherwise NOfalse.

    If your app needs to be able to resume file downloads in gzip format, your download:shouldDecodeSourceDataOfMIMEType: method must return NOfalse, and you must decode the resulting file yourself after you finish downloading it in its entirety.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.4 and later.

  • Returns an initialized NSURLDownload object that will resume downloading the specified data to the specified file and begins the download.

    Declaration

    Swift

    init(resumeData resumeData: NSData, delegate delegate: NSURLDownloadDelegate?, path path: String)

    Objective-C

    - (instancetype)initWithResumeData:(NSData *)resumeData delegate:(id<NSURLDownloadDelegate>)delegate path:(NSString *)path

    Parameters

    resumeData

    Specifies the data to resume downloading.

    delegate

    The delegate for the download. This object will receive delegate messages as the download progresses. Delegate messages will be sent on the thread which calls this method. For the download to work correctly the calling thread’s run loop must be operating in the default run loop mode.

    The NSURLDownload class maintains a strong reference to this delegate object.

    path

    The location for the downloaded data.

    Return Value

    An initialized NSURLDownload object.

    Discussion

    If you want to support pausing and resuming downloads, your app must:

    1. Call setDeletesFileUponFailure:, passing NOfalse. If you want to support resuming downloads in the event of a lost connection, you should do this immediately after you initialize the download object.

    2. If your app needs to pause the transfer for any reason, call cancel. Because your app previously called setDeletesFileUponFailure: with NOfalse, the in-progress download is not deleted.

    3. After your app pauses the transfer or after a transfer error occurs, call resumeData to obtain the data needed to resume the transfer later.

    4. If the transfer failed because of a connectivity error, use the SCNetworkReachability API to determine an appropriate time to try again. For details, read SCNetworkReachability Reference.

      If your app explicitly paused the download, wait until it is appropriate to continue the transfer (such as when the user clicks or taps a resume button).

    5. Call initWithResumeData:delegate:path: and pass the resume data blob that it previously obtained in step 3.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.4 and later.

    See Also

    cancel
    resumeData

  • Returns the resume data for a download that is not yet complete.

    Declaration

    Swift

    @NSCopying var resumeData: NSData? { get }

    Objective-C

    @property(readonly, copy) NSData *resumeData

    Return Value

    The resume data for a download that is not yet complete. This data represents the necessary state information that an NSURLDownload object needs to resume a download. The resume data can later be used when initializing a download with initWithResumeData:delegate:path:. Returns nil if the download is not able to be resumed.

    Discussion

    Resume data is returned only if both the protocol and the server support resuming. For details on how to resume a connection, see the documentation for initWithResumeData:delegate:path:.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.4 and later.

  • Specifies whether the receiver deletes the partially downloaded file when a download stops prematurely.

    Declaration

    Swift

    var deletesFileUponFailure: Bool

    Objective-C

    @property BOOL deletesFileUponFailure

    Parameters

    deletesFileUponFailure

    YEStrue if partially downloaded files should be deleted when a download stops prematurely, NOfalse otherwise. The default is YEStrue.

    Discussion

    To allow the download to be resumed in case the download ends prematurely you should call this method as soon as possible after starting the download.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.4 and later.

  • Cancels the receiver’s download and deletes the downloaded file.

    Declaration

    Swift

    func cancel()

    Objective-C

    - (void)cancel

    Discussion

    This method deletes the partially downloaded file unless you have previously called setDeletesFileUponFailure:, passing NOfalse.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.2 with Safari 1.0 installed.

    Available in OS X v10.2.7 and later.

  • Returns the request that initiated the receiver’s download.

    Declaration

    Swift

    @NSCopying var request: NSURLRequest { get }

    Objective-C

    @property(readonly, copy) NSURLRequest *request

    Return Value

    The URL request that initiated the receiver's download.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.2 with Safari 1.0 installed.

    Available in OS X v10.2.7 and later.

  • Returns whether the receiver deletes partially downloaded files when a download stops prematurely.

    Declaration

    Swift

    var deletesFileUponFailure: Bool

    Objective-C

    @property BOOL deletesFileUponFailure

    Return Value

    YEStrue if partially downloaded files should be deleted when a download stops prematurely, NOfalse otherwise. The default is YEStrue.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.4 and later.