Up

# NSURLDownload class documentation

### Authors

Richard Frith-Macdonald (`frm@gnu.org`)

Date: Generated at 2025-02-13 06:02:40 +0000

Copyright: (C) 2006 Software Foundation, Inc.

### Contents -

1. Software documentation for the NSURLDownload class
2. Software documentation for the NSObject(NSURLDownloadDelegate) category

# Software documentation for the NSURLDownload class

## NSURLDownload : NSObject

> Declared in:
>   Foundation/NSURLDownload.h

Availability: MacOS-X 10.2.0, Base 1.13.0
Handles download to file.

Instance Variables
Method summary

- +canResumeDownloadDecodedWithEncodingMIMEType:
- -cancel
- -deletesFileUponFailure
- -initWithRequest:delegate:
- -initWithResumeData:delegate:path:
- -request
- -resumeData
- -setDeletesFileUponFailure:
- -setDestination:allowOverwrite:

### canResumeDownloadDecodedWithEncodingMIMEType:

+ (BOOL) canResumeDownloadDecodedWithEncodingMIMEType: (NSString*)MIMEType;
Availability: MacOS-X 10.2.0, Base 1.13.0
Returns a flag saying whether the class can resume a download which was decoded with MIMEType.

### cancel

- (void) cancel;
Availability: MacOS-X 10.2.0, Base 1.13.0
Cancels the download and deletes any downloaded file.

### deletesFileUponFailure

- (BOOL) deletesFileUponFailure;
Availability: MacOS-X 10.2.0, Base 1.13.0
Returns a flag saying whether a partially downloaded file should be deleted on failure... `YES` by default.

### initWithRequest: delegate:

- (id) initWithRequest: (NSURLRequest*)request delegate: (id)delegate;
Availability: MacOS-X 10.2.0, Base 1.13.0
Initialises the receiver and start the download process.

### initWithResumeData: delegate: path:

- (id) initWithResumeData: (NSData*)resumeData delegate: (id)delegate path: (NSString*)path;
Availability: MacOS-X 10.2.0, Base 1.13.0
This is a designated initialiser for the class.
Initialises the receiver with data from a previous partial download and resumes (or restarts) the downloading process.

### request

- (NSURLRequest*) request;
Availability: MacOS-X 10.2.0, Base 1.13.0
Returns the receiver's request.

### resumeData

- (NSData*) resumeData;
Availability: MacOS-X 10.2.0, Base 1.13.0
Returns state data of an incomplete download... this data should be sufficient to resume/restart the download using the -initWithResumeData:delegate:path: method.
Returns `nil` if a resume is probably impossible.
NB. You need to call -setDeletesFileUponFailure: to turn off deletion if you wish to be able to resume an incomplete download.

### setDeletesFileUponFailure:

- (void) setDeletesFileUponFailure: (BOOL)deletesFileUponFailure;
Availability: MacOS-X 10.2.0, Base 1.13.0
Sets a flag to determine if downloaded file is be deleted upon failure. This is `YES` by default and needs to be set to `NO` if you want to be able to attempt to resume a failed download.

### setDestination: allowOverwrite:

- (void) setDestination: (NSString*)path allowOverwrite: (BOOL)allowOverwrite;
Availability: MacOS-X 10.2.0, Base 1.13.0
Sets the path to which the file is downloaded.
May be called (once only) after initialisation of the receiver or when the delegate receives a -download:decideDestinationWithSuggestedFilename: message.
Appends a number to the filename if allowOverwrite is `NO` and a file already exists at path.
See -download:didCreateDestination: also.

## Instance Variables for NSURLDownload Class

### _NSURLDownloadInternal

@protected void* _NSURLDownloadInternal;
Availability: MacOS-X 10.2.0, Base 1.13.0
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

# Software documentation for the NSObject(NSURLDownloadDelegate) category

## NSObject(NSURLDownloadDelegate)

> Declared in:
>   Foundation/NSURLDownload.h

Availability: MacOS-X 10.2.0, Base 1.13.0
Protocol for delegate used to report the progress of the download.
Method summary

- -download:decideDestinationWithSuggestedFilename:
- -download:didCancelAuthenticationChallenge:
- -download:didCreateDestination:
- -download:didFailWithError:
- -download:didReceiveAuthenticationChallenge:
- -download:didReceiveDataOfLength:
- -download:didReceiveResponse:
- -download:shouldDecodeSourceDataOfMIMEType:
- -download:willResumeWithResponse:fromByte:
- -download:willSendRequest:redirectResponse:
- -downloadDidBegin:
- -downloadDidFinish:

### download: decideDestinationWithSuggestedFilename:

- (void) download: (NSURLDownload*)download decideDestinationWithSuggestedFilename: (NSString*)filename;
Availability: MacOS-X 10.2.0, Base 1.13.0
Called when it's time to establish a name for the downloaded file... the delegate may decide a name by inspecting the response.
The delegate should call -setDestination:allowOverwrite: to set the filename to be used.

### download: didCancelAuthenticationChallenge:

- (void) download: (NSURLDownload*)download didCancelAuthenticationChallenge: (NSURLAuthenticationChallenge*)challenge;
Availability: MacOS-X 10.2.0, Base 1.13.0
Called when authentication of a request is cancelled.

### download: didCreateDestination:

- (void) download: (NSURLDownload*)download didCreateDestination: (NSString*)path;
Availability: MacOS-X 10.2.0, Base 1.13.0
Called when the download has created the downloaded file.

### download: didFailWithError:

- (void) download: (NSURLDownload*)download didFailWithError: (NSError*)error;
Availability: MacOS-X 10.2.0, Base 1.13.0
Called when the download fails.

### download: didReceiveAuthenticationChallenge:

- (void) download: (NSURLDownload*)download didReceiveAuthenticationChallenge: (NSURLAuthenticationChallenge*)challenge;
Availability: MacOS-X 10.2.0, Base 1.13.0
Called when an authentication challenge is received.
The delegate should send -useCredential:forAuthenticationChallenge: or -continueWithoutCredentialForAuthenticationChallenge: or -cancel to the connection sender when done.

### download: didReceiveDataOfLength:

- (void) download: (NSURLDownload*)download didReceiveDataOfLength: (NSUInteger)length;
Availability: MacOS-X 10.2.0, Base 1.13.0
Called when some data has been received.

### download: didReceiveResponse:

- (void) download: (NSURLDownload*)download didReceiveResponse: (NSURLResponse*)response;
Availability: MacOS-X 10.2.0, Base 1.13.0
Called when a response is received.
Multiple responses may be received on the same download (eg with server push) and the delegate should be prepared to treat each separately.

### download: shouldDecodeSourceDataOfMIMEType:

- (BOOL) download: (NSURLDownload*)download shouldDecodeSourceDataOfMIMEType: (NSString*)encodingType;
Availability: MacOS-X 10.2.0, Base 1.13.0
Called if the download file is encoded... the delegate should return `YES` if the downloaded data is to be decoded, `NO` otherwise.

### download: willResumeWithResponse: fromByte:

- (void) download: (NSURLDownload*)download willResumeWithResponse: (NSURLResponse*)response fromByte: (long long)startingByte;
Availability: MacOS-X 10.2.0, Base 1.13.0
Called when a download is resuming from previously stored data and a response has been received from the server.
The startingBytes is the offset from which the downloaded data will actually commence... and may be zero if the entire download must be redone.

### download: willSendRequest: redirectResponse:

- (NSURLRequest*) download: (NSURLDownload*)download willSendRequest: (NSURLRequest*)request redirectResponse: (NSURLResponse*)redirectResponse;
Availability: MacOS-X 10.2.0, Base 1.13.0
Called if a new request has to be sent due to redirection.
Must return the request argument (or a modified copy of it) to have the process continue.

### downloadDidBegin:

- (void) downloadDidBegin: (NSURLDownload*)download;
Availability: MacOS-X 10.2.0, Base 1.13.0
Called immediately once the download has started.

### downloadDidFinish:

- (void) downloadDidFinish: (NSURLDownload*)download;
Availability: MacOS-X 10.2.0, Base 1.13.0
Called when the download completes after having received all data.

Up