Official documents of the Nsurlrequest "translation"

Overview

Nsurlrequest objects represent a URL load request in a manner independent of Protocol and URL scheme.

Nsurlrequest encapsulates the elements of a load request:the URL to load, and the policy to use when Consultin G The URL content cache made available by the implementation.

Nsurlrequest is designed to being extended to support additional protocols by adding categories that Access Protocol specific Values from a Property object using Nsurlprotocol ' SpropertyForKey:inRequest:and setProperty:forKey:inRequest:methods.

The mutable subclass of Nsurlrequest is nsmutableurlrequest.

Overview:

The Nsurlrequest object represents a URL-loaded request, in a sense a separate protocol and URL scheme.

The nsurlrequest encapsulates two basic data elements in one load request: The URL to be loaded, and the policy to use when querying the URL content cache for possible implementations.

Nsurlrequest is designed to extend support for additional protocols. A Property object uses the Nsurlprotocol propertyforkey:inrequest: and SetProperty:forKey:inRequest: method to add various specified access protocol values, which are supported by Nsurlrequest.

The variable nsurlrequest subclass is Nsmutableurlrequest.

Class Methods

Requestwithurl:

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

Creates and returns a URL request that points to a specified URL, with the default cache policy and time-out response duration.

+ (ID) Requestwithurl: (Nsurl *) theURL

Discussion

The default cache policy is nsurlrequestuseprotocolcachepolicy and the default timeout interval is seconds.

The default caching policy is Nsurlrequestuseprotocolcachepolicy, the default timeout time is 60 seconds.

RequestWithURL:cachePolicy:timeoutInterval:

Creates and returns an initialized URL request with specified values.

Creates and returns an initialized URL request that takes the specified cache policy and timeout length.

+ (ID) Requestwithurl: (Nsurl *) theURL CachePolicy: (nsurlrequestcachepolicy) Cachepolicytimeoutinterval: ( Nstimeinterval) timeOutInterval

Return Value

The newly created URL request.

Instance Methods

Allhttpheaderfields

Returns A dictionary containing all the receiver's HTTP header fields.

Returns a dictionary containing the HTTP header area for all recipients.

-(Nsdictionary *) allhttpheaderfields

Allowscellularaccess

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

Returns whether a request is allowed to use a cellular network.

-(BOOL) allowscellularaccess

Return Value

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

CachePolicy

Returns the receiver ' s cache policy.

Returns the cache policy for the request recipient.

-(Nsurlrequestcachepolicy) CachePolicy

Return Value

The receiver ' s cache policy.

Httpbody

Returns the receiver ' s HTTP body data.

Returns the HTTP data of the recipient.

-(NSData *) httpbody

Return Value

The receiver ' s HTTP body data.

Discussion

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

This data is sent as a request message body, just like sending a request in an HTTP.

Httpbodystream

Returns the receiver ' s HTTP body stream.

Returns the HTTP principal stream of the recipient.

-(Nsinputstream *) 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's not a safe to manipulate the stream on any.

The recipient's HTTP principal stream, nil if not set. The returned stream is for inspection only, and it is not safe to operate the stream anyway.

Discussion

The receiver'll has either an HTTP body or an HTTP body stream, and only one may is set for a request. A HTTP body stream was preserved when copying an Nsurlrequest object, but was lost when a request was archived using the Nsco Ding protocol.

The recipient will have both the HTTP principal and the HTTP principal stream, and only one will be set to the request. When it copies a Nsurlrequest object, the HTTP principal stream is retained, but is discarded when a request arrives using the Nscoding protocol.

HttpMethod

Returns the receiver ' s HTTP request method.

-(NSString *) HttpMethod

Return Value

The receiver ' s HTTP request method.

Discussion

The default HTTP method is "GET".

Returns the method that operates HTTP. The default is "GET".

Httpshouldhandlecookies

Returns whether the default cookie handling would be a used for this request.

-(BOOL) httpshouldhandlecookies

Return Value

YES if the default cookie handling is 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.

Returns whether the request requires continuous data transfer before receiving the previous transport response.

-(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: (Nsurl *) theURL

Return Value

The initialized URL request.

Discussion

The default cache policy is nsurlrequestuseprotocolcachepolicy and the default timeout interval is seconds.

InitWithURL:cachePolicy:timeoutInterval:

Returns a initialized URL request with specified values.

-(ID) Initwithurl: (Nsurl *) theURL CachePolicy: (nsurlrequestcachepolicy) Cachepolicytimeoutinterval: (NSTimeInterval ) timeOutInterval

Discussion

This was the designated initializer for nsurlrequest.

These two are initialization methods, different from the first two factory methods.

Maindocumenturl

Returns the main document URL associated with the request.

-(Nsurl *) Maindocumenturl

Return Value

The main document URL associated with the request.

Discussion

This URL was used for the cookie "same domain as main document" policy.

Networkservicetype

Returns the Network Service type of the request.

Returns the type of the requested network Service.

-(Nsurlrequestnetworkservicetype) Networkservicetype

Return Value

The Network service type of the request.

timeOutInterval

Returns the receiver ' s timeout interval, in seconds.

-(Nstimeinterval) 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 was considered to has timed out.

If a connection attempt request remains idle for a period exceeding the time-out response, the request is considered timed out.

Url

Returns the request ' s URL.

-(Nsurl *) URL

Return Value

The request ' s URL.

Valueforhttpheaderfield:

Returns the value of the specified HTTP header field.

-(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 is case-insensitive.

Returns the name of the header area, which is 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 is used to specify interaction with the cached responses.

Enum

{

Nsurlrequestuseprotocolcachepolicy = 0,

Nsurlrequestreloadignoringlocalcachedata = 1,

Nsurlrequestreloadignoringlocalandremotecachedata = 4,

Nsurlrequestreloadignoringcachedata = Nsurlrequestreloadignoringlocalcachedata,

Nsurlrequestreturncachedataelseload = 2,

Nsurlrequestreturncachedatadontload = 3,

Nsurlrequestreloadrevalidatingcachedata = 5

};

typedef Nsuinteger Nsurlrequestcachepolicy;

Constants

Nsurlrequestuseprotocolcachepolicy

Specifies that the caching logic defined in the protocol implementation, if any, was used for a particular URL load request . The default policy for URL, load requests.

Specify the cache logic in the protocol implementation. is the default policy for URL load requests.

Nsurlrequestreloadignoringlocalcachedata

Specifies that the data for the URL load should is loaded from the originating source. No existing cache data should is used to satisfy a URL load request.

Specifies that the URL load should load the source-side data, and that no existing cached data should be used to satisfy the URL load request.

Nsurlrequestreloadignoringlocalandremotecachedata

Specifies that isn't only should the local cache data is ignored, but so proxies and other intermediates should is Instruc Ted to disregard their caches so far as the protocol allows.

Specifies that not only local cache data is not used, but proxies and other intermediaries ignore their caches until the protocol allows.

Nsurlrequestreloadignoringcachedata

Replaced by Nsurlrequestreloadignoringlocalcachedata.

Nsurlrequestreturncachedataelseload

Specifies that the existing cached data should is used to satisfy the request, regardless of their age or expiration date. If There is no existing data in the cache corresponding the request, the data was loaded from the originating source.

Specifies that the stored cache data should be used in response to the request, regardless of its life time and expiration time. If there is no stored data in the cache in response to the request, the data is loaded from the source side.

Nsurlrequestreturncachedatadontload

Specifies that the existing cache data should is used to satisfy a request, regardless of their age or expiration date. If There is no existing data in the cache corresponding to a URL of load request, no attempt is made to load the data from th e originating source, and the load is considered to has failed. This constant specifies a behavior, that's similar to an "offline" mode.

Specifies that the stored cache data is used to satisfy the request, regardless of life time and expiration time. If there is no stored data in the cache in response to a URL load request, no attempt is made to load the data from the source segment, and the load request is considered to be unsuccessful. This constant specifies a behavior similar to the offline mode.

Nsurlrequestreloadrevalidatingcachedata

Specifies that the existing cache data are used provided the Origin source confirms its validity, otherwise the URL is Loaded from the Origin source.

Specifies that the cached data is allowed to respond to the request if the stored cache data is supplied with its source segment, otherwise the data is loaded from the source segment.

Nsurlrequestnetworkservicetype

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

Enum

{

Nsurlnetworkservicetypedefault = 0,

Nsurlnetworkservicetypevoip = 1,

Nsurlnetworkservicetypevideo = 2,

Nsurlnetworkservicetypebackground = 3,

Nsurlnetworkservicetypevoice = 4

};

typedef Nsuinteger NSURLREQUESTNETWORKSERVICETYPE;

Constants

Nsurlnetworkservicetypedefault

Specifies standard network traffic.

Nsurlnetworkservicetypevoip

Specifies that the request was for VoIP traffic.

Nsurlnetworkservicetypevideo

Specifies that the request was for video traffic.

Nsurlnetworkservicetypebackground

Specifies that the request was for background traffic.

Nsurlnetworkservicetypevoice

Specifies that the request was 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 the application to reduce their dependency on a network connection and increase its performance.

The URL loading system provides a mixed disk and memory cache to respond to network requests. This cache allows an application to reduce dependency on network connections and increase performance.

Using the Cache for a Request

An Nsurlrequest instance specifies how the local cache was used by setting the cache policy to one of the Nsurlrequestcache Policy Values:nsurlrequestuseprotocolcachepolicy,nsurlrequestreloadignoringcachedata, Nsurlrequestreturncachedataelseload, Ornsurlrequestreturncachedatadontload.

A Nsurlrequest instance specifies how to use the local cache by setting the Nsurlrequestcachepolicy.

The default cache policy for a nsurlrequest instance is nsurlrequestuseprotocolcachepolicy. Thensurlrequestuseprotocolcachepolicy behavior is protocol specific and are defined as being the best conforming policy for The protocol.

The default caching policy is Nsurlrequestuseprotocolcachepolicy, which is the best validation policy defined for the protocol.

Setting the cache policy to Nsurlrequestreloadignoringcachedata causes the URL of loading system to load the data from the OR Iginating source, ignoring the cache completely.

Setting the cache policy to nsurlrequestreloadignoringcachedata causes the URL loading system to load data from the source segment and completely ignore the cache.

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

The Nsurlrequestreturncachedataelseload cache policy allows the URL-loading system to use cached data, regardless of its lifecycle and expiration time, to load data from the source segment only when there is no cache.

The Nsurlrequestreturncachedatadontload policy allows an application to specify, the only data in the cache should is Retu rned. Attempting to create a nsurlconnection or Nsurldownload instance with this cache policy returns nil immediately if the RE Sponse is not in the local cache. This is similar on function to an "offline" mode and never brings up a network connection.

The Nsurlrequestreturncachedatadontload policy allows an app to specify that only the data in the cache is used. If you attempt to create a nsurlconnection or nsurldownload instance, under this cache policy, if there is no response in the local cache, nil will be returned immediately. This is somewhat similar to the offline mode feature, and never initiates a network connection.

Note: Currently, responses to HTTP and HTTPS requests is 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.

Note: Most recently, only requests that respond to HTTP and HTTPS are cached. FTP and file protocol try to access the source segment when it is allowed by the cache policy. The custom Nsurlprotocol class is able to protect the cache if they are selected for use.

Cache use semantics for the HTTP Protocol

The most complicated caches use situation are when a request uses the HTTP protocol and have set the cache policy to Nsurlreq Uestuseprotocolcachepolicy.

The most complex cache usage is when a request uses the HTTP protocol, setting the cache policy to Nsurlrequestuseprotocolcachepolicy.

If An nscachedurlresponse does isn't exist for the request, then the data was fetched from the originating source. If there is a cached response for the request, the URL of the loading system checks the response to determine if it specifies tha T the contents must be revalidated. If the contents must be revalidated a connection are 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 was fetched from the originating source.

If a nscachedurlresponse does not exist for the request, the data will be fetched from the source side. If the request has a cached response, then the URL-loading system will check the response to determine if it specifies that the content must be re-enforced. If the content has to be re-entered, a connection to the source will be established to see if the content has changed. If the content does not change, the response returns data from the local cache. If the content changes, the data is fetched from the source side.

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

If the cached response does not specify that the content must be re-effective, the response specifies the maximum lifetime and expiration of the cache is checked. If the cache response is new enough, the response returns data from the local cache. If the response you decide is old, the source will check for new data. If the new data is feasible, the data will be fetched from the source side, otherwise the data will be returned from the cache.

RFC 2616, section http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13 specifies the semantics involved in Detail.

Official documents of the Nsurlrequest "translation"