<!--
{
  "availability" : [
    "macOS: 10.2.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Foundation",
  "identifier" : "/documentation/Foundation/NSURLDownloadDelegate",
  "metadataVersion" : "0.1.0",
  "role" : "Protocol",
  "symbol" : {
    "kind" : "Protocol",
    "modules" : [
      "Foundation"
    ],
    "preciseIdentifier" : "c:objc(pl)NSURLDownloadDelegate"
  },
  "title" : "NSURLDownloadDelegate"
}
-->

# NSURLDownloadDelegate

A protocol that URL download delegates implement to interact with a URL download request.

```
protocol NSURLDownloadDelegate : NSObjectProtocol
```

## Overview

The [`NSURLDownloadDelegate`](/documentation/Foundation/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`](/documentation/Foundation/NSURLDownload) object.

- A [`downloadDidBegin(_:)`](/documentation/Foundation/NSURLDownloadDelegate/downloadDidBegin(_:)) message will be sent to the delegate immediately upon starting the download.
- Zero or more [`download(_:willSend:redirectResponse:)`](/documentation/Foundation/NSURLDownloadDelegate/download(_:willSend: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(_:didReceive:)`](/documentation/Foundation/NSURLDownloadDelegate/download(_:didReceive:)-1pc0v) 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(_:didCancel:)`](/documentation/Foundation/NSURLDownloadDelegate/download(_:didCancel:)) messages will be sent to the delegate if [`NSURLDownload`](/documentation/Foundation/NSURLDownload) cancels the authentication challenge due to encountering a protocol implementation error.
- Zero or more [`download(_:didReceive:)`](/documentation/Foundation/NSURLDownloadDelegate/download(_:didReceive:)-817z3) messages will be sent to the delegate before receiving a [`download(_:didReceiveDataOfLength:)`](/documentation/Foundation/NSURLDownloadDelegate/download(_:didReceiveDataOfLength:)) message. The only case where [`download(_:didReceive:)`](/documentation/Foundation/NSURLDownloadDelegate/download(_:didReceive:)-817z3) 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:)`](/documentation/Foundation/NSURLDownloadDelegate/download(_:didReceiveDataOfLength:)) messages will be sent before [`downloadDidFinish(_:)`](/documentation/Foundation/NSURLDownloadDelegate/downloadDidFinish(_:)) or [`download(_:didFailWithError:)`](/documentation/Foundation/NSURLDownloadDelegate/download(_:didFailWithError:)) is sent to the delegate.
- Zero or one [`download(_:decideDestinationWithSuggestedFilename:)`](/documentation/Foundation/NSURLDownloadDelegate/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:)`](/documentation/Foundation/NSURLDownload/setDestination(_:allowOverwrite:)) has already been sent to the [`NSURLDownload`](/documentation/Foundation/NSURLDownload) instance.
- A [`download(_:didCreateDestination:)`](/documentation/Foundation/NSURLDownloadDelegate/download(_:didCreateDestination:)) message will be sent to the delegate when the [`NSURLDownload`](/documentation/Foundation/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:)`](/documentation/Foundation/NSURLDownloadDelegate/download(_:shouldDecodeSourceDataOfMIMEType:)). The delegate should return <doc://com.apple.documentation/documentation/Swift/true> to decode the data, <doc://com.apple.documentation/documentation/Swift/false> otherwise.
- Unless an [`NSURLDownload`](/documentation/Foundation/NSURLDownload) instance receives a [`cancel()`](/documentation/Foundation/NSURLDownload/cancel()) message, the delegate will receive one and only one [`downloadDidFinish(_:)`](/documentation/Foundation/NSURLDownloadDelegate/downloadDidFinish(_:)) or [`download(_:didFailWithError:)`](/documentation/Foundation/NSURLDownloadDelegate/download(_:didFailWithError:)) message, but never both. In addition, once either of these messages are sent, the delegate will receive no further messages for the given [`NSURLDownload`](/documentation/Foundation/NSURLDownload).

## Topics

### Download Authentication

[`download(_:canAuthenticateAgainstProtectionSpace:)`](/documentation/Foundation/NSURLDownloadDelegate/download(_:canAuthenticateAgainstProtectionSpace:))

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

[`download(_:didCancel:)`](/documentation/Foundation/NSURLDownloadDelegate/download(_:didCancel:))

Sent if an authentication challenge is canceled due to the protocol implementation encountering an error.

[`download(_:didReceive:)`](/documentation/Foundation/NSURLDownloadDelegate/download(_:didReceive:)-1pc0v)

Sent when the URL download must authenticate a challenge in order to download the request.

[`downloadShouldUseCredentialStorage(_:)`](/documentation/Foundation/NSURLDownloadDelegate/downloadShouldUseCredentialStorage(_:))

Sent to determine whether the URL loader should consult the credential storage to authenticate the download.

### Download Data and Responses

[`download(_:decideDestinationWithSuggestedFilename:)`](/documentation/Foundation/NSURLDownloadDelegate/download(_:decideDestinationWithSuggestedFilename:))

The delegate receives this message when `download` has determined a suggested filename for the downloaded file.

[`downloadDidBegin(_:)`](/documentation/Foundation/NSURLDownloadDelegate/downloadDidBegin(_:))

Sent immediately after a download object begins a download.

[`download(_:didCreateDestination:)`](/documentation/Foundation/NSURLDownloadDelegate/download(_:didCreateDestination:))

Sent when the destination file is created.

[`download(_:didReceive:)`](/documentation/Foundation/NSURLDownloadDelegate/download(_:didReceive:)-817z3)

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

[`download(_:didReceiveDataOfLength:)`](/documentation/Foundation/NSURLDownloadDelegate/download(_:didReceiveDataOfLength:))

Sent as a download object receives data incrementally.

[`download(_:shouldDecodeSourceDataOfMIMEType:)`](/documentation/Foundation/NSURLDownloadDelegate/download(_:shouldDecodeSourceDataOfMIMEType:))

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

[`download(_:willResumeWith:fromByte:)`](/documentation/Foundation/NSURLDownloadDelegate/download(_:willResumeWith:fromByte:))

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

[`download(_:willSend:redirectResponse:)`](/documentation/Foundation/NSURLDownloadDelegate/download(_:willSend:redirectResponse:))

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

### Download Completion

[`download(_:didFailWithError:)`](/documentation/Foundation/NSURLDownloadDelegate/download(_:didFailWithError:))

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

[`downloadDidFinish(_:)`](/documentation/Foundation/NSURLDownloadDelegate/downloadDidFinish(_:))

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


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)