NSMutableURLRequest Class Reference

Inherits from
Conforms to
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
Declared in
NSURLRequest.h
Related sample code

Overview

NSMutableURLRequest is a subclass of NSURLRequest provided to aid developers who may find it more convenient to mutate a single request object for a series of URL load requests instead of creating an immutable NSURLRequest object for each load.

NSMutableURLRequest, like NSURLRequest, is designed to be extended to support additional protocols by adding categories that provide accessor methods for your own protocol-specific properties. Those methods can get and set the actual values by calling the NSURLProtocol methods propertyForKey:inRequest: and setProperty:forKey:inRequest:.

The NSURLSession, NSURLConnection, and NSURLDownload classes make a deep copy of each NSMutableURLRequest object passed to their initializers and task creation methods.

Tasks

Setting Request Properties

Setting HTTP Specific Properties

Instance Methods

addValue:forHTTPHeaderField:

Adds an HTTP header to the receiver’s HTTP header dictionary.

- (void)addValue:(NSString *)value forHTTPHeaderField:(NSString *)field
Parameters
value

The value for the header field.

field

The name of the header field. In keeping with the HTTP RFC, HTTP header field names are case-insensitive.

Discussion

This method provides the ability to add values to header fields incrementally. If a value was previously set for the specified field, the supplied value is appended to the existing value using the appropriate field delimiter. In the case of HTTP, the delimiter is a comma.

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

setAllHTTPHeaderFields:

Replaces the receiver's header fields with the passed values.

- (void)setAllHTTPHeaderFields:(NSDictionary *)headerFields
Parameters
headerFields

A dictionary with the new header fields. HTTP header fields must be string values; therefore, each object and key in the headerFields dictionary must be a subclass of NSString. If either the key or value for a key-value pair is not a subclass of NSString, the key-value pair is skipped.

Discussion

The NSURLConnection class and NSURLSession classes are designed to handle various aspects of the HTTP protocol for you. As a result, you should not modify the following headers:

  • Authorization

  • Connection

  • Host

  • WWW-Authenticate

Additionally, if the length of your upload body data can be determined automatically (for example, if you provide the body content with an NSData object), then the value of Content-Length is set for you.

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

setAllowsCellularAccess:

Sets whether the connection can use the device’s cellular radio (if present).

- (void)setAllowsCellularAccess:(BOOL)allow
Parameters
allow

YES if the device’s cellular radio can be used; NO otherwise;

Discussion

The default is YES.

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

setCachePolicy:

Sets the cache policy of the receiver.

- (void)setCachePolicy:(NSURLRequestCachePolicy)policy
Parameters
policy

The new cache policy.

Availability
  • Available in OS X v10.2 with Safari 1.0 installed.
  • Available in OS X v10.2.7 and later.
See Also
Declared In
NSURLRequest.h

setHTTPBody:

Sets the request body of the receiver to the specified data.

- (void)setHTTPBody:(NSData *)data
Parameters
data

The new request body for the receiver. This is sent as the message body of the request, as in an HTTP POST request.

Discussion

Setting the HTTP body data clears any input stream set by setHTTPBodyStream:. These values are mutually exclusive.

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

setHTTPBodyStream:

Sets the request body of the receiver to the contents of a specified input stream.

- (void)setHTTPBodyStream:(NSInputStream *)inputStream
Parameters
inputStream

The input stream that will be the request body of the receiver. The entire contents of the stream will be sent as the body, as in an HTTP POST request. The inputStream should be unopened and the receiver will take over as the stream’s delegate.

Discussion

Setting a body stream clears any data set by setHTTPBody:. These values are mutually exclusive.

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

setHTTPMethod:

Sets the receiver’s HTTP request method.

- (void)setHTTPMethod:(NSString *)method
Parameters
method

The new HTTP request method. 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.
See Also
Related Sample Code
Declared In
NSURLRequest.h

setHTTPShouldHandleCookies:

Sets whether the receiver should use the default cookie handling for the request.

- (void)setHTTPShouldHandleCookies:(BOOL)handleCookies
Parameters
handleCookies

YES if the receiver should use the default cookie handling for the request, NO otherwise. The default is YES.

Discussion

If your app sets the Cookie header on an NSMutableURLRequest object, then this method has no effect, and the cookie data you set in the header overrides all cookies from the cookie store.

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

setHTTPShouldUsePipelining:

Sets whether the request can continue transmitting data before receiving a response from an earlier transmission.

- (void)setHTTPShouldUsePipelining:(BOOL)shouldUsePipelining
Parameters
shouldUsePipelining

If YES, the request should continue transmitting data; if NO, the request should wait for a response.

Discussion

The default value is NO.

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

setMainDocumentURL:

Sets the main document URL for the receiver.

- (void)setMainDocumentURL:(NSURL *)theURL
Parameters
theURL

The new main document URL. Can be nil.

Discussion

The caller should set the main document URL to an appropriate main document, if known. For example, when loading a web page the URL of the HTML document for the top-level frame would be appropriate. This URL will be used for the “only from same domain as main document” cookie accept 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

setNetworkServiceType:

Sets the network service type of the connection.

- (void)setNetworkServiceType:(NSURLRequestNetworkServiceType)networkServiceType
Parameters
networkServiceType

The network service type.

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

setTimeoutInterval:

Sets the receiver’s timeout interval, in seconds.

- (void)setTimeoutInterval:(NSTimeInterval)timeoutInterval
Parameters
timeoutInterval

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

Note: In iOS versions prior to iOS 6, the minimum (and default) timeout interval for any request containing a request body was 240 seconds.

As a general rule, you should not use short timeout intervals, and instead, should provide an easy way for the user to cancel a long-running operation. For more information, read “Designing for Real-World Networks”.

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

setURL:

Sets the URL of the receiver

- (void)setURL:(NSURL *)theURL
Parameters
theURL

The new URL.

Availability
  • Available in OS X v10.2 with Safari 1.0 installed.
  • Available in OS X v10.2.7 and later.
See Also
Declared In
NSURLRequest.h

setValue:forHTTPHeaderField:

Sets the specified HTTP header field.

- (void)setValue:(NSString *)value forHTTPHeaderField:(NSString *)field
Parameters
value

The new value for the header field. Any existing value for the field is replaced by the new value.

field

The name of the header field to set. In keeping with the HTTP RFC, HTTP header field names are case-insensitive.

Discussion

The NSURLConnection class and NSURLSession classes are designed to handle various aspects of the HTTP protocol for you. As a result, you should not modify the following headers:

  • Authorization

  • Connection

  • Host

  • WWW-Authenticate

Additionally, if the length of your upload body data can be determined automatically (for example, if you provide the body content with an NSData object), then the value of Content-Length is set for you.

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