NSURLRequest & NSMutableURLR

NSURLRequest

Overview

NSURLRequest表示一个以独立于 protocol 和 URL scheme 的URL加载请求；

NSURLRequest封装了加载请求的两个基本数据元素：要加载的URL，以及查询URL内容缓存时使用的策略。

Important：NSURLRequest仅用于封装有关URL请求的信息。 你必须使用其他类（如NSURLSession或NSURLConnection）将这些请求发送到服务器。

NSURLRequest旨在通过添加为你自己的协议特定属性提供访问器方法的类别来扩展以支持其他协议。 这些方法可以通过调用NSURLProtocol方法propertyForKey：inRequest：和setProperty：forKey：inRequest：获取和设置实际值。

NSURLRequest的可变子类是NSMutableURLRequest。

Important：Swift基础框架覆盖提供了URLRequest结构体，它与NSURLRequest类及其可变子类NSMutableURLRequest进行桥接。 URLRequest值类型提供与NSURLRequest引用类型相同的功能，两者可以与Swift代码交互使用，与Objective-C API进行交互。 此行为类似于Swift将标准字符串，数字和集合类型桥接到其相应的Foundation类。

Symbols

Creating Requests

---

• + (instancetype)requestWithURL:(NSURL *)URL

  创建并返回具有默认缓存策略和超时值的URL请求。
  默认缓存策略为NSURLRequestUseProtocolCachePolicy，默认超时时间间隔为60秒。

---

• - (instancetype)initWithURL:(NSURL *)URL
  同上；

---

• + (instancetype)requestWithURL:(NSURL *)URL cachePolicy:(NSURLRequestCachePolicy)cachePolicy timeoutInterval:(NSTimeInterval)timeoutInterval

  使用指定值去初始化NSURLRequest。

  cachePolicy：新请求的缓存策略；
  timeoutInterval：新请求的超时时间，单位秒；

---

• - (instancetype)initWithURL:(NSURL *)URL cachePolicy:(NSURLRequestCachePolicy)cachePolicy timeoutInterval:(NSTimeInterval)timeoutInterval

  同上;

Getting Request Properties

---

• @property(readonly) NSURLRequestCachePolicy cachePolicy

  调用者的缓存策略；

---

• @property(readonly) BOOL HTTPShouldUsePipelining

  一个布尔值，指示在接收到之前请求的响应之前，当前请求是否应继续传输数据。
  如果请求应继续发送数据，则为YES，否则请求应等待响应。 默认值为NO。

  将此属性设置为YES值不保证HTTP的流水线行为。 如果配置了HTTP代理，或者如果HTTP请求使用不安全的请求方法（例如，POST请求不会管道），这可能不起作用。 在给定TCP连接的第二个请求之前，流水线行为可能不会开始。 即使将此属性设置为YES，也可能不会发生流水线化的其他情况。 HTTP 1.1允许客户端向服务器发送多个请求，而不必等待响应。 虽然HTTP 1.1需要对流水线的支持，但一些服务器将其自身报告为HTTP 1.1，但不支持流水线（断开连接，以错误的顺序发送资源，省略部分资源等）（不懂~~~）。

---

• @property(readonly, copy) NSURL *mainDocumentURL

  与请求相关联的主文档URL。
  以后可能会用到的属性，暂时是返回cookie "same domain as main document" policy；

---

• @property(readonly) NSTimeInterval timeoutInterval

  请求的超时时间；
  如果在连接尝试期间，请求保持空闲时间超过超时间隔，则该请求被认为已超时；
  作为一般规则，你不应该使用短暂的超时间隔。 相反，你应该为用户提供一种简单的方法来取消长时间运行的操作。

---

• @property(readonly) NSURLRequestNetworkServiceType networkServiceType

  请求的网络服务类型；
  networkServiceType为操作系统提供了关于基础流量使用的提示。 这个提示增强了系统优先流量的能力，确定唤醒蜂窝或Wi-Fi需要多快等等。 通过提供准确的信息，我们可以提高系统平衡电池寿命，性能和其他注意事项的能力。

  例如，如果您应用正在执行未被用户请求的下载，则应指定NSURLNetworkServiceTypeBackground类型，例如预取内容，以便在用户选择查看内容时可用。

---

• @property(readonly, copy) NSURL *URL

  请求的URL；

Getting HTTP Request Properties

---

• @property(readonly, copy) NSDictionary<NSString *,NSString *> *allHTTPHeaderFields

  调用者的HTTP请求的头部信息；

---

• @property(readonly, copy) NSData *HTTPBody

  调用者的HTTP请求body数据；
  该数据作为请求的消息正文发送，如HTTP POST请求。

---

• @property(readonly, retain) NSInputStream *HTTPBodyStream

  调用者的HTTP请求body流；
  如果body流尚未设置，则为nil。 返回的流仅用于检查, 以任何方式操纵流都是不安全的。
  接收器只能有HTTP body和HTTP body流中的一个。 复制NSURLRequest对象时会保留HTTP body流，但在使用NSCoding协议存档请求时丢失HTTP body流。

---

• @property(readonly, copy) NSString *HTTPMethod

  调用者的HTTP请求的方法；默认方法是"GET";

---

• @property(readonly) BOOL HTTPShouldHandleCookies

  一个布尔值，指示是否使用默认的Cookie处理此请求。默认为YES；
  如果你的应用在NSMutableURLRequest对象上设置Cookie头，则此方法不起作用，并且你在头部中设置的Cookie数据将覆盖Cookie仓库中的所有Cookie。

---

• - (NSString *)valueForHTTPHeaderField:(NSString *)field

  返回指定HTTP头部字段的值；如果不存在此字段返回nil;

Allowing Cellular Access

---

• @property(readonly) BOOL allowsCellularAccess

  是否允许使用蜂窝移动网络；
  当没有其他网络连接可用时，将此属性设置为NO将导致请求失败，返回带有NSURLErrorDomain和NSURLErrorNotConnectedToInternet domain的NSError对象。

Support for Secure Coding

---

• @property(class, readonly) BOOL supportsSecureCoding

  表示NSURLRequest是否实现NSSecureCoding协议；此属性为类属性；

Constants

---

typedef enum NSURLRequestCachePolicy : NSUInteger {
    NSURLRequestUseProtocolCachePolicy = 0,
    NSURLRequestReloadIgnoringLocalCacheData = 1,
    NSURLRequestReloadIgnoringLocalAndRemoteCacheData = 4,
    NSURLRequestReloadIgnoringCacheData = NSURLRequestReloadIgnoringLocalCacheData,
    NSURLRequestReturnCacheDataElseLoad = 2,
    NSURLRequestReturnCacheDataDontLoad = 3,
    NSURLRequestReloadRevalidatingCacheData = 5
} NSURLRequestCachePolicy;

对于HTTP协议，NSURLRequestUseProtocolCachePolicy策略的行为在NSURLRequest中。

HTTP和HTTPS的NSURLRequestUseProtocolCachePolicy决策树，如下图：

NSURLRequestCachePolicy决策树.png

简要说明：

1. 如果该请求不存在缓存的响应，则URL加载系统将从始发源获取数据。

2. 否则，如果缓存的响应并不表示它必须每次都重新生效，并且如果缓存的响应没有过时（超过其到期日期），则URL加载系统将返回缓存的响应内容。

3. 如果缓存响应过时或需要重新验证，则URL加载系统会向始发源发出HEAD请求，以查看资源是否已更改。 如果已经更改，URL加载系统将从始发源获取数据。 否则，它返回缓存的响应。

RFC 2616，第13节详细说明了这些语义。

Symbols

1. NSURLRequestUseProtocolCachePolicy

   指定在协议实现中定义的缓存逻辑，可以用于特定的URL加载请求。 这是URL加载请求的默认策略。
   如果要自定义HTTP或HTTPS在字节范围内请求，请使用NSURLRequestReloadIgnoringLocalCacheData策略。

2. NSURLRequestReloadIgnoringLocalCacheData

   指定URL加载的数据应该从始发源加载。 不应使用现有的缓存数据来做URL加载请求。

3. NSURLRequestReloadIgnoringLocalAndRemoteCacheData

   指定不仅应该忽略本地缓存数据，而且应该指示代理和其他中间设备在协议允许的情况下忽略其缓存。
   Important：该常数未实现，不应使用。

4. NSURLRequestReturnCacheDataElseLoad

   指定现有的缓存数据应用于满足请求，而不管其是否过期。 如果高速缓存中没有现有的数据对应于请求，则从始发源加载数据。

5. NSURLRequestReturnCacheDataDontLoad

   指定现有的缓存数据应用于满足请求，而不管其是否过期。 如果缓存中没有与URL加载请求相对应的现有数据，不尝试从始发源加载数据，并且认为该加载失败。 此常数指定类似于“离线”模式的行为。

6. NSURLRequestReloadRevalidatingCacheData

   指定可以使用现有的缓存数据，前提是原始源确认其有效性，否则，URL将从源文件加载。

---

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

Overview

这些常量用于指定请求的网络服务类型。

网络服务类型为操作系统提供了关于基础流量使用的提示。 这个提示增强了系统优先使用流量的能力，确定唤醒蜂窝或Wi-Fi无线电需要多快等等。 通过提供准确的信息，你可以提高系统最佳平衡电池寿命，性能和其他注意事项的能力。

Symbols

1. NSURLNetworkServiceTypeDefault

   指定标准网络流量。 大多数连接应该使用这种服务类型。

2. NSURLNetworkServiceTypeVoIP

   指定该请求用于VoIP请求。
   使用VoIP服务类型，内核在您的应用程序处于后台时继续监听传入流量，然后在新数据到达时唤醒您的应用程序。 这只能用于与VoIP服务进行通信的连接。

3. NSURLNetworkServiceTypeVideo

   指定请求是针对视频流量。

4. NSURLNetworkServiceTypeBackground

   指定请求是用于后台流量。
   如果你的应用程序正在执行未被用户请求的下载，则应指定此类型，例如，预取内容，以便在用户选择查看内容时可用。

5. NSURLNetworkServiceTypeVoice

   指定请求是针对音频流量。

6. NSURLNetworkServiceTypeCallSignaling

   指定请求是针对呼叫信令流量。（官方文档居然对这个没有解释，我也有点醉~~~）

NSMutableURLRequest

NSMutableURLRequest是NSURLRequest的子类，用于帮助开发人员，他们可能会发现，为一系列URL加载请求对单个请求对象进行突变更为方便，而不是为每个加载创建一个不可变的NSURLRequest对象。

Overview

NSURLSession，NSURLConnection和NSURLDownload类会在其初始化和任务创建方法中将每个NSMutableURLRequest对象的深拷贝传递给它们的。

Reserved HTTP Headers

URL加载系统旨在为我们处理HTTP协议的各个方面。 因此，我们不应使用addValue: forHTTPHeaderField: 或 setValue: forHTTPHeaderField:修改以下头部信息：

a. Authorization(授权);
b. Connection（连接）;
c. Host(主机);
d. WWW-Authenticate(WWW身份验证);

Symbols

Setting Request Properties

---

• @property NSURLRequestCachePolicy cachePolicy

  请求的缓存策略；
  对于用于构造NSURLSessionUploadTask和NSURLSessionDownloadTask对象的请求，此属性被忽略，因为URL加载系统不支持上传或下载请求的缓存。

---

• @property(copy) NSURL *mainDocumentURL

  调用者应给mainDocumentURL设置适当的主文档（如果已知）。 例如，当加载网页时，最顶级的frame的HTML文档的URL是适当的（不懂~~~）。 此URL将用于“仅与主文档相同的域”cookie接受策略。

nil表示没有主文档。

Setting HTTP Specific Properties

---

• - (void)addValue:(NSString *)value forHTTPHeaderField:(NSString *)field

  为HTTP头部字典添加键值对；

  value：头部字典中field对应的值；
  field：头部字段的名称。 与HTTP RFC保持一致，HTTP头部名不区分大小写。

  该方法提供了向HTTP请求头字段增加值的功能。 如果先前为指定的字段设置了一个值，则使用适当的字段分隔符将提供的值附加到现有值。 如果是HTTP请求，分隔符是逗号。

---

• @property(copy) NSDictionary<NSString *,NSString *> *allHTTPHeaderFields

  调用者的头部信息；
  HTTP头字段必须是字符串值; 因此，headerFields字典中的每个对象和键都必须是NSString的子类。 如果键值对的键或值不是NSString的子类，则键值对被跳过。

  如果可以自动确定上传body数据的长度（例如，如果您提供body一个NSData对象），则会为你设置Content-Length的值。

---

• @property(copy) NSData *HTTPBody

  请求的body部分；
  请求体作为请求的消息正文发送，如HTTP POST请求一样。 设置HTTP体数据将清除HTTPBodyStream中的输入流。 这些值是相互排斥的。

---

• @property(retain) NSInputStream *HTTPBodyStream

  请求体的输入流；
  调用者的请求体将是这个输入流。 流的全部内容将作为body发送，如HTTP POST请求一样。 输入流应该是未打开的，接收方将接管流的委托。

  设置HTTPBodyStream将清除HTTPBody中的任何数据。 这些值是相互排斥的

---

• - (void)setValue:(NSString *)value forHTTPHeaderField:(NSString *)field

  给HTTP请求头部设置值；如果该key已经存在，则更新该key对应的value；

Instance Methods

---

• - (void)bindToHotspotHelperCommand:(NEHotspotHelperCommand *)command

这个方法贼奇怪，苹果的文档里面有这个方法，但是没有任何关于这个方法的解释，在头文件中甚至找不到这个方法；