# NSURLProtocol class documentation

Software documentation for the NSURLProtocol class
Foundation/NSURLProtocol.h

Subclasses of NSURLProtocol implement basic handling of URL loading for specific protocols. The NSURLProtocol class itsself is a semi-abstract class giving the essential structure for the subclasses.

You never instantiate NSURLProtocol yourself... it should only ever be done by other classes within the URL loading system.

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
propertyForKey:
key
inRequest:
request
Allows subclasses to provide access to proptocol specific properties, returning the property of request stored by the name key or `nil` if no property had been stored using that key in the request.
registerClass:
protocolClass
Registers the specified class so that it can be used to load requests.
When the system is determining which class to use to handle a request it examines them in a most recently registered first order.
The +canInitWithRequest: method is used to determine whether a class may be used to handle a particular request or not. Returns `YES` if registered (ie the class is an NSURLProtocol subclass), `NO` otherwise.
setProperty:
value
forKey:
key
inRequest:
request
Allows subclasses to provide a way to set protocol specific properties, setting the property named key to value in the request.
unregisterClass:
protocolClass
Unregisters a class which was previously registered using the +registerClass: method.
cachedResponse
Returns the cachedResponse of the receiver.
client
Returns the client associated with the receiver.
initWithRequest:
_request
cachedResponse:
_cachedResponse
client:
_client
Initialises the receiver with request, cachedResponse and client.
The cachedResponse may be the result of a previous load of the request (in which case the protocol may validate and use it).
The client is the object which receives messages about the progress of the load. This is retained by the protocl instance and is released once the last message has been sent to it.
initWithTask:
_task
cachedResponse:
_cachedResponse
client:
_client
Description forthcoming.
request
Returns the request handled by the receiver.
task
Returns the task handled by the receiver.
Software documentation for the NSURLProtocol(Subclassing) category
Foundation/NSURLProtocol.h
This category lists the methods which a subclass must implement in order to produce a working protocol.
canInitWithRequest:
request
This method is called to decide whether a class can deal with the specified request. The abstract class implementation raises an exception.
canonicalRequestForRequest:
request
Returns the 'canonical' version of the request.
The canonical form is used to look up requests in the cache by checking for equality.
The abnstract class implementation simply returns request.
requestIsCacheEquivalent:
a
toRequest:
b
Compares two requests for equivalence for caching purposes.
The abstract class implementaton just uses [NSObject -isEqual:]
startLoading
Starts loading of a request.
stopLoading
Stops loading of a request (eg when the load is cancelled).
Software documentation for the NSURLProtocolClient protocol
Foundation/NSURLProtocol.h
NSObject
Defines the API for NSURLProtocol loading
URLProtocol:
protocol
cachedResponseIsValid:
cachedResponse
Informs a client that a cached response is valid.
URLProtocol:
protocol
didCancelAuthenticationChallenge:
challenge
Informs a client that an authentication challenge has been cancelled.
URLProtocol:
protocol
didFailWithError:
error
Informs a client that loading of a request has failed.
URLProtocol:
protocol
didLoadData:
data
Informs a client that data has been loaded. Only new data since the last call to this method must be provided.
URLProtocol:
protocol
didReceiveAuthenticationChallenge:
challenge
Informs a client that an authentication challenge has been received.
URLProtocol:
protocol
didReceiveResponse:
response
cacheStoragePolicy:
policy
Informs a client that a response for the current load has been created.
Also supplies the policy to be used for caching the response.
URLProtocol:
protocol
wasRedirectedToRequest:
request
redirectResponse:
redirectResponse
Informs a client that a redirect has occurred.
URLProtocolDidFinishLoading:
protocol
Informs a client that loading of a request has successfully finished.