iOS Developer Library

Developer

Foundation Framework Reference NSMutableURLRequest Class Reference

Options
Deployment Target:

On This Page
Language:

NSMutableURLRequest

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.

Inheritance


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in iOS 2.0 and later.
  • The cache policy of the receiver.

    Declaration

    Swift

    var cachePolicy: NSURLRequestCachePolicy

    Objective-C

    @property NSURLRequestCachePolicy cachePolicy

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 8.0 and later.

  • The main document URL for the receiver.

    Declaration

    Swift

    @NSCopying var mainDocumentURL: NSURL?

    Objective-C

    @property(copy) NSURL *mainDocumentURL

    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.

    nil indicates no main document.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 8.0 and later.

  • The network service type of the connection.

    Declaration

    Swift

    var networkServiceType: NSURLRequestNetworkServiceType

    Objective-C

    @property NSURLRequestNetworkServiceType networkServiceType

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 4.0 and later.

  • The receiver’s timeout interval, in seconds.

    Declaration

    Swift

    var timeoutInterval: NSTimeInterval

    Objective-C

    @property NSTimeInterval timeoutInterval

    Discussion

    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.

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

    Special Considerations

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 8.0 and later.

  • URL URL Property

    The URL of the receiver

    Declaration

    Swift

    @NSCopying var URL: NSURL?

    Objective-C

    @property(copy) NSURL *URL

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 8.0 and later.

  • A boolean value that indicates whether the connection can use the device’s cellular radio (if present).

    Declaration

    Swift

    var allowsCellularAccess: Bool

    Objective-C

    @property BOOL allowsCellularAccess

    Discussion

    YEStrue if the device’s cellular radio can be used; NOfalse otherwise. The default is YEStrue.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    func addValue(_ value: String?, forHTTPHeaderField field: String)

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The receiver's header fields.

    Declaration

    Swift

    var allHTTPHeaderFields: [NSObject : AnyObject]?

    Objective-C

    @property(copy) NSDictionary *allHTTPHeaderFields

    Discussion

    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.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 8.0 and later.

  • HTTPBody HTTPBody Property

    The request body of the receiver.

    Declaration

    Swift

    @NSCopying var HTTPBody: NSData?

    Objective-C

    @property(copy) NSData *HTTPBody

    Discussion

    The request body is sent as the message body of the request, as in an HTTP POST request. Setting the HTTP body data clears any input stream in HTTPBodyStream. These values are mutually exclusive.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 8.0 and later.

    See Also

    HTTPBodyStream

  • The request body as an input stream.

    Declaration

    Swift

    var HTTPBodyStream: NSInputStream?

    Objective-C

    @property(retain) NSInputStream *HTTPBodyStream

    Discussion

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

    Setting a body stream clears any data in HTTPBody. These values are mutually exclusive.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 8.0 and later.

    See Also

    HTTPBody

  • The receiver’s HTTP request method.

    Declaration

    Swift

    var HTTPMethod: String

    Objective-C

    @property(copy) NSString *HTTPMethod

    Discussion

    The default HTTP method is “GET”.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 8.0 and later.

  • A boolean value that indicates whether the receiver should use the default cookie handling for the request.

    Declaration

    Swift

    var HTTPShouldHandleCookies: Bool

    Objective-C

    @property BOOL HTTPShouldHandleCookies

    Discussion

    YEStrue if the receiver should use the default cookie handling for the request, NOfalse otherwise. The default is YEStrue.

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 8.0 and later.

  • A boolean value that indicates whether the request can continue transmitting data before receiving a response from an earlier transmission.

    Declaration

    Swift

    var HTTPShouldUsePipelining: Bool

    Objective-C

    @property BOOL HTTPShouldUsePipelining

    Discussion

    YEStrue if the request should continue transmitting data, NOfalse if the request should wait for a response. The default value is NOfalse.

    Setting this property to YEStrue value does not guarantee HTTP pipelining behavior. This may have no effect if an HTTP proxy is configured, or if the HTTP request uses an unsafe request method—for example, POST requests will not pipeline. Pipelining behavior may not begin until the second request on a given TCP connection. There may be other situations where pipelining does not occur even though this property is set to YEStrue. HTTP 1.1 allows the client to send multiple requests to the server without waiting for a response. Though HTTP 1.1 requires support for pipelining, some servers report themselves as being HTTP 1.1 but do not support pipelining (disconnecting, sending resources in the wrong order, omitting part of a resource, etc.).

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 4.0 and later.

  • Sets the specified HTTP header field.

    Declaration

    Swift

    func setValue(_ value: String?, forHTTPHeaderField field: String)

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.