NSURLDownload Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in OS X v10.2 with Safari 1.0 installed.
Available in OS X v10.2.7 and later.
Companion guide
Declared in
NSURLDownload.h
Related sample code

Overview

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.

The delegate object assigned to each instance of this class should implement the methods defined by the NSURLDownloadDelegate protocol. These methods provide the delegate with the current status of in-progress asynchronous downloads and allow the delegate to customize the URL loading process. These delegate methods are called on the thread that started the asynchronous load operation for the associated NSURLDownload object.

Tasks

Creating and Configuring a Download Instance

Resuming Partial Downloads

Canceling a Download

Getting Download Properties

Class Methods

canResumeDownloadDecodedWithEncodingMIMEType:

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

+ (BOOL)canResumeDownloadDecodedWithEncodingMIMEType:(NSString *)MIMEType
Parameters
MIMEType

The MIME type the caller wants to know about.

Return Value

YES if the URL download object can resume a download that was decoded with the specified MIME type, NO 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 NO 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 YES for MacBinary and BinHex, otherwise NO.

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

Availability
  • Available in OS X v10.4 and later.
Declared In
NSURLDownload.h

Instance Methods

cancel

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

- (void)cancel
Discussion

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

Availability
  • Available in OS X v10.2 with Safari 1.0 installed.
  • Available in OS X v10.2.7 and later.
Declared In
NSURLDownload.h

deletesFileUponFailure

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

- (BOOL)deletesFileUponFailure
Return Value

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

Availability
  • Available in OS X v10.4 and later.
Declared In
NSURLDownload.h

initWithRequest:delegate:

Returns an initialized URL download for a URL request and begins to download the data for the request.

- (id)initWithRequest:(NSURLRequest *)request delegate:(id)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.

Availability
  • Available in OS X v10.2 with Safari 1.0 installed.
  • Available in OS X v10.2.7 and later.
Declared In
NSURLDownload.h

initWithResumeData:delegate:path:

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

- (id)initWithResumeData:(NSData *)resumeData delegate:(id)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 NO. 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 NO, 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.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSURLDownload.h

request

Returns the request that initiated the receiver’s download.

- (NSURLRequest *)request
Return Value

The URL request that initiated the receiver's download.

Availability
  • Available in OS X v10.2 with Safari 1.0 installed.
  • Available in OS X v10.2.7 and later.
Declared In
NSURLDownload.h

resumeData

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

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

Availability
  • Available in OS X v10.4 and later.
Declared In
NSURLDownload.h

setDeletesFileUponFailure:

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

- (void)setDeletesFileUponFailure:(BOOL)deletesFileUponFailure
Parameters
deletesFileUponFailure

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

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSURLDownload.h

setDestination:allowOverwrite:

Sets the destination path of the downloaded file.

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

The path for the downloaded file.

allowOverwrite

YES if an existing file at path can be replaced, NO otherwise.

Discussion

If allowOverwrite is NO 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.

Availability
  • Available in OS X v10.2 with Safari 1.0 installed.
  • Available in OS X v10.2.7 and later.
Related Sample Code
Declared In
NSURLDownload.h