---

NSURLRequest Class Reference

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.

Adopted Protocols

• – copyWithZone:

• – mutableCopyWithZone:

Tasks

Creating Requests

• + requestWithURL:
• – initWithURL:
• + requestWithURL:cachePolicy:timeoutInterval:
• – initWithURL:cachePolicy:timeoutInterval:

Getting Request Properties

• – cachePolicy
• – mainDocumentURL
• – timeoutInterval
• – URL

Getting HTTP Request Properties

• – allHTTPHeaderFields
• – HTTPBody
• – HTTPBodyStream
• – HTTPMethod
• – HTTPShouldHandleCookies
• – valueForHTTPHeaderField:

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 Mac OS X v10.2 with Safari 1.0 installed.
• Available in Mac OS X v10.2.7 and later.

See Also

• + requestWithURL:cachePolicy:timeoutInterval:

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 Mac OS X v10.2 with Safari 1.0 installed.
• Available in Mac OS X v10.2.7 and later.

See Also

• – initWithURL:cachePolicy:timeoutInterval:

Related Sample Code

• URL CacheInfo

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 Mac OS X v10.2 with Safari 1.0 installed.
• Available in Mac OS X v10.2.7 and later.

See Also

• – valueForHTTPHeaderField:

Declared In

NSURLRequest.h

cachePolicy

Returns the receiver’s cache policy.

- (NSURLRequestCachePolicy)cachePolicy

Return Value

The receiver’s cache policy.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 installed.
• Available in Mac 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 Mac OS X v10.2 with Safari 1.0 installed.
• Available in Mac 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 Mac 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 Mac OS X v10.2 with Safari 1.0 installed.
• Available in Mac 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 Mac OS X v10.2 with Safari 1.0 the value set by this method is not respected by the framework.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 installed.
• Available in Mac OS X v10.2.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 Mac OS X v10.2 with Safari 1.0 installed.
• Available in Mac OS X v10.2.7 and later.

See Also

• – initWithURL:cachePolicy:timeoutInterval:

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 Mac OS X v10.2 with Safari 1.0 installed.
• Available in Mac OS X v10.2.7 and later.

See Also

• – initWithURL:

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 Mac OS X v10.2 with Safari 1.0 installed.
• Available in Mac OS X v10.2.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 Mac OS X v10.2 with Safari 1.0 installed.
• Available in Mac 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 Mac OS X v10.2 with Safari 1.0 installed.
• Available in Mac OS X v10.2.7 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 Mac OS X v10.2 with Safari 1.0 installed.
• Available in Mac 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 Mac 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 Mac 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 Mac OS X v10.5 and later.

Declared in NSURLRequest.h.

NSURLRequestReloadIgnoringCacheData

Replaced by NSURLRequestReloadIgnoringLocalCacheData.

Available in Mac 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 Mac 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 Mac 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 Mac OS X v10.5 and later.

Declared in NSURLRequest.h.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

NSURLRequest.h

---