NSURLRequest Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in OS X v10.2 and later.
Companion guide
Declared in
NSURLRequest.h
Related sample code

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

Support for Secure Coding

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 and later.
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 and later.
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 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.

Return Value

The receiver’s cache policy.

Availability
  • Available in OS X v10.2 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 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 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.

Availability
  • Available in OS X v10.2 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 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 and later.
Related Sample Code
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 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.

Discussion

The network service type provides a hint to the operating system about what the underlying traffic is used for. This hint enhances the system's ability to prioritize traffic, determine how quickly it needs to wake up the cellular or Wi-Fi radio, and so on. By providing accurate information, you improve the ability of the system to optimally balance battery life, performance, and other considerations.

For example, you should specify the NSURLNetworkServiceTypeBackground type if your app is performing a download that was not requested by the user—for example, prefetching content so that it will be available when the user chooses to view it.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSURLRequest.h

supportsSecureCoding

Indicates that NSURLRequest implements the NSSecureCoding protocol.

- (BOOL)supportsSecureCoding
Return Value

YES to indicate that NSURLRequest implements the NSSecureCoding protocol.

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 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 and later.
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 and later.
Declared In
NSURLRequest.h

Constants

NSURLRequestCachePolicy

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

enum
{
   NSURLRequestUseProtocolCachePolicy = 0,
   NSURLRequestReloadIgnoringLocalCacheData = 1,
   NSURLRequestReturnCacheDataElseLoad = 2,
   NSURLRequestReturnCacheDataDontLoad = 3,
};
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;
Constants
NSURLNetworkServiceTypeDefault

Specifies standard network traffic. Most connections should be made using this service type.

Available in OS X v10.7 and later.

Declared in NSURLRequest.h.

NSURLNetworkServiceTypeVoIP

Specifies that the request is for VoIP traffic.

With the VoIP service type, the kernel continues to listen for incoming traffic while your app is in the background, then wakes up your app whenever new data arrives. This should be used only for connections that are used to communicate with a VoIP service.

Available in OS X v10.7 and later.

Declared in NSURLRequest.h.

NSURLNetworkServiceTypeVideo

Specifies that the request is for video traffic.

Available in OS X v10.7 and later.

Declared in NSURLRequest.h.

NSURLNetworkServiceTypeBackground

Specifies that the request is for background traffic.

You should specify this type if your app is performing a download that was not requested by the user—for example, prefetching content so that it will be available when the user chooses to view it.

Available in OS X v10.7 and later.

Declared in NSURLRequest.h.

NSURLNetworkServiceTypeVoice

Specifies that the request is for voice traffic.

Available in OS X v10.7 and later.

Declared in NSURLRequest.h.

Discussion

The network service type provides a hint to the operating system about what the underlying traffic is used for. This hint enhances the system's ability to prioritize traffic, determine how quickly it needs to wake up the cellular or Wi-Fi radio, and so on. By providing accurate information, you improve the ability of the system to optimally balance battery life, performance, and other considerations.