Download files directly to the filesystem.
For network resources that are already stored as files, like images and documents, you can use download tasks to fetch these items directly to the local filesystem.
For Simple Downloads, Use a Completion Handler
To download files, you create an
NSURLSession from an
NSURLSession. If you don’t care about receiving progress updates or other delegate callbacks during the download, you can use a completion handler. The task calls the completion handler when the download ends, either at the end of a successful download or when downloading fails.
Your completion handler may receive a client-side error, indicating a local problem like not being able to reach the network. If there is no client-side error, you also receive an
NSURLResponse, which you should inspect to ensure that it indicates a successful response from the server.
If the download is successful, your completion handler receives a URL indicating the location of the downloaded file on the local filesystem. This storage is temporary. If you want to preserve the file, you must copy or move it from this location before returning from the completion handler.
Listing 1 shows a simple example of creating a download task with a completion handler. If no errors are indicated, the completion handler moves the downloaded file to the app’s
Documents directory. Start the task by calling
To Receive Progress Updates, Use a Delegate
If you want to receive progress updates as the download proceeds, you must use a delegate. Instead of receiving the results in a completion handler, you receive callbacks to your implementations of methods from the
Create your own
NSURLSession instance, and set its
delegate property. Listing 2 shows a lazily instantiated
url property that sets
self as its delegate.
To start downloading, use this
NSURLSession to create a
NSURLSession, and then start the task by calling
resume, as shown in Listing 3.
Receive Progress Updates
Once the download starts, you receive periodic progress updates in the
URLSession:. You can use the byte counts provided by this callback to update a progress UI in your app.
Listing 4 shows an implementation of this callback method. This implementation calculates the fractional progress of the download, and uses it to update a label that shows progress as a percentage. Because the callback is performed on an unknown Grand Central Dispatch queue, you must explicitly perform the UI update on the main queue.
Handle Download Completion or Errors in Your Delegate
When you use a delegate instead of a completion handler, you handle the completion of the download by implementing
URLSession:. Check the
response property to ensure that the server response indicates success. If so, the
location parameter provides a local URL where the file has been stored. This location is valid only until the end of the callback. This means you must either read the file immediately, or move it to another location such as the app’s
Documents directory before you return from the callback method. Listing 5 shows how to preserve the downloaded file.
If a client-side error occurs, your delegate receives it in a callback to the
URLSession: delegate method. On the other hand, if the download completes successfully, this method is called after
URLSession: and the error is