ADC Home > Reference Library > Reference > Cocoa > Networking > NSMutableURLRequest Class Reference >

Next Page > Hide TOC

NSMutableURLRequest Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in Mac OS X v10.2 with Safari 1.0 installed.
Available in Mac OS X v10.2.7 and later.
Companion guide
Declared in
NSURLRequest.h

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 for each load.

This programming model is supported by the following contract between NSMutableURLRequest and NSURLConnection: NSURLConnection makes a deep copy of each NSMutableURLRequest object passed to one of its initializers.

NSMutableURLRequest, like 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.

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, this is a comma.

Availability
See Also
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.

Availability
See Also
Declared In
NSURLRequest.h

setCachePolicy:

Sets the cache policy of the receiver.

- (void)setCachePolicy:(NSURLRequestCachePolicy)policy

Parameters
policy

The new cache policy.

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

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

Availability
See Also
Declared In
NSURLRequest.h

setURL:

Sets the URL of the receiver

- (void)setURL:(NSURL *)theURL

Parameters
theURL

The new URL.

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

Availability
See Also
Declared In
NSURLRequest.h

Next Page > Hide TOC

© 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-05-23)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.