NSURLRequest Class Reference

Inherits from	NSObject
Conforms to	NSCoding NSCopying NSMutableCopying NSObject (NSObject)
Framework	/System/Library/Frameworks/Foundation.framework
Availability	Available in OS X v10.2 with Safari 1.0 installed. Available in OS X v10.2.7 and later.
Companion guide	URL Loading System Programming Guide
Declared in	NSURLRequest.h
Related sample code	JavaScriptCoreHeadstart LinkedImageFetcher Sandboxing with NSXPCConnection SpecialPictureProtocol XMLBrowser

Overview

NSURLRequest objects represent a URL load request in a manner independent of protocol and URL scheme.

NSURLRequest encapsulates two basic data elements of a load request: the URL to load, and the policy to use when consulting the URL content cache made available by the implementation.

NSURLRequest is designed to be extended to support additional protocols by adding categories that access protocol specific values from a property object using NSURLProtocol’s propertyForKey:inRequest: and setProperty:forKey:inRequest: methods.

The mutable subclass of NSURLRequest is NSMutableURLRequest.

Tasks

Creating Requests

Getting Request Properties

Getting HTTP Request Properties

Allowing Cellular Access

Class Methods

requestWithURL:

Creates and returns a URL request for a specified URL with default cache policy and timeout value.

+ (id)requestWithURL:(NSURL *)theURL

Parameters

theURL: The URL for the new request.

Return Value

The newly created URL request.

Discussion

The default cache policy is NSURLRequestUseProtocolCachePolicy and the default timeout interval is 60 seconds.

Availability

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

Related Sample Code

Declared In

NSURLRequest.h

requestWithURL:cachePolicy:timeoutInterval:

Creates and returns an initialized URL request with specified values.

+ (id)requestWithURL:(NSURL *)theURL cachePolicy:(NSURLRequestCachePolicy)cachePolicy timeoutInterval:(NSTimeInterval)timeoutInterval

Parameters

theURL: The URL for the new request.
cachePolicy: The cache policy for the new request.
timeoutInterval: The timeout interval for the new request, in seconds.

Return Value

The newly created URL request.

Availability

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

Related Sample Code

Sandboxing with NSXPCConnection

Declared In

NSURLRequest.h

Instance Methods

allHTTPHeaderFields

Returns a dictionary containing all the receiver’s HTTP header fields.

- (NSDictionary *)allHTTPHeaderFields

Return Value

A dictionary containing all the receiver’s HTTP header fields.

Availability

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

Declared In

NSURLRequest.h

allowsCellularAccess

Returns whether the request is allowed to use the cellular radio (if present).

- (BOOL)allowsCellularAccess

Return Value

YES if the cellular radio can be used; NO otherwise.

Availability

Available in OS X v10.8 and later.

Declared In

NSURLRequest.h

cachePolicy

Returns the receiver’s cache policy.

- (NSURLRequestCachePolicy)cachePolicy

Return Value

The receiver’s cache policy.

Availability

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

Declared In

NSURLRequest.h

HTTPBody

Returns the receiver’s HTTP body data.

- (NSData *)HTTPBody

Return Value

The receiver's HTTP body data.

Discussion

This data is sent as the message body of a request, as in an HTTP POST request.

Availability

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

Declared In

NSURLRequest.h

HTTPBodyStream

Returns the receiver’s HTTP body stream.

- (NSInputStream *)HTTPBodyStream

Return Value

The receiver’s HTTP body stream, or nil if it has not been set. The returned stream is for examination only, it is not safe to manipulate the stream in any way.

Discussion

The receiver will have either an HTTP body or an HTTP body stream, only one may be set for a request. A HTTP body stream is preserved when copying an NSURLRequest object, but is lost when a request is archived using the NSCoding protocol.

Availability

Available in OS X v10.4 and later.

Declared In

NSURLRequest.h

HTTPMethod

Returns the receiver’s HTTP request method.

- (NSString *)HTTPMethod

Return Value

The receiver’s HTTP request method.

Discussion

The default HTTP method is “GET”.

Availability

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

Declared In

NSURLRequest.h

HTTPShouldHandleCookies

Returns whether the default cookie handling will be used for this request.

- (BOOL)HTTPShouldHandleCookies

Return Value

YES if the default cookie handling will be used for this request, NO otherwise.

Discussion

The default is YES.

Special Considerations

In OS X v10.2 with Safari 1.0 the value set by this method is not respected by the framework.

Availability

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

Declared In

NSURLRequest.h

HTTPShouldUsePipelining

Returns whether the request should continue transmitting data before receiving a response from an earlier transmission.

- (BOOL)HTTPShouldUsePipelining

Return Value

YES if the request should continue transmitting data; otherwise, NO.

Availability

Available in OS X v10.7 and later.

Declared In

NSURLRequest.h

initWithURL:

Returns a URL request for a specified URL with default cache policy and timeout value.

- (id)initWithURL:(NSURL *)theURL

Parameters

theURL: The URL for the request.

Return Value

The initialized URL request.

Discussion

The default cache policy is NSURLRequestUseProtocolCachePolicy and the default timeout interval is 60 seconds.

Availability

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

Declared In

NSURLRequest.h

initWithURL:cachePolicy:timeoutInterval:

Returns an initialized URL request with specified values.

- (id)initWithURL:(NSURL *)theURL cachePolicy:(NSURLRequestCachePolicy)cachePolicy timeoutInterval:(NSTimeInterval)timeoutInterval

Parameters

theURL: The URL for the request.
cachePolicy: The cache policy for the request.
timeoutInterval: The timeout interval for the request, in seconds.

Return Value

The initialized URL request.

Discussion

This is the designated initializer for NSURLRequest.

Availability

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

Related Sample Code

Quartz Composer MiniSOAP

Declared In

NSURLRequest.h

mainDocumentURL

Returns the main document URL associated with the request.

- (NSURL *)mainDocumentURL

Return Value

The main document URL associated with the request.

Discussion

This URL is used for the cookie “same domain as main document” policy.

Availability

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

Declared In

NSURLRequest.h

networkServiceType

Returns the network service type of the request.

- (NSURLRequestNetworkServiceType)networkServiceType

Return Value

The network service type of the request.

Availability

Available in OS X v10.7 and later.

Declared In

NSURLRequest.h

timeoutInterval

Returns the receiver’s timeout interval, in seconds.

- (NSTimeInterval)timeoutInterval

Return Value

The receiver's timeout interval, in seconds.

Discussion

If during a connection attempt the request remains idle for longer than the timeout interval, the request is considered to have timed out.

Availability

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

Declared In

NSURLRequest.h

URL

Returns the request's URL.

- (NSURL *)URL

Return Value

The request's URL.

Availability

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

Related Sample Code

Declared In

NSURLRequest.h

valueForHTTPHeaderField:

Returns the value of the specified HTTP header field.

- (NSString *)valueForHTTPHeaderField:(NSString *)field

Parameters

field: The name of the header field whose value is to be returned. In keeping with the HTTP RFC, HTTP header field names are case-insensitive.

Return Value

The value associated with the header field field, or nil if there is no corresponding header field.

Availability

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

Declared In

NSURLRequest.h

Constants

NSURLRequestCachePolicy

These constants are used to specify interaction with the cached responses.

enum
{
   NSURLRequestUseProtocolCachePolicy = 0,
   NSURLRequestReloadIgnoringLocalCacheData = 1,
   NSURLRequestReloadIgnoringLocalAndRemoteCacheData =4,
   NSURLRequestReloadIgnoringCacheData = NSURLRequestReloadIgnoringLocalCacheData,
   NSURLRequestReturnCacheDataElseLoad = 2,
   NSURLRequestReturnCacheDataDontLoad = 3,
   NSURLRequestReloadRevalidatingCacheData = 5
};
typedef NSUInteger NSURLRequestCachePolicy;

Constants

NSURLRequestUseProtocolCachePolicy

Specifies that the caching logic defined in the protocol implementation, if any, is used for a particular URL load request. This is the default policy for URL load requests.

Available in OS X v10.2 and later.

Declared in NSURLRequest.h.

NSURLRequestReloadIgnoringLocalCacheData

Specifies that the data for the URL load should be loaded from the originating source. No existing cache data should be used to satisfy a URL load request.

Available in OS X v10.5 and later.

Declared in NSURLRequest.h.

NSURLRequestReloadIgnoringLocalAndRemoteCacheData

Specifies that not only should the local cache data be ignored, but that proxies and other intermediates should be instructed to disregard their caches so far as the protocol allows.

Available in OS X v10.5 and later.

Declared in NSURLRequest.h.

NSURLRequestReloadIgnoringCacheData

Replaced by NSURLRequestReloadIgnoringLocalCacheData.

Available in OS X v10.2 and later.

Declared in NSURLRequest.h.

NSURLRequestReturnCacheDataElseLoad

Specifies that the existing cached data should be used to satisfy the request, regardless of its age or expiration date. If there is no existing data in the cache corresponding the request, the data is loaded from the originating source.

Available in OS X v10.2 and later.

Declared in NSURLRequest.h.

NSURLRequestReturnCacheDataDontLoad

Specifies that the existing cache data should be used to satisfy a request, regardless of its age or expiration date. If there is no existing data in the cache corresponding to a URL load request, no attempt is made to load the data from the originating source, and the load is considered to have failed. This constant specifies a behavior that is similar to an “offline” mode.

Available in OS X v10.2 and later.

Declared in NSURLRequest.h.

NSURLRequestReloadRevalidatingCacheData

Specifies that the existing cache data may be used provided the origin source confirms its validity, otherwise the URL is loaded from the origin source.

Available in OS X v10.5 and later.

Declared in NSURLRequest.h.

Declared In

NSURLRequest.h

NSURLRequestNetworkServiceType

These constants are used to specify the network service type of a request.

enum
{
   NSURLNetworkServiceTypeDefault    = 0,
   NSURLNetworkServiceTypeVoIP       = 1,
   NSURLNetworkServiceTypeVideo      = 2,
   NSURLNetworkServiceTypeBackground = 3,
   NSURLNetworkServiceTypeVoice      = 4
};
typedef NSUInteger NSURLRequestNetworkServiceType;