The URL loading system is a set of classes and protocols that provide the underlying capability for an application to access the data specified by a URL.
These classes fall into five categories: URL loading, cache management, authentication and credentials, cookie storage, and protocol support.
The most commonly used classes in the URL loading system allow an application to create a request for the content of a URL and download it from the source.
A request for the contents of a URL is represented by an NSURLRequest
object. The NSURLRequest
class encapsulates a URL and any protocol-specific properties, in a protocol-independent manner. It also provides an interface to set the timeout for a connection and specifies the policy regarding the use of any locally cached data. The NSMutableURLRequest
class is a mutable subclass of NSURLRequest
that allows a client application to alter an existing request.
Note: When a client application initiates a connection or download using an instance of NSMutableURLRequest
, a deep copy is made of the request. Changes made to the initiating request have no effect once a download has been initialized.
Protocols, such as HTTP, that support protocol-specific properties must create categories on the NSURLRequest
and NSMutableURLRequest
classes to provide accessors for those properties. As an example, the HTTP protocol adds methods to NSURLRequest
to return the HTTP request body, headers, and transfer method. It also adds methods to NSMutableURLRequest
to set the corresponding values. Methods for setting and getting property values in those accessors are exposed in the NSURLProtocol
class.
The response from a server to a request can be viewed as two parts: metadata describing the contents and the URL content data. The metadata that is common to most protocols is encapsulated by the NSURLResponse
class and consists of the MIME type, expected content length, text encoding (where applicable), and the URL that provided the response. Protocols can create subclasses of NSURLResponse
to store protocol-specific metadata. NSHTTPURLResponse
, for example, stores the headers and the status code returned by the web server.
Note: It’s important to remember that only the metadata for the response is stored in an NSURLResponse
object. An NSCachedURLResponse
instance is used to encapsulate an NSURLResponse
, the URL content data, and any application-provided information. See “Cache Management” for details.
The NSURLConnection
and NSURLDownload
classes provide the interface to make a connection specified by an NSURLRequest
object and download the contents. An NSURLConnection
object provides data to the delegate as it is received from the originating source, whereas an NSURLDownload
object writes the request data directly to disk. Both classes provide extensive delegate support for responding to redirects, authentication challenges, and error conditions.
the NSURLConnection
class provides a delegate method that allows an application to control the caching of a response on a per-request basis. Downloads initiated by an NSURLDownload
instance are not cached.
The URL loading system provides a composite on-disk and in-memory cache allowing an application to reduce its dependence on a network connection and provide faster turnaround for previously cached responses. The cache is stored on a per-application basis.
The cache is queried by NSURLConnection
according to the cache policy specified by the initiating NSURLRequest
.
The NSURLCache
class provides methods to configure the cache size and its location on disk. It also provides methods to manage the collection of NSCachedURLResponse
objects that contain the cached responses.
An NSCachedURLResponse
object encapsulates the NSURLResponse
and the URL content data. NSCachedURLResponse
also provides a user info dictionary that can be used by an application to cache any custom data.
Not all protocol implementations support response caching. Currently only http
and https
requests are cached, and https
requests are never cached to disk.
An NSURLConnection
can control whether a response is cached and whether the response should be cached only in memory by implementing the connection:willCacheResponse:
delegate method.
Some servers restrict access to certain content, requiring a user to authenticate with a valid user name and password in order to gain access. In the case of a web server, restricted content is grouped together into a realm that requires a single set of credentials.
The URL loading system provides classes that model credentials and protected areas as well as providing secure credential persistence. Credentials can be specified to persist for a single request, for the duration of an application’s launch, or permanently in the user’s keychain.
Note: Credentials stored in persistent storage are kept in the user's keychain and shared among all applications.
The NSURLCredential
class encapsulates a credential consisting of the user name, password, and the type of persistence to use. The NSURLProtectionSpace
class represents an area that requires a specific credential. A protection space can be limited to a single URL, encompass a realm on a web server, or refer to a proxy.
A shared instance of the NSURLCredentialStorage
class manages credential storage and provides the mapping of an NSURLCredential
object to the corresponding NSURLProtectionSpace
object for which it provides authentication.
The NSURLAuthenticationChallenge
class encapsulates the information required by an NSURLProtocol
implementation to authenticate a request: a proposed credential, the protection space involved, the error or response that the protocol used to determine that authentication is required, and the number of authentication attempts that have been made. An NSURLAuthenticationChallenge
instance also specifies the object that initiated the authentication. The initiating object, referred to as the sender, must conform to the NSURLAuthenticationChallengeSender
protocol.
NSURLAuthenticationChallenge
instances are used by NSURLProtocol
subclasses to inform the URL loading system that authentication is required. They are also provided to the delegate methods of NSURLConnection
and NSURLDownload that facilitate customized authentication handling.
Due to the stateless nature of the HTTP protocol, cookies are often used to provide persistent storage of data across URL requests. The URL loading system provides interfaces to create and manage cookies as well as sending and receiving cookies from web servers.
The NSHTTPCookie
class encapsulates a cookie, providing accessors for many of the common cookie attributes. It also provides methods to convert HTTP cookie headers to NSHTTPCookie
instances and convert an NSHTTPCookie instance to headers suitable for use with an NSURLRequest
. The URL loading system automatically sends any stored cookies appropriate for an NSURLRequest
. unless the request specifies not to send cookies. Likewise, cookies returned in an NSURLResponse
are accepted in accordance with the current cookie acceptance policy.
The NSHTTPCookieStorage
class provides the interface for managing the collection of NSHTTPCookie
objects shared by all applications.
NSHTTPCookieStorage
allows an application to specify a cookie acceptance policy. The cookie acceptance policy controls whether cookies should always be accepted, never be accepted, or accepted only from the same domain as the main document URL.
Note: Changing the cookie acceptance policy in an application affects the cookie acceptance policy for all other running applications.
When another application changes the cookie storage or the cookie acceptance policy, NSHTTPCookieStorage
notifies an application by posting the NSHTTPCookieStorageCookiesChangedNotification
and NSHTTPCookieStorageAcceptPolicyChangedNotification
notifications.
The URL loading system design allows a client application to extend the protocols that are supported for transferring data. The URL loading system natively supports http
, https
, file
, and ftp
protocols.
Custom protocols are implemented by subclassing NSURLProtocol
and then registering the new class with the URL loading system using the NSURLProtocol
class method registerClass:
. When an NSURLConnection
or NSURLDownload object initiates a connection for an NSURLRequest, the URL loading system consults each of the registered classes in the reverse order of their registration. The first class that returns YES
for a canInitWithRequest:
message is used to handle the request.
The URL loading system is responsible for creating and releasing NSURLProtocol
instances when connections start and complete. An application should never create an instance of NSURLProtocol
directly.
When an NSURLProtocol
subclass is initialized by the URL loading system, it is provided a client object that conforms to the NSURLProtocolClient protocol. The NSURLProtocol
subclass sends messages from the NSURLProtocolClient protocol to the client object to inform the URL loading system of its actions as it creates a response, receives data, redirects to a new URL, requires authentication, and completes the load. If the custom protocol supports authentication, then it must conform to the NSURLAuthenticationChallengeSender protocol.
Last updated: 2010-03-24