Up

# NSURLProtocol class documentation

### Authors

Generated by root

### Contents -

1. Software documentation for the NSURLProtocol class
2. Software documentation for the NSURLProtocol(Subclassing) category
3. Software documentation for the NSURLProtocolClient protocol

# Software documentation for the NSURLProtocol class

## NSURLProtocol : NSObject

> Declared in:
>   Foundation/NSURLProtocol.h

Availability: MacOS-X 10.2.0, Base 1.13.0

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 mthe URL loading system.

Instance Variables
Method summary

- +canInitWithRequest:
- +canonicalRequestForRequest:
- +requestIsCacheEquivalent:toRequest:
- -startLoading
- -stopLoading
- +propertyForKey:inRequest:
- +registerClass:
- +setProperty:forKey:inRequest:
- +unregisterClass:
- -cachedResponse
- -client
- -initWithRequest:cachedResponse:client:
- -request

### propertyForKey: inRequest:

+ (id) propertyForKey: (NSString*)key inRequest: (NSURLRequest*)request;
Availability: MacOS-X 10.2.0, Base 1.13.0
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:

+ (BOOL) registerClass: (Class)protocolClass;
Availability: MacOS-X 10.2.0, Base 1.13.0
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: forKey: inRequest:

+ (void) setProperty: (id)value forKey: (NSString*)key inRequest: (NSMutableURLRequest*)request;
Availability: MacOS-X 10.2.0, Base 1.13.0
Allows subclasses to provide a way to set protocol specific properties, setting the property named key to value in the request.

### unregisterClass:

+ (void) unregisterClass: (Class)protocolClass;
Availability: MacOS-X 10.2.0, Base 1.13.0
Unregisters a class which was previously registered using the +registerClass: method.

### cachedResponse

- (NSCachedURLResponse*) cachedResponse;
Availability: MacOS-X 10.2.0, Base 1.13.0
Returns the cachedResponse of the receiver.

### client

- (id<NSURLProtocolClient>) client;
Availability: MacOS-X 10.2.0, Base 1.13.0
Returns the client associated with the receiver.

### initWithRequest: cachedResponse: client:

- (id) initWithRequest: (NSURLRequest*)request cachedResponse: (NSCachedURLResponse*)cachedResponse client: (id<NSURLProtocolClient>)client;
Availability: MacOS-X 10.2.0, Base 1.13.0
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.

### request

- (NSURLRequest*) request;
Availability: MacOS-X 10.2.0, Base 1.13.0
Returns the request handled by the receiver.

## Instance Variables for NSURLProtocol Class

### _NSURLProtocolInternal

@protected void* _NSURLProtocolInternal;
Availability: MacOS-X 10.2.0, Base 1.13.0
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.

# Software documentation for the NSURLProtocol(Subclassing) category

## NSURLProtocol(Subclassing)

> Declared in:
>   Foundation/NSURLProtocol.h

Availability: MacOS-X 10.2.0, Base 1.13.0
This category lists the methods which a subclass must implement in order to produce a working protocol.
Method summary

- +canInitWithRequest:
- +canonicalRequestForRequest:
- +requestIsCacheEquivalent:toRequest:
- -startLoading
- -stopLoading

### canInitWithRequest:

+ (BOOL) canInitWithRequest: (NSURLRequest*)request;
Availability: MacOS-X 10.2.0, Base 1.13.0
Subclasses must override this method.
This method is called to decide whether a class can deal with the specified request. The abstract class implementation raises an exception.

### canonicalRequestForRequest:

+ (NSURLRequest*) canonicalRequestForRequest: (NSURLRequest*)request;
Availability: MacOS-X 10.2.0, Base 1.13.0
Subclasses must override this method.
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: toRequest:

+ (BOOL) requestIsCacheEquivalent: (NSURLRequest*)a toRequest: (NSURLRequest*)b;
Availability: MacOS-X 10.2.0, Base 1.13.0
Subclasses must override this method.
Compares two requests for equivalence for caching purposes.
The abstract class implementaton just uses [NSObject -isEqual:]

### startLoading

- (void) startLoading;
Availability: MacOS-X 10.2.0, Base 1.13.0
Subclasses must override this method.
Starts loading of a request.

### stopLoading

- (void) stopLoading;
Availability: MacOS-X 10.2.0, Base 1.13.0
Subclasses must override this method.
Stops loading of a request (eg when the load is cancelled).

# Software documentation for the NSURLProtocolClient protocol

## NSURLProtocolClient

> Declared in:
>   Foundation/NSURLProtocol.h

> Conforms to:
>   NSObject

Availability: MacOS-X 10.2.0, Base 1.13.0
Defines the API for NSURLProtocol loading
Method summary

- -URLProtocol:cachedResponseIsValid:
- -URLProtocol:didCancelAuthenticationChallenge:
- -URLProtocol:didFailWithError:
- -URLProtocol:didLoadData:
- -URLProtocol:didReceiveAuthenticationChallenge:
- -URLProtocol:didReceiveResponse:cacheStoragePolicy:
- -URLProtocol:wasRedirectedToRequest:redirectResponse:
- -URLProtocolDidFinishLoading:

### URLProtocol: cachedResponseIsValid:

- (void) URLProtocol: (NSURLProtocol*)protocol cachedResponseIsValid: (NSCachedURLResponse*)cachedResponse;
Availability: MacOS-X 10.2.0, Base 1.13.0
Informs a client that a cached response is valid.

### URLProtocol: didCancelAuthenticationChallenge:

- (void) URLProtocol: (NSURLProtocol*)protocol didCancelAuthenticationChallenge: (NSURLAuthenticationChallenge*)challenge;
Availability: MacOS-X 10.2.0, Base 1.13.0
Informs a client that an authentication challenge has been cancelled.

### URLProtocol: didFailWithError:

- (void) URLProtocol: (NSURLProtocol*)protocol didFailWithError: (NSError*)error;
Availability: MacOS-X 10.2.0, Base 1.13.0
Informs a client that loading of a request has failed.

### URLProtocol: didLoadData:

- (void) URLProtocol: (NSURLProtocol*)protocol didLoadData: (NSData*)data;
Availability: MacOS-X 10.2.0, Base 1.13.0
Informs a client that data has been loaded. Only new data since the last call to this method must be provided.

### URLProtocol: didReceiveAuthenticationChallenge:

- (void) URLProtocol: (NSURLProtocol*)protocol didReceiveAuthenticationChallenge: (NSURLAuthenticationChallenge*)challenge;
Availability: MacOS-X 10.2.0, Base 1.13.0
Informs a client that an authentication challenge has been received.

### URLProtocol: didReceiveResponse: cacheStoragePolicy:

- (void) URLProtocol: (NSURLProtocol*)protocol didReceiveResponse: (NSURLResponse*)response cacheStoragePolicy: (NSURLCacheStoragePolicy)policy;
Availability: MacOS-X 10.2.0, Base 1.13.0
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: wasRedirectedToRequest: redirectResponse:

- (void) URLProtocol: (NSURLProtocol*)protocol wasRedirectedToRequest: (NSURLRequest*)request redirectResponse: (NSURLResponse*)redirectResponse;
Availability: MacOS-X 10.2.0, Base 1.13.0
Informs a client that a redirect has occurred.

### URLProtocolDidFinishLoading:

- (void) URLProtocolDidFinishLoading: (NSURLProtocol*)protocol;
Availability: MacOS-X 10.2.0, Base 1.13.0
Informs a client that loading of a request has successfully finished.

Up