Inherits from | |
Conforms to | |
Framework | /System/Library/Frameworks/Foundation.framework |
Availability | Available in Mac OS X v10.2 with Safari 1.0 installed. Available in Mac OS X v10.2.7 and later. |
Companion guide | |
Declared in | NSURLDownload.h |
NSURLDownload downloads a request asynchronously and saves the data to a file. The interface for NSURLDownload is sparse, providing methods to initialize a download, set the destination path and cancel loading the request.
NSURLDownload’s delegate methods allow an object to receive informational callbacks about the asynchronous load of the 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.
A downloadDidBegin:
message will be sent to the delegate immediately upon starting the download.
Zero or more download:willSendRequest:redirectResponse:
messages will be sent to the delegate before any further messages are sent if it is determined that the download must redirect to a new location. The delegate can allow the redirect, modify the destination or deny the redirect.
Zero or more download:didReceiveAuthenticationChallenge:
messages will be sent to the delegate if it is necessary to authenticate in order to download the request and NSURLDownload does not already have authenticated credentials.
Zero or more download:didCancelAuthenticationChallenge:
messages will be sent to the delegate if NSURLDownload cancels the authentication challenge due to encountering a protocol implementation error.
Zero or more download:didReceiveResponse:
messages will be sent to the delegate before receiving a download:didReceiveDataOfLength:
message. The only case where download:didReceiveResponse:
is not sent to a delegate is when the protocol implementation encounters an error before a response could be created.
Zero or more download:didReceiveDataOfLength:
messages will be sent before downloadDidFinish:
or download:didFailWithError:
is sent to the delegate.
Zero or one download:decideDestinationWithSuggestedFilename:
will be sent to the delegate when sufficient information has been received to determine the suggested filename for the downloaded file. The delegate will not receive this message if setDestination:allowOverwrite:
has already been sent to the NSURLDownload instance.
A download:didCreateDestination:
message will be sent to the delegate when the NSURLDownload instance creates the file on disk.
If NSURLDownload determines that the downloaded file is in a format that it is able to decode (MacBinary, Binhex or gzip), the delegate will receive a download:shouldDecodeSourceDataOfMIMEType:
. The delegate should return YES
to decode the data, NO
otherwise.
Unless an NSURLDownload instance receives a cancel
message, the delegate will receive one and only one downloadDidFinish:
or download:didFailWithError:
message, but never both. In addition, once either of messages are sent, the delegate will receive no further messages for the given NSURLDownload.
+ canResumeDownloadDecodedWithEncodingMIMEType:
– initWithResumeData:delegate:path:
– resumeData
– setDeletesFileUponFailure:
– deletesFileUponFailure
– download:decideDestinationWithSuggestedFilename:
delegate method
– download:didCancelAuthenticationChallenge:
delegate method
– download:didCreateDestination:
delegate method
– download:didFailWithError:
delegate method
– download:didReceiveAuthenticationChallenge:
delegate method
– download:didReceiveDataOfLength:
delegate method
– download:didReceiveResponse:
delegate method
– download:shouldDecodeSourceDataOfMIMEType:
delegate method
– download:willSendRequest:redirectResponse:
delegate method
– downloadDidBegin:
delegate method
– downloadDidFinish:
delegate method
– download:willResumeWithResponse:fromByte:
delegate method
Returns whether a URL download object can resume a download that was decoded with the specified MIME type.
+ (BOOL)canResumeDownloadDecodedWithEncodingMIMEType:(NSString *)MIMEType
The MIME type the caller wants to know about.
YES
if the URL download object can resume a download that was decoded with the specified MIME type, NO
otherwise.
NSURLDownload cannot resume a download that was partially decoded in the gzip format.
NSURLDownload.h
Cancels the receiver’s download and deletes the downloaded file.
- (void)cancel
NSURLDownload.h
Returns whether the receiver deletes partially downloaded files when a download stops prematurely.
- (BOOL)deletesFileUponFailure
YES
if partially downloaded files should be deleted when a download stops prematurely, NO
otherwise. The default is YES
.
NSURLDownload.h
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
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.
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.
An initialized NSURLDownload object for request.
NSURLDownload.h
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
Specifies the data to resume downloading.
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 location for the downloaded data.
An initialized NSURLDownload object.
NSURLDownload.h
Returns the request that initiated the receiver’s download.
- (NSURLRequest *)request
The URL request that initiated the receiver's download.
NSURLDownload.h
Returns the resume data for a download that is not yet complete.
- (NSData *)resumeData
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.
Resume data will only be returned if the protocol of the download as well as the server support resuming. In order to later resume a download you must call setDeletesFileUponFailure:
passing NO
so the partially downloaded data is not deleted when the initial connection is lost or canceled.
NSURLDownload.h
Specifies whether the receiver deletes the partially downloaded file when a download stops prematurely.
- (void)setDeletesFileUponFailure:(BOOL)deletesFileUponFailure
YES
if partially downloaded files should be deleted when a download stops prematurely, NO
otherwise. The default is YES
.
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.
NSURLDownload.h
Sets the destination path of the downloaded file.
- (void)setDestination:(NSString *)path allowOverwrite:(BOOL)allowOverwrite
The path for the downloaded file.
YES
if an existing file at path can be replaced, NO
otherwise.
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 download:didCreateDestination:
to determine the filename used when the file is written to disk.
An NSURLDownload
instance ignores multiple calls to this method.
NSURLDownload.h
The delegate receives this message when download has determined a suggested filename for the downloaded file.
- (void)download:(NSURLDownload *)download decideDestinationWithSuggestedFilename:(NSString *)filename
The URL download object sending the message.
The suggested filename for the download.
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.
The delegate will not receive this message if setDestination:allowOverwrite:
has already been called for the download.
NSURLDownload.h
Sent if an authentication challenge is canceled due to the protocol implementation encountering an error.
- (void)download:(NSURLDownload *)download didCancelAuthenticationChallenge:(NSURLAuthenticationChallenge *)challenge
The URL download object sending the message.
The authentication challenge that caused the download object to cancel the download.
If the delegate receives this message the download will fail and the delegate will receive a download:didFailWithError:
message.
NSURLDownload.h
Sent when the destination file is created.
- (void)download:(NSURLDownload *)download didCreateDestination:(NSString *)path
The URL download object sending the message.
The path to the destination file.
NSURLDownload.h
Sent if the download fails or if an I/O error occurs when the file is written to disk.
- (void)download:(NSURLDownload *)download didFailWithError:(NSError *)error
The URL download object sending the message.
The error that caused the failure of the download.
Any partially downloaded file will be deleted.
Once the delegate receives this message, it will receive no further messages for download.
NSURLDownload.h
Sent when the URL download must authenticate a challenge in order to download the request.
- (void)download:(NSURLDownload *)download didReceiveAuthenticationChallenge:(NSURLAuthenticationChallenge *)challenge
The URL download object sending the message.
The URL authentication challenge that must be authenticated in order to download the request.
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 a user name and password, 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 will be 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.
NSURLDownload.h
Sent as a download object receives data incrementally.
- (void)download:(NSURLDownload *)download didReceiveDataOfLength:(NSUInteger)length
The URL download object sending the message.
The amount of data received in this increment of the download, measured in bytes.
NSURLDownload.h
Sent when a download object has received sufficient load data to construct the NSURLResponse object for the download.
- (void)download:(NSURLDownload *)download didReceiveResponse:(NSURLResponse *)response
The URL download object sending the message.
The URL response object received as part of the download. response is immutable and will not be modified after this method is called.
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.
NSURLDownload.h
Sent when a download object determines that the downloaded file is encoded to inquire whether the file should be automatically decoded.
- (BOOL)download:(NSURLDownload *)download shouldDecodeSourceDataOfMIMEType:(NSString *)encodingType
The URL download object sending the message.
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"
).
YES
to decode the file, NO
otherwise.
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.
NSURLDownload.h
Sent when a download object has received a response from the server after attempting to resume a download.
- (void)download:(NSURLDownload *)download willResumeWithResponse:(NSURLResponse *)response fromByte:(long long)startingByte
The URL download object sending the message.
The URL response received from the server in response to an attempt to resume a download.
The location of the start of the resumed data, in bytes.
NSURLDownload.h
Sent when the download object determines that it must change URLs in order to continue loading a request.
- (NSURLRequest *)download:(NSURLDownload *)download willSendRequest:(NSURLRequest *)request redirectResponse:(NSURLResponse *)redirectResponse
The URL download object sending the message.
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.
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.
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
.
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.
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.
NSURLDownload.h
Sent immediately after a download object begins a download.
- (void)downloadDidBegin:(NSURLDownload *)download
The URL download object sending the message.
NSURLDownload.h
Sent when a download object has completed downloading successfully and has written its results to disk.
- (void)downloadDidFinish:(NSURLDownload *)download
The URL download object sending the message.
The delegate will receive no further messages for download.
NSURLDownload.h
© 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-05-23)