URL Loading System Programming Guide - Apple Developer

More documents

Recommendations

Info

Life Cycle of a URL Session You can use the NSURLSession API in two ways: with a system-provided delegate or with your own delegate. In general, you must use your own delegate if your app does any of the following: ● ● ● ● ● ● ● Uses background sessions to download or upload content while your app is not running. Performs custom authentication. Performs custom SSL certificate verification. Decides whether a transfer should be downloaded to disk or displayed based on the MIME type returned by the server or other similar criteria. Uploads data from a body stream (as opposed to an NSData object). Limits caching programmatically. Limits HTTP redirects programmatically. If your app does not need to do any of these things, your app can use the system-provided delegates. Depending on which technique you choose, you should read one of the following sections: ● ● “Life Cycle of a URL Session with System-Provided Delegates” (page 64) provides a lightweight view of how your code creates and uses a URL session. You should read this section even if you intend to write your own delegate, because it gives you a complete picture of what your code must do to configure the object and use it. “Life Cycle of a URL Session with Custom Delegates” (page 66) provides a complete view of every step in the operation of a URL session. You should refer to this section to help you understand how the session interacts with its delegate. In particular, this explains when each of the delegate methods is called. Life Cycle of a URL Session with System-Provided Delegates If you are using the NSURLSession class without providing a delegate object, the system-provided delegate handles many of the details for you. Here is the basic sequence of method calls that your app must make and completion handler calls that your app receives when using NSURLSession with the system-provided delegate: 1. Create a session configuration. For background sessions, this configuration must contain a unique identifier. Store that identifier, and use it to reassociate with the session if your app crashes or is terminated or suspended. 2013-10-22 | Copyright © 2003, 2013 Apple Inc. All Rights Reserved. 64
Life Cycle of a URL Session Life Cycle of a URL Session with System-Provided Delegates 2. Create a session, specifying a configuration object and a nil delegate. 3. Create task objects within a session that each represent a resource request. Each task starts out in a suspended state. After your app calls resume on the task, it begins downloading the specified resource. The task objects are subclasses of NSURLSessionTask—NSURLSessionDataTask, NSURLSessionUploadTask, or NSURLSessionDownloadTask, depending on the behavior you are trying to achieve. These objects are analogous to NSURLConnection objects, but give you more control and a unified delegate model. Although your app can (and typically should) add more than one task to a session, for simplicity, the remaining steps describe the life cycle in terms of a single task. Important: If you are using the NSURLSession class without providing delegates, your app must create tasks using a call that takes a completionHandler parameter, because otherwise it cannot obtain data from the class. 4. For a download task, during the transfer from the server, if the user tells your app to pause the download, cancel the task by calling cancelByProducingResumeData: method. Later, pass the returned resume data to either the downloadTaskWithResumeData: or downloadTaskWithResumeData:completionHandler: method to create a new download task that continues the download. 5. When a task completes, the NSURLSession object calls the task’s completion handler. Note: NSURLSession does not report server errors through the error parameter. The only errors your app receives through the error parameter are client-side errors, such as being unable to resolve the hostname or connect to the host. The error codes are described in URL Loading System Error Codes. Server-side errors are reported through the HTTP status code in the NSHTTPURLResponse object. For more information, read the documentation for the NSHTTPURLResponse and NSURLResponse classes. 6. When your app no longer needs a session, invalidate it by calling either invalidateAndCancel (to cancel outstanding tasks) or finishTasksAndInvalidate (to allow outstanding tasks to finish before invalidating the object). 2013-10-22 | Copyright © 2003, 2013 Apple Inc. All Rights Reserved. 65
Page 1 and 2:
URL Loading System Programming Guid
Page 3 and 4:
Contents Making a POST Request 36 R
Page 5 and 6:
Listings Understanding Cache Access
Page 7 and 8:
About the URL Loading System At a G
Page 9 and 10:
Page 11 and 12:
Page 13 and 14: About the URL Loading System How to
Page 15 and 16: Using NSURLSession The NSURLSession
Page 17 and 18: Using NSURLSession Understanding UR
Page 19 and 20: Using NSURLSession Creating and Con
Page 21 and 22: Using NSURLSession Creating and Con
Page 23 and 24: Using NSURLSession Fetching Data Us
Page 25 and 26: Using NSURLSession Downloading File
Page 27 and 28: Using NSURLSession Uploading Body C
Page 29 and 30: Using NSURLSession Handling iOS Bac
Page 31 and 32: Using NSURLSession Handling iOS Bac
Page 33 and 34: Using NSURLConnection Creating a Co
Page 35 and 36: Using NSURLConnection Creating a Co
Page 37 and 38: Using NSURLConnection Making a POST
Page 39 and 40: Using NSURLConnection Retrieving Da
Page 41 and 42: Using NSURLDownload Downloading to
Page 43 and 44: Using NSURLDownload Downloading a F
Page 45 and 46: Using NSURLDownload Displaying Down
Page 47 and 48: Using NSURLDownload Decoding Encode
Page 49 and 50: Encoding URL Data CFStringRef decod
Page 51 and 52: Handling Redirects and Other Reques
Page 53 and 54: Authentication Challenges and TLS C
Page 59 and 60: Understanding Cache Access Cache Us
Page 61 and 62: Understanding Cache Access Controll
Page 63: Cookies and Custom Protocols Protoc
Page 67 and 68: Life Cycle of a URL Session Life Cy
Page 69 and 70: Life Cycle of a URL Session Life Cy
Page 71 and 72: Document Revision History Date 2003
show all

URL Loading System Programming Guide - Apple Developer

Create successful ePaper yourself

Delete template?

Save as template?