Class

NSURLProtocol

An abstract class that handles the loading of protocol-specific URL data.

Declaration

@interface NSURLProtocol : NSObject

Overview

Don't instantiate an NSURLProtocol subclass directly. Instead, create subclasses for any custom protocols or URL schemes that your app supports. When a download starts, the system creates the appropriate protocol object to handle the corresponding URL request. You define your protocol class and call the registerClass: class method during your app’s launch time so that the system is aware of your protocol.

To support the customization of protocol-specific requests, define categories on NSURLRequest and NSMutableURLRequest with any custom API that you need. You can store and retrieve protocol-specific request data by using NSURLProtocol’s class methods propertyForKey:inRequest: and setProperty:forKey:inRequest:.

Create a NSURLResponse for each request your subclass processes successfully. You may want to create a custom, mutable NSURLResponse class to provide protocol specific information.

Subclassing Notes

When overriding methods of this class, be aware that methods that take a task parameter are preferred by the system to those that do not. Therefore, you should override the task-based methods when subclassing, as follows:

Topics

Creating Protocol Objects

initWithRequest:cachedResponse:client:

Creates a URL protocol instance to handle the request.

initWithTask:cachedResponse:client:

Creates a URL protocol instance to handle the task.

Registering and Unregistering Protocol Classes

registerClass:

Attempts to register a subclass of NSURLProtocol, making it visible to the URL loading system.

unregisterClass:

Unregisters the specified subclass of NSURLProtocol.

Determining If a Subclass Can Handle a Request

canInitWithRequest:

Determines whether the protocol subclass can handle the specified request.

canInitWithTask:

Determines whether the protocol subclass can handle the specified task.

Getting and Setting Request Properties

propertyForKey:inRequest:

Fetches the property associated with the specified key in the specified request.

setProperty:forKey:inRequest:

Sets the property associated with the specified key in the specified request.

removePropertyForKey:inRequest:

Removes the property associated with the specified key in the specified request.

Providing a Canonical Version of a Request

canonicalRequestForRequest:

Returns a canonical version of the specified request.

Determining If Requests Are Cache Equivalent

requestIsCacheEquivalent:toRequest:

A Boolean value indicating whether two requests are equivalent for cache purposes.

Starting and Stopping Downloads

startLoading

Starts protocol-specific loading of the request.

stopLoading

Stops protocol-specific loading of the request.

Getting Protocol Attributes

cachedResponse

The protocol’s cached response.

client

The object the protocol uses to communicate with the URL loading system.

NSURLProtocolClient

The interface used by NSURLProtocol subclasses to communicate with the URL Loading System.

request

The protocol’s request.

task

The protocol’s task.

Relationships

Inherits From

See Also

Supporting Custom Protocols

protocolClasses

An array of extra protocol subclasses that handle requests in a session.