NSURLProtocol Class Reference

Inherits from
NSObject
Conforms to
NSObject (NSObject)
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in iOS 2.0 and later.
Companion guide
URL Loading System Programming Guide
Declared in
NSURLProtocol.h

Overview

NSURLProtocol is an abstract class that provides the basic structure for performing protocol-specific loading of URL data. Concrete subclasses handle the specifics associated with one or more protocols or URL schemes.

An application should never need to directly instantiate an NSURLProtocol subclass. The instance of the appropriate NSURLProtocol subclass for an NSURLRequest is created by NSURLConnection when a download is started.

The NSURLProtocolClient protocol describes the methods an implementation uses to drive the URL loading system from a NSURLProtocol subclass.

To support customization of protocol-specific requests, protocol implementors are encouraged to provide categories on NSURLRequest and NSMutableURLRequest. Protocol implementors who need to extend the capabilities of NSURLRequest and NSMutableURLRequest in this way can store and retrieve protocol-specific request data by using NSURLProtocol’s class methods propertyForKey:inRequest: and setProperty:forKey:inRequest:.

An essential responsibility for a protocol implementor is creating a NSURLResponse for each request it processes successfully. A protocol implementor may wish to create a custom, mutable NSURLResponse class to provide protocol specific information.

Tasks

Creating Protocol Objects

Registering and Unregistering Protocol Classes

Getting and Setting Request Properties

Determining If a Subclass Can Handle a Request

Providing a Canonical Version of a Request

Determining If Requests Are Cache Equivalent

Starting and Stopping Downloads

Getting Protocol Attributes

Class Methods

canInitWithRequest:

Returns whether the protocol subclass can handle the specified request.

+ (BOOL)canInitWithRequest:(NSURLRequest *)request
Parameters
request

The request to be handled.

Return Value

YES if the protocol subclass can handle request, otherwise NO.

Discussion

A subclass should inspect request and determine whether or not the implementation can perform a load with that request.

This is an abstract method and subclasses must provide an implementation.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSURLProtocol.h

canonicalRequestForRequest:

Returns a canonical version of the specified request.

+ (NSURLRequest *)canonicalRequestForRequest:(NSURLRequest *)request
Parameters
request

The request whose canonical version is desired.

Return Value

The canonical form of request.

Discussion

It is up to each concrete protocol implementation to define what “canonical” means. A protocol should guarantee that the same input request always yields the same canonical form.

Special consideration should be given when implementing this method, because the canonical form of a request is used to lookup objects in the URL cache, a process which performs equality checks between NSURLRequest objects.

This is an abstract method and subclasses must provide an implementation.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSURLProtocol.h

propertyForKey:inRequest:

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

+ (id)propertyForKey:(NSString *)key inRequest:(NSURLRequest *)request
Parameters
key

The key of the desired property.

request

The request whose properties are to be queried.

Return Value

The property associated with key, or nil if no property has been stored for key.

Discussion

This method provides an interface for protocol implementors to access protocol-specific information associated with NSURLRequest objects.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
NSURLProtocol.h

registerClass:

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

+ (BOOL)registerClass:(Class)protocolClass
Parameters
protocolClass

The subclass of NSURLProtocol to register.

Return Value

YES if the registration is successful, NO otherwise. The only failure condition is if protocolClass is not a subclass of NSURLProtocol.

Discussion

When the URL loading system begins to load a request, each registered protocol class is consulted in turn to see if it can be initialized with the specified request. The first NSURLProtocol subclass to return YES when sent a canInitWithRequest: message is used to perform the URL load. There is no guarantee that all registered protocol classes will be consulted.

Classes are consulted in the reverse order of their registration. A similar design governs the process to create the canonical form of a request with canonicalRequestForRequest:.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
NSURLProtocol.h

removePropertyForKey:inRequest:

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

+ (void)removePropertyForKey:(NSString *)key inRequest:(NSMutableURLRequest *)request
Parameters
key

The key whose value should be removed.

request

The request from which to remove the property value.

Discussion

This method is used to provide an interface for protocol implementors to customize protocol-specific information associated with NSMutableURLRequest objects.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
NSURLProtocol.h

requestIsCacheEquivalent:toRequest:

Returns whether two requests are equivalent for cache purposes.

+ (BOOL)requestIsCacheEquivalent:(NSURLRequest *)aRequest toRequest:(NSURLRequest *)bRequest
Parameters
aRequest

The request to compare with bRequest.

bRequest

The request to compare with aRequest.

Return Value

YES if aRequest and bRequest are equivalent for cache purposes, NO otherwise. Requests are considered equivalent for cache purposes if and only if they would be handled by the same protocol and that protocol declares them equivalent after performing implementation-specific checks.

Discussion

The NSURLProtocol implementation of this method compares the URLs of the requests to determine if the requests should be considered equivalent. Subclasses can override this method to provide protocol-specific comparisons.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSURLProtocol.h

setProperty:forKey:inRequest:

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

+ (void)setProperty:(id)value forKey:(NSString *)key inRequest:(NSMutableURLRequest *)request
Parameters
value

The value to set for the specified property.

key

The key for the specified property.

request

The request for which to create the property.

Discussion

This method is used to provide an interface for protocol implementors to customize protocol-specific information associated with NSMutableURLRequest objects.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
NSURLProtocol.h

unregisterClass:

Unregisters the specified subclass of NSURLProtocol.

+ (void)unregisterClass:(Class)protocolClass
Parameters
protocolClass

The subclass of NSURLProtocol to unregister.

Discussion

After this method is invoked, protocolClass is no longer consulted by the URL loading system.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
NSURLProtocol.h

Instance Methods

cachedResponse

Returns the receiver’s cached response.

- (NSCachedURLResponse *)cachedResponse
Return Value

The receiver's cached response.

Discussion

If not overridden in a subclass, this method returns the cached response stored at initialization time.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSURLProtocol.h

client

Returns the object the receiver uses to communicate with the URL loading system.

- (id < NSURLProtocolClient >)client
Return Value

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

Availability
  • Available in iOS 2.0 and later.
Declared In
NSURLProtocol.h

initWithRequest:cachedResponse:client:

Initializes an NSURLProtocol object.

- (id)initWithRequest:(NSURLRequest *)request cachedResponse:(NSCachedURLResponse *)cachedResponse client:(id < NSURLProtocolClient >)client
Parameters
request

The URL request for the URL protocol object. This request is retained.

cachedResponse

A cached response for the request; may be nil if there is no existing cached response for the request.

client

An object that provides an implementation of the NSURLProtocolClient protocol that the receiver uses to communicate with the URL loading system. This client object is retained.

Discussion

Subclasses should override this method to do any custom initialization. An application should never explicitly call this method.

This is the designated intializer for NSURLProtocol.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSURLProtocol.h

request

Returns the receiver’s request.

- (NSURLRequest *)request
Return Value

The receiver's request.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSURLProtocol.h

startLoading

Starts protocol-specific loading of the request.

- (void)startLoading
Discussion

When this method is called, the subclass implementation should start loading the request, providing feedback to the URL loading system via the NSURLProtocolClient protocol.

Subclasses must implement this method.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
NSURLProtocol.h

stopLoading

Stops protocol-specific loading of the request.

- (void)stopLoading
Discussion

When this method is called, the subclass implementation should stop loading a request. This could be in response to a cancel operation, so protocol implementations must be able to handle this call while a load is in progress. When your protocol receives a call to this method, it should also stop sending notifications to the client.

Subclasses must implement this method.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
NSURLProtocol.h


© 2011 Apple Inc. All Rights Reserved. (Last updated: 2011-05-04)

Did this document help you? Yes It's good, but... Not helpful...