Mac Developer Library

Developer

Foundation Framework Reference NSURLProtocol Class Reference

Options
Deployment Target:

On This Page
Language:

NSURLProtocol

Inheritance


Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in OS X v10.2 with Safari 1.0 installed.
Available in OS X v10.2.7 and later.

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.

  • Initializes an NSURLProtocol object.

    Declaration

    Swift

    init(request request: NSURLRequest, cachedResponse cachedResponse: NSCachedURLResponse?, client client: NSURLProtocolClient?)

    Objective-C

    - (instancetype)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 initializer for NSURLProtocol.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 with Safari 1.0 installed.

    Available in OS X v10.2.7 and later.

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

    Declaration

    Swift

    class func registerClass(_ protocolClass: AnyClass) -> Bool

    Objective-C

    + (BOOL)registerClass:(Class)protocolClass

    Parameters

    protocolClass

    The subclass of NSURLProtocol to register.

    Return Value

    YEStrue if the registration is successful, NOfalse 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 YEStrue 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:.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 with Safari 1.0 installed.

    Available in OS X v10.2.7 and later.

  • Unregisters the specified subclass of NSURLProtocol.

    Declaration

    Swift

    class func unregisterClass(_ protocolClass: AnyClass)

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 with Safari 1.0 installed.

    Available in OS X v10.2.7 and later.

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

    Declaration

    Swift

    class func propertyForKey(_ key: String, inRequest request: NSURLRequest) -> AnyObject?

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 with Safari 1.0 installed.

    Available in OS X v10.2.7 and later.

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

    Declaration

    Swift

    class func setProperty(_ value: AnyObject, forKey key: String, inRequest request: NSMutableURLRequest)

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 with Safari 1.0 installed.

    Available in OS X v10.2.7 and later.

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

    Declaration

    Swift

    class func removePropertyForKey(_ key: String, inRequest request: NSMutableURLRequest)

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • Returns whether the protocol subclass can handle the specified request.

    Declaration

    Swift

    class func canInitWithRequest(_ request: NSURLRequest) -> Bool

    Objective-C

    + (BOOL)canInitWithRequest:(NSURLRequest *)request

    Parameters

    request

    The request to be handled.

    Return Value

    YEStrue if the protocol subclass can handle request, otherwise NOfalse.

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 with Safari 1.0 installed.

    Available in OS X v10.2.7 and later.

  • Returns a canonical version of the specified request.

    Declaration

    Swift

    class func canonicalRequestForRequest(_ request: NSURLRequest) -> NSURLRequest

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 with Safari 1.0 installed.

    Available in OS X v10.2.7 and later.

  • Returns whether two requests are equivalent for cache purposes.

    Declaration

    Swift

    class func requestIsCacheEquivalent(_ aRequest: NSURLRequest, toRequest bRequest: NSURLRequest) -> Bool

    Objective-C

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

    Parameters

    aRequest

    The request to compare with bRequest.

    bRequest

    The request to compare with aRequest.

    Return Value

    YEStrue if aRequest and bRequest are equivalent for cache purposes, NOfalse 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 with Safari 1.0 installed.

    Available in OS X v10.2.7 and later.

  • Starts protocol-specific loading of the request.

    Declaration

    Swift

    func startLoading()

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 with Safari 1.0 installed.

    Available in OS X v10.2.7 and later.

    See Also

    – stopLoading

  • Stops protocol-specific loading of the request.

    Declaration

    Swift

    func stopLoading()

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 with Safari 1.0 installed.

    Available in OS X v10.2.7 and later.

  • The receiver’s cached response. (read-only)

    Declaration

    Swift

    @NSCopying var cachedResponse: NSCachedURLResponse? { get }

    Objective-C

    @property(readonly, copy) NSCachedURLResponse *cachedResponse

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 with Safari 1.0 installed.

    Available in OS X v10.2.7 and later.

  • client client Property

    The object the receiver uses to communicate with the URL loading system. (read-only)

    Declaration

    Swift

    var client: NSURLProtocolClient? { get }

    Objective-C

    @property(readonly, retain) id< NSURLProtocolClient > client

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 with Safari 1.0 installed.

    Available in OS X v10.2.7 and later.

  • request request Property

    The receiver’s request. (read-only)

    Declaration

    Swift

    @NSCopying var request: NSURLRequest { get }

    Objective-C

    @property(readonly, copy) NSURLRequest *request

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 with Safari 1.0 installed.

    Available in OS X v10.2.7 and later.