iOS NSURLRequest&&NSURLR

NSURLRequest.h

NSURLRequest

• NSURLRequest 对象代表独立于协议的URL加载请求。

• NSURLRequest 封装了加载请求的两个基本元素: URL，缓存策略。

• NSURLRequest 可以通过添加 category 来支持其他的协议，使用 NSURLProtocol 的 propertyForKey:inRequest: 方法和setProperty:forKey:inRequest: 方法，可以访问属性对象的协议值。

• NSURLRequest 对应的可变类为 NSMutableURLRequest。

• 创建请求

• requestWithURL:
  – initWithURL:
• requestWithURL:cachePolicy:timeoutInterval:
  – initWithURL:cachePolicy:timeoutInterval:

获取请求属性
– cachePolicy
– HTTPShouldUsePipelining
– mainDocumentURL
– timeoutInterval
– networkServiceType
– URL

获取HTTP请求属性
– allHTTPHeaderFields
– HTTPBody
– HTTPBodyStream
– HTTPMethod
– HTTPShouldHandleCookies
– valueForHTTPHeaderField:

类方法
requestWithURL:
创建并返回使用 默认缓存策略 + 默认超时时间 + 指定URL 的请求。

• (id)requestWithURL:(NSURL *)theURL
  theURL: 请求的URL
  返回值： 新建的URL请求。
  默认的缓存策略是 NSURLRequestUseProtocolCachePolicy 。
  默认的超时时间是 60s。

requestWithURL:cachePolicy:timeoutInterval:
创建并返回使用 指定缓存策略 + 指定超时时间 + 指定URL 的请求。

• (id)requestWithURL:(NSURL *)theURL
  cachePolicy:(NSURLRequestCachePolicy)cachePolicy
  timeoutInterval:(NSTimeInterval)timeoutInterval
  theURL: 请求的URL
  cachePolicy: 请求的缓存策略
  timeoutInterval: 请求的超时时间，以秒为单位。
  返回值： 新建的URL请求

实例方法

allHTTPHeaderFields

• (NSDictionary *)allHTTPHeaderFields
  返回值： 包含HTTP头所有字段的字典

allowsCellularAccess

• (BOOL)allowsCellularAccess
  返回值： YES蜂窝数据可用，NO蜂窝数据不可用。

cachePolicy

• (NSURLRequestCachePolicy)cachePolicy
  返回值： 该请求使用的缓存策略。

HTTPBody

• (NSData *)HTTPBody
  返回值： 请求体。

HTTPBodyStream

• (NSInputStream *)HTTPBodyStream
  返回值： 请求的输入流。如果未设置，则返回nil。这个流只能用来检验，其他操作都是不可靠的。
  一个请求要么设置了请求体（HTTP Body），要么设置了输入流（HTTP Body Stream），只能设置一个。
  输入流在复制NSURLRequest对象时被保留，但是用NSCoding协议归档的时候将丢失。

HTTPMethod

• (NSString *)HTTPMethod
  返回值：请求方法。 默认是“GET”
  HEAD - 只传递头信息，没有请求体，也没有响应体。
  GET - 查询资源
  PUT - 新增资源
  POST - 更新资源
  DELETE - 删除资源

---

HTTPShouldHandleCookies

• (BOOL)HTTPShouldHandleCookies
  返回值： YES 使用默认cookie处理，NO不使用。
  默认值为YES。

HTTPShouldUsePipelining
返回在接到上一个请求的响应之前，是否需要传输数据。

• (BOOL)HTTPShouldUsePipelining
  返回值： YES 传输，NO 不传输。

initWithURL:
初始化使用 默认缓存策略 + 默认超时时间 + 指定URL 的请求。

• (id)initWithURL:(NSURL *)theURL
  theURL: 请求的URL
  返回值： 新建的URL请求。
  默认的缓存策略是 NSURLRequestUseProtocolCachePolicy 。
  默认的超时时间是 60s。

initWithURL:cachePolicy:timeoutInterval:
初始化使用 指定缓存策略 + 指定超时时间 + 指定URL 的请求。

• (id)initWithURL:(NSURL *)theURL
  cachePolicy:(NSURLRequestCachePolicy)cachePolicy
  timeoutInterval:(NSTimeInterval)timeoutInterval
  theURL: 请求的URL
  cachePolicy: 请求的缓存策略
  timeoutInterval: 请求的超时时间，以秒为单位。
  返回值： 新建的URL请求

mainDocumentURL

• (NSURL *)mainDocumentURL
  返回值： 请求对应URL的主文档。

networkServiceType

• (NSURLRequestNetworkServiceType)networkServiceType
  返回值： 网络服务类型。
  网络服务类型给操作系统提示底层通信的作用。这个提示有助于系统优化通信，确定唤醒蜂窝数据或者WIFI的速度。调节不同的参数，可以平衡电池、性能以及其他因素。
  比如，进行非用户请求的下载时应该使用 NSURLNetworkServiceTypeBackground。 比如，在后台提前加载数据，这样等用户需要看时就不需要加载了。

supportsSecureCoding
表明 NSURLRequest 是否实现了 NSSecureCoding 协议。

• (BOOL)supportsSecureCoding
  返回值： YES 实现了 NSSecureCoding 协议，NO未实现。

timeoutInterval

• (NSTimeInterval)timeoutInterval
  返回值： 请求的超时时间，单位秒。

URL

• (NSURL *)URL

valueForHTTPHeaderField:

• (NSString *)valueForHTTPHeaderField:(NSString *)field
  field: 头字段的名字。 忽略大小写。
  返回值： 头字段的值，如果没有该字段，则返回nil。

NSMutableURLRequest

概述

NSMutableURLRequest 是 NSURLRequest 的子类。多个请求时，可以只创建一个可变对象，而不需要为每一个加载创建一个不可变的 NSURLRequest 对象。
NSURLSession，NSURLConnection 和 NSURLDownload 类初始化时对 NSMutableURLRequest 对象是进行的深度复制。

注意： 这个类只是封装URL请求的信息。 要真正发出请求，需要使用其他的类，比如NSURLSession、NSURLConnection。
参考：URL Loading System Programming Guide

作用

设置请求属性
– setCachePolicy:
– setMainDocumentURL:
– setNetworkServiceType:
– setTimeoutInterval:
– setURL:
– setAllowsCellularAccess:

设置HTTP具体属性
– addValue:forHTTPHeaderField:
– setAllHTTPHeaderFields:
– setHTTPBody:
– setHTTPBodyStream:
– setHTTPMethod:
– setHTTPShouldHandleCookies:
– setHTTPShouldUsePipelining:
– setValue:forHTTPHeaderField:

实例方法

addValue:forHTTPHeaderField:
向HTTP头字典中加入一个HTTP头值。

• (void)addValue:(NSString *)value forHTTPHeaderField:(NSString *)field
  value: 头字段的值
  field： 头字段的名字。为了跟HTTP RFC保持一致，这里头字段的名字忽略大小写。
  这个方法可以向头字段中增加值。 如果指定头字段已经有值了，那么新的值将会被添加到原有的值后面。中间加上合适的分隔符。 在HTTP中，分隔符是逗号。

注意：NSURLConnection 和 NSURLSession 是用来处理HTTP协议的各个方面的。 因此，下面这些头不应该修改：
Authorization
Connection
Host
WWW-Authenticate
此外，如果上传的请求体的大小可以通过计算得出（比如请求体的内容是一个NSData对象），那么Content-Length这个头也是设置好了的。

setAllHTTPHeaderFields:
替换指定头字段的值。

• (void)setAllHTTPHeaderFields:(NSDictionary *)headerFields
  headerFields: 新的头字段和值的字典。 头字段必须是字符串类型的，因此，字典的键值都必须是NSString的子类。如果有一组键值其中有一个不是NSString的子类，那么这一组键值将被忽略。
  注意：NSURLConnection 和 NSURLSession 是用来处理HTTP协议的各个方面的。 因此，下面这些头不应该修改：
  Authorization
  Connection
  Host
  WWW-Authenticate
  此外，如果上传的请求体的大小可以通过计算得出（比如请求体的内容是一个NSData对象），那么Content-Length这个头也是设置好了的。

setAllowsCellularAccess:
设置连接是否可以使用蜂窝数据（如果存在的话）

• (void)setAllowsCellularAccess:(BOOL)allow
  allow： YES可以使用，NO不能使用。 默认是YES。

setCachePolicy:
设置缓存策略。

• (void)setCachePolicy:(NSURLRequestCachePolicy)policy
  policy: 新的缓存策略。

setHTTPBody:
设置请求体的具体值。

• (void)setHTTPBody:(NSData *)data
  data： 新的请求体。这个方法会修改请求的信息体，就像HTTP Post请求中的一样。
  设置了这个值，会自动把setHTTPBodyStream:的值清空。 这两个方法是互斥的。

setHTTPBodyStream:
设置请求体的具体输入流内容。

• (void)setHTTPBodyStream:(NSInputStream *)inputStream
  inputStream: 请求体的输入流。流的整个内容都是请求体，就像HTTP Post请求中的一样。
  inputStream应该是未打开的，请求本身会接管流的代理。
  设置了这个值，会自动把setHTTPBody:的值清空。 这两个方法是互斥的。

setHTTPMethod:
设置HTTP的请求方式。

• (void)setHTTPMethod:(NSString *)method
  method: 请求方式。 默认是GET。

setHTTPShouldHandleCookies:
设置是否使用默认cookie处理方式

• (void)setHTTPShouldHandleCookies:(BOOL)handleCookies
  handleCookies: YES使用默认的，NO不使用默认的。默认YES。
  如果 NSMutableURLRequest 对象设置了Cookie 头， 那么这个方法不起作用。头里设置的Cookie会覆盖所有的cookie。

setHTTPShouldUsePipelining:
设置在接到前一个请求的响应之前，是否传输数据。

• (void)setHTTPShouldUsePipelining:(BOOL)shouldUsePipelining
  shouldUsePipelining: YES传输，NO不传输。默认NO。

setMainDocumentURL:
设置URL的主文档。

• (void)setMainDocumentURL:(NSURL *)theURL
  theURL: URL的主文档。可以为nil。
  这个值需要合理设置。 比如，加载一个网页的时候，从最顶层的HTML文档开始加载比较合理。这个URL的cookie遵守同源策略。

setNetworkServiceType:
设置连接的服务类型。

• (void)setNetworkServiceType:(NSURLRequestNetworkServiceType)networkServiceType
  networkServiceType: 网络服务类型。

setTimeoutInterval:
设置超时时间，单位秒。

• (void)setTimeoutInterval:(NSTimeInterval)timeoutInterval
  timeoutInterval: 超时时间，单位秒。默认60s。
  注意： iOS6之前，最小的超时时间（也是默认的超时时间）是240s。

通常情况下，超时时间不要设置的太短。最好是给用户提供一个取消长时间操作的方法。详细信息，参考：Designing for Real-World Networks。

setURL:

• (void)setURL:(NSURL *)theURL

setValue:forHTTPHeaderField:
设置HTTP头字段的值。

• (void)setValue:(NSString *)value forHTTPHeaderField:(NSString *)field
  value: 头字段的值。覆盖原来的值。
  field：头字段的名字。 忽略大小写。
  注意：NSURLConnection 和 NSURLSession 是用来处理HTTP协议的各个方面的。 因此，下面这些头不应该修改：
  Authorization
  Connection
  Host
  WWW-Authenticate
  此外，如果上传的请求体的大小可以通过计算得出（比如请求体的内容是一个NSData对象），那么Content-Length这个头也是设置好了的。

NSURLResponse

//初始化方法

• (instancetype)initWithURL:(NSURL *)URL MIMEType:(nullable NSString *)MIMEType expectedContentLength:(NSInteger)length textEncodingName:(nullable NSString *)name NS_DESIGNATED_INITIALIZER;

返回数据的数据类型（纯文本，视频，语音，超文本等）
@property (nullable, readonly, copy) NSString *MIMEType;

将要返回的数据的大小
@property (readonly) long long expectedContentLength;

编码的名称
@property (nullable, readonly, copy) NSString *textEncodingName;

获取服务器的文件的名称
@property (nullable, readonly, copy) NSString *suggestedFilename;

返回数据的头部信息，key－value格式
NSDictionary* allHeaderFields：

NSHTTPURLResponse

概述：
NSHTTPURLResponse 类是NSURLResponse的子类，可以访问HTTP协议的响应信息。使用HTTP URL发送请求时，无论是通过NSURLSession，NSURLConnection，还是NSURLDownload，它们的响应都是NSHTTPURLResponse 的实例。

作用：

1. 初始化Response对象

• (id)initWithURL:statusCode:HTTPVersion:headerFields:

2. 获取HTTP响应头

• (NSDictionary *)allHeaderFields

3. 获取HTTP响应状态码

• (NSString *)localizedStringForStatusCode:

• (NSDictionary *)allHeaderFields

• (NSString *)localizedStringForStatusCode:(NSInteger)statusCode;
  返回指定状态码对应的描述。

实例方法：
allHeaderFields
获取所有的HTTP响应头
HTTP头是忽略大小写的。为了简化代码，头字段都使用规范的标准格式。
比如，服务器发送 content-length，将自动调整为 Content-Length。
返回的头字典，在 set 操作时，是保留大小写的，除非已经有另一种大小写格式的存在了。查询key的时候是忽略大小写的。
比如，设置的时候，使用 X-foo， 后面再设置的时候，使用了X-Foo。那么，头字典将仍然使用X-foo，但是值更新成X-Foo的值。

initWithURL:statusCode:HTTPVersion:headerFields:
初始化HTTP响应对象
url： 产生响应的url
statusCode: 返回的HTTP状态码
HTTPVersion: HTTP响应的版本。通常是 "HTTP/1.1”
headerFields： 服务器传回来的响应头的字典