NSURLRequest

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

The mutable subclass of NSURLRequest is .

概述：

NSURLRequest 对象代表一个URL加载的请求，在某种意义上是独立的协议和URL方案。

NSURLRequest封装了两个基本的数据元素在一个加载请求中：一是要加载的URL，另一个是当查询URL内容缓存通过实现是否可行时采用的策略。

NSURLRequest是设计用来扩展支持附加协议的。某个属性对象使用NSURLProtocol的 和  方法，可以添加各种指定的接入协议值，NSURLRequest都支持。

可变的NSURLRequest子类为NSMutableURLRequest。

 

Class Methods

requestWithURL:

Creates and returns a URL request for a specified URL with default cache policy and timeout value.

创建并返回一个URL请求，指向一个指定的URL，采用默认的缓存策略和超时响应时长。

+ (id)requestWithURL:( *)theURL

Discussion

The default cache policy is NSURLRequestUseProtocolCachePolicy and the default timeout interval is 60 seconds.

默认的缓存策略是NSURLRequestUseProtocolCachePolicy，默认的超时时长是60秒。

requestWithURL:cachePolicy:timeoutInterval:

Creates and returns an initialized URL request with specified values.

创建并返回一个初始化的URL请求，采用指定的缓存策略和超时时长。

+ (id)requestWithURL:( *)theURL cachePolicy:(NSURLRequestCachePolicy)cachePolicytimeoutInterval:()timeoutInterval

Return Value

The newly created URL request.

Instance Methods

allHTTPHeaderFields

Returns a dictionary containing all the receiver’s HTTP header fields.

返回一个包含所有接受者HTTP头区域的字典。

- ( *)allHTTPHeaderFields

allowsCellularAccess

Returns whether the request is allowed to use the cellular radio (if present).

返回是否请求允许使用蜂窝网络。

- (BOOL)allowsCellularAccess

Return Value

YES if the cellular radio can be used; NO otherwise.

cachePolicy

Returns the receiver’s cache policy.

返回请求接受者的缓存策略。

- (NSURLRequestCachePolicy)cachePolicy

Return Value

The receiver’s cache policy.

HTTPBody

Returns the receiver’s HTTP body data.

返回接受者的HTTP数据。

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

这个数据作为一个请求的信息主体被发送，就像在一个HTTP里发送请求。

HTTPBodyStream

Returns the receiver’s HTTP body stream.

返回接受者的HTTP主体流。

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

接受者的HTTP主体流，如果没有被设置的话为nil。返回的流仅供检验，无论如何操作这个流是不安全的。

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.

接受者将会同时拥有HTTP主体和HTTP主体流，仅有一个会被设置为请求。当它复制一个NSURLRequest对象的时候，HTTP主体流被保留，但是当一个请求使用NSCoding协议到达的时候会被丢弃。

HTTPMethod

Returns the receiver’s HTTP request method.

- ( *)HTTPMethod

Return Value

The receiver’s HTTP request method.

Discussion

The default HTTP method is “GET”.

返回操作HTTP的方法。默认为"GET"。

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.

HTTPShouldUsePipelining

Returns whether the request should continue transmitting data before receiving a response from an earlier transmission.

返回在接收到前面的传输响应之前，请求是否需要持续地传输数据。

- (BOOL)HTTPShouldUsePipelining

Return Value

YES if the request should continue transmitting data; otherwise, NO.

initWithURL:

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

- (id)initWithURL:( *)theURL

Return Value

The initialized URL request.

Discussion

The default cache policy is NSURLRequestUseProtocolCachePolicy and the default timeout interval is 60 seconds.

initWithURL:cachePolicy:timeoutInterval:

Returns an initialized URL request with specified values.

- (id)initWithURL:( *)theURL cachePolicy:(NSURLRequestCachePolicy)cachePolicytimeoutInterval:()timeoutInterval

Discussion

This is the designated initializer for NSURLRequest.

这两个是初始化方法，不同于最开始两个的工厂方法。

mainDocumentURL

Returns the main document URL associated with the request.

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

networkServiceType

Returns the network service type of the request.

返回请求的网络服务的类型。

- (NSURLRequestNetworkServiceType)networkServiceType

Return Value

The network service type of the request.

timeoutInterval

Returns the receiver’s timeout interval, in seconds.

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

如果在一个连接尝试请求保持空闲了一段超过超时响应的时间，这个请求会被认为超时。

URL

Returns the request's URL.

- ( *)URL

Return Value

The request's URL.

valueForHTTPHeaderField:

Returns the value of the specified HTTP header field.

- ( *)valueForHTTPHeaderField:( *)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.

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

在协议实现中指定缓存逻辑。是URL加载请求的默认策略。

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.

指定URL加载应该加载源端数据，不应采用已存在的缓存数据来满足URL加载请求。

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.

指定不仅本地缓存数据不采用，并且代理和其他中介都要忽视他们的缓存，直到协议允许。

NSURLRequestReloadIgnoringCacheData

Replaced by NSURLRequestReloadIgnoringLocalCacheData.

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.

指定已存的缓存数据应该用来响应请求，不管它的生命时长和过期时间。如果在缓存中没有已存数据来响应请求的话，数据从源端加载。

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.

指定已存的缓存数据用来满足请求，不管生命时长和过期时间。如果在缓存中没有已存数据来响应URL加载请求的话，不去尝试从源段加载数据，此时认为加载请求失败。这个常量指定了一个类似于离线模式的行为。

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.

指定如果已存的缓存数据被提供它的源段确认为有效则允许使用缓存数据响应请求，否则从源段加载数据。

NSURLRequestNetworkServiceType

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

enum

{

   NSURLNetworkServiceTypeDefault    = 0,

   NSURLNetworkServiceTypeVoIP       = 1,

   NSURLNetworkServiceTypeVideo      = 2,

   NSURLNetworkServiceTypeBackground = 3,

   NSURLNetworkServiceTypeVoice      = 4

};

typedef  NSURLRequestNetworkServiceType;

Constants

NSURLNetworkServiceTypeDefault

Specifies standard network traffic.

NSURLNetworkServiceTypeVoIP

Specifies that the request is for VoIP traffic.

NSURLNetworkServiceTypeVideo

Specifies that the request is for video traffic.

NSURLNetworkServiceTypeBackground

Specifies that the request is for background traffic.

NSURLNetworkServiceTypeVoice

Specifies that the request is for voice traffic.

Understanding Cache Access

The URL loading system provides a composite on-disk and in-memory cache of responses to requests. This cache allows an application to reduce its dependency on a network connection and increase its performance.

URL加载系统提供了一个磁盘和内存混合的缓存，来相应网络请求。这个缓存允许一个应用减少对网络连接的依赖，并且增加性能。

Using the Cache for a Request

An NSURLRequest instance specifies how the local cache is used by setting the cache policy to one of the NSURLRequestCachePolicy values: ,, , or.

一个NSURLRequest实例通过设置NSURLRequestCachePolicy来指定如何使用本地缓存。

The default cache policy for an NSURLRequest instance is . The behavior is protocol specific and is defined as being the best conforming policy for the protocol.

默认的缓存策略是，这是为协议定义的最好的确认策略。

Setting the cache policy to  causes the URL loading system to load the data from the originating source, ignoring the cache completely.

设置缓存策略为，会让URL加载系统从源段加载数据，完全忽略缓存。

The  cache policy will cause the URL loading system to use cached data ignoring its age or expiration date, if it exists, and load the data from the originating source only if there is no cached version.

缓存策略会让URL加载系统使用缓存数据，不管其生命周期和过期时间，只有在没有缓存的时候才从源段加载数据。

The  policy allows an application to specify that only data in the cache should be returned. Attempting to create an NSURLConnection or NSURLDownload instance with this cache policy returns nil immediately if the response is not in the local cache. This is similar in function to an “offline” mode and never brings up a network connection.

策略允许一个应用指定仅使用缓存中的数据。如果尝试创建一个NSURLConnection或者NSURLDownload实例，在这个缓存策略下，假如在本地缓存中没有响应，将立即返回nil。这有点类似离线模式的功能，并且从不发起一个网络连接。

Note: Currently, only responses to http and https requests are cached. The ftp and file protocols attempt to access the originating source as allowed by the cache policy. Custom NSURLProtocol classes can provide caching if they choose.

注意：最近，只有响应http和https的请求会被缓存。ftp和文件协议当被缓存策略允许的时候尝试接入源段。自定义的NSURLProtocol类能够保护缓存，如果它们被选择使用的话。

Cache Use Semantics for the http Protocol

The most complicated cache use situation is when a request uses the http protocol and has set the cache policy to .

最复杂的缓存使用情况就是当一个请求使用http协议的时候，设置缓存策略为。

If an NSCachedURLResponse does not exist for the request, then the data is fetched from the originating source. If there is a cached response for the request, the URL loading system checks the response to determine if it specifies that the contents must be revalidated. If the contents must be revalidated a connection is made to the originating source to see if it has changed. If it has not changed, then the response is returned from the local cache. If it has changed, the data is fetched from the originating source.

如果一个NSCachedURLResponse对于请求并不存在，数据将会从源端获取。如果请求拥有一个缓存的响应，那么URL加载系统会检查这个响应来决定，如果它指定内容必须重新生效的话。假如内容必须重新生效，将建立一个连向源端的连接来查看内容是否发生变化。假如内容没有变化，那么响应就从本地缓存返回数据。如果内容变化了，那么数据将从源端获取。

If the cached response doesn’t specify that the contents must be revalidated, the maximum age or expiration specified in the response is examined. If the cached response is recent enough, then the response is returned from the local cache. If the response is determined to be stale, the originating source is checked for newer data. If newer data is available, the data is fetched from the originating source, otherwise it is returned from the cache.

如果缓存响应没有指定内容必须重新生效，将会检查响应指定的缓存最大的生命周期和过期时间。如果缓存响应足够新，那么响应从本地缓存返回数据。如果决定的响应是旧的，那么源端就会检查是否有新的数据。如果新数据是可行的，这个数据将会从源端获取，否则将会从缓存中返回数据。