Mac Developer Library

Developer

Foundation Framework Reference NSURLRequest Class Reference

Options
Deployment Target:

On This Page
Language:

NSURLRequest

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 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 mutable subclass of NSURLRequest is NSMutableURLRequest.

Inheritance


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in OS X v10.2 and later.
  • Creates and returns a URL request for a specified URL with default cache policy and timeout value.

    Declaration

    Objective-C

    + (instancetype)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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.2 and later.

  • Returns a URL request for a specified URL with default cache policy and timeout value.

    Declaration

    Swift

    convenience init(URL theURL: NSURL)

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

  • Creates and returns an initialized URL request with specified values.

    Declaration

    Objective-C

    + (instancetype)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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.2 and later.

  • Returns an initialized URL request with specified values.

    Declaration

    Swift

    init(URL theURL: NSURL, cachePolicy cachePolicy: NSURLRequestCachePolicy, timeoutInterval timeoutInterval: NSTimeInterval)

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

  • The receiver’s cache policy. (read-only)

    Declaration

    Swift

    var cachePolicy: NSURLRequestCachePolicy { get }

    Objective-C

    @property(readonly) NSURLRequestCachePolicy cachePolicy

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

    See Also

    setCachePolicy:

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

    Declaration

    Swift

    var HTTPShouldUsePipelining: Bool { get }

    Objective-C

    @property(readonly) BOOL HTTPShouldUsePipelining

    Discussion

    YEStrue if the request should continue transmitting data; otherwise, NOfalse.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.7 and later.

  • The main document URL associated with the request. (read-only)

    Declaration

    Swift

    @NSCopying var mainDocumentURL: NSURL? { get }

    Objective-C

    @property(readonly, copy) NSURL *mainDocumentURL

    Discussion

    This URL is used for the cookie “same domain as main document” policy.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

  • The receiver’s timeout interval, in seconds. (read-only)

    Declaration

    Swift

    var timeoutInterval: NSTimeInterval { get }

    Objective-C

    @property(readonly) 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

  • The network service type of the request. (read-only)

    Declaration

    Swift

    var networkServiceType: NSURLRequestNetworkServiceType { get }

    Objective-C

    @property(readonly) NSURLRequestNetworkServiceType networkServiceType

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.7 and later.

  • URL URL Property

    The request's URL. (read-only)

    Declaration

    Swift

    @NSCopying var URL: NSURL { get }

    Objective-C

    @property(readonly, copy) NSURL *URL

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

    See Also

    setURL:

  • All of the receiver’s HTTP header fields. (read-only)

    Declaration

    Swift

    var allHTTPHeaderFields: [NSObject : AnyObject]? { get }

    Objective-C

    @property(readonly, copy) NSDictionary *allHTTPHeaderFields

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

  • HTTPBody HTTPBody Property

    The receiver’s HTTP body data. (read-only)

    Declaration

    Swift

    @NSCopying var HTTPBody: NSData? { get }

    Objective-C

    @property(readonly, copy) NSData *HTTPBody

    Discussion

    This data is sent as the message body of a request, as in an HTTP POST request.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

  • The receiver’s HTTP body stream. (read-only)

    Declaration

    Swift

    var HTTPBodyStream: NSInputStream? { get }

    Objective-C

    @property(readonly, retain) NSInputStream *HTTPBodyStream

    Discussion

    nil if the body stream has not been set. The returned stream is for examination only—it is not safe to manipulate the stream in any way.

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.4 and later.

  • The receiver’s HTTP request method. (read-only)

    Declaration

    Swift

    var HTTPMethod: String? { get }

    Objective-C

    @property(readonly, copy) NSString *HTTPMethod

    Discussion

    The default HTTP method is “GET”.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

    See Also

    setHTTPMethod:

  • A boolean value that indicates whether the default cookie handling will be used for this request. (read-only)

    Declaration

    Swift

    var HTTPShouldHandleCookies: Bool { get }

    Objective-C

    @property(readonly) BOOL HTTPShouldHandleCookies

    Discussion

    YEStrue if the default cookie handling will be used for this request, NOfalse otherwise. The default is YEStrue.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

  • Returns the value of the specified HTTP header field.

    Declaration

    Swift

    func valueForHTTPHeaderField(_ field: String) -> String?

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

  • A boolean value that indicates whether the request is allowed to use the cellular radio (if present). (read-only)

    Declaration

    Swift

    var allowsCellularAccess: Bool { get }

    Objective-C

    @property(readonly) BOOL allowsCellularAccess

    Discussion

    YEStrue if the cellular radio can be used; NOfalse otherwise.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.8 and later.

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

    Declaration

    Swift

    enum NSURLRequestCachePolicy : UInt { case UseProtocolCachePolicy case ReloadIgnoringLocalCacheData case ReloadIgnoringLocalAndRemoteCacheData case ReturnCacheDataElseLoad case ReturnCacheDataDontLoad case ReloadRevalidatingCacheData }

    Objective-C

    enum { NSURLRequestUseProtocolCachePolicy = 0, NSURLRequestReloadIgnoringLocalCacheData = 1, NSURLRequestReturnCacheDataElseLoad = 2, NSURLRequestReturnCacheDataDontLoad = 3, }; typedef NSUInteger NSURLRequestCachePolicy;

    Constants

    • UseProtocolCachePolicy

      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. This policy is described further in the discussion below.

      Available in OS X v10.2 and later.

    • ReloadIgnoringLocalCacheData

      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.

    • ReturnCacheDataElseLoad

      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.

    • ReturnCacheDataDontLoad

      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.

    Discussion

    For the HTTP protocol, the behavior of the NSURLRequestUseProtocolCachePolicy policy is shown in NSURLRequestUseProtocolCachePolicy decision tree for HTTP and HTTPS.

    Figure 1NSURLRequestUseProtocolCachePolicy decision tree for HTTP and HTTPS image: ../Art/http_caching.pdf

    Briefly put:

    1. If a cached response does not exist for the request, the URL loading system fetches the data from the originating source.

    2. Otherwise, if the cached response does not indicate that it must be revalidated every time, and if the cached response is not stale (past its expiration date), the URL loading system returns the cached response.

    3. If the cached response is stale or requires revalidation, the URL loading system makes a HEAD request to the originating source to see if the resource has changed. If so, the URL loading system fetches the data from the originating source. Otherwise, it returns the cached response.

    RFC 2616, Section 13 (http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13) specifies these semantics in detail.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

  • These constants are used to specify the network service type of a request.

    Declaration

    Swift

    enum NSURLRequestNetworkServiceType : UInt { case NetworkServiceTypeDefault case NetworkServiceTypeVoIP case NetworkServiceTypeVideo case NetworkServiceTypeBackground case NetworkServiceTypeVoice }

    Objective-C

    enum { NSURLNetworkServiceTypeDefault = 0, NSURLNetworkServiceTypeVoIP = 1, NSURLNetworkServiceTypeVideo = 2, NSURLNetworkServiceTypeBackground = 3, NSURLNetworkServiceTypeVoice = 4 }; typedef NSUInteger NSURLRequestNetworkServiceType;

    Constants

    • NetworkServiceTypeDefault

      NSURLNetworkServiceTypeDefault

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

      Available in OS X v10.7 and later.

    • NetworkServiceTypeVoIP

      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.

    • NetworkServiceTypeVideo

      NSURLNetworkServiceTypeVideo

      Specifies that the request is for video traffic.

      Available in OS X v10.7 and later.

    • NetworkServiceTypeBackground

      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.

    • NetworkServiceTypeVoice

      NSURLNetworkServiceTypeVoice

      Specifies that the request is for voice traffic.

      Available in OS X v10.7 and later.

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.7 and later.