NSHTTPCookieStorage（Objective-C）
继承自：NSObject
遵守协议：NSObject
导入声明：@import Foundation;
适用范围：iOS 2.0 及以后
一、概述（Overview）
NSHTTPCookieStorage 是一个用来管理 cookie 存储的单例。一个 NSHTTPCookie 单例代表一个 cookie。通常来讲，cookie 可以在应用间共享，并且在进程之间保持同步。 对于单进程，Session cookies （这里的 cookie 对象的 isSessionOnly 方法返回 YES）是局部的并且不能被共享。
iOS 说明
在 iOS 中，应用间是不能共享 cookie 的。
说明
cookie 接收策略（Cookie Accept Policy）的改变会对所有正在运行的使用 cookie 存储的应用产生影响。
在 OS X 10.9 及以后和 iOS 7 及以后，NSHTTPCookieStorage 是线程安全的。
二、功能（Tasks）
1.创建并初始化一个 NSHTTPCookieStorage 对象（Creating and Initializing a Cookie Storage Object）
- initWithStorageLocation: Available in iOS 4.0 through iOS 4.3
2.获取共享的 NSHTTPCookieStorage 对象（Getting the Shared Cookie Storage Object）
+ sharedHTTPCookieStorage
Returns the shared cookie storage instance.
Declaration
+ (NSHTTPCookieStorage *)sharedHTTPCookieStorage
Return Value
The shared cookie storage instance.
Availability
Available in iOS 2.0 and later.
3.获取和设置Cookie Accept Policy（Getting and Setting the Cookie Accept Policy）
cookieAcceptPolicy Property
The cookie storage’s cookie accept policy.
Declaration
@property NSHTTPCookieAcceptPolicy cookieAcceptPolicy
Discussion
The default cookie accept policy is NSHTTPCookieAcceptPolicyAlways
. Changing the cookie policy affects all currently running applications using the cookie storage.
Availability
Available in iOS 2.0 and later.
4.添加和删除 cookie（Adding and Removing Cookies）
Deletes the specified cookie from the cookie storage.
Declaration
- (void)deleteCookie:(NSHTTPCookie *)aCookie
Parameters
| 参数 | 含义 |
|---|---|
| aCookie | The cookie to delete. |
Availability
Available in iOS 2.0 and later.
Stores a specified cookie in the cookie storage if the cookie accept policy permits.
Declaration
- (void)setCookie:(NSHTTPCookie *)aCookie
Parameters
| 参数 | 含义 |
|---|---|
| aCookie | The cookie to store. |
Discussion
The cookie replaces an existing cookie with the same name, domain, and path, if one exists in the cookie storage. This method accepts the cookie only if the receiver’s cookie accept policy isNSHTTPCookieAcceptPolicyAlways or NSHTTPCookieAcceptPolicyOnlyFromMainDocumentDomain. The cookie is ignored if the receiver’s cookie accept policy is NSHTTPCookieAcceptPolicyNever.
Availability
Available in iOS 2.0 and later.
- setCookies:forURL:mainDocumentURL:
Adds an array of cookies to the receiver if the receiver’s cookie acceptance policy permits.
Declaration
- (void)setCookies:(NSArray<NSHTTPCookie *> *)cookies
forURL:(NSURL *)theURL
mainDocumentURL:(NSURL *)mainDocumentURL
Parameters
| 参数 | 含义 |
|---|---|
| cookies | The cookies to add. |
| theURL | The URL associated with the added cookies. |
| mainDocumentURL | The URL of the main HTML document for the top-level frame, if known. Can be nil. This URL is used to determine if the cookie should be accepted if the cookie accept policy is NSHTTPCookieAcceptPolicyOnlyFromMainDocumentDomain. |
Discussion
The cookies will replace existing cookies with the same name, domain, and path, if one exists in the cookie storage. The cookie will be ignored if the receiver's cookie accept policy is NSHTTPCookieAcceptPolicyNever.
To store cookies from a set of response headers, an application can use cookiesWithResponseHeaderFields:forURL: passing a header field dictionary and then use this method to store the resulting cookies in accordance with the receiver’s cookie acceptance policy.
Availability
Available in iOS 2.0 and later.
5.读取 cookie （Retrieving Cookies）
cookies Property
The cookie storage’s cookies. (read-only)
Declaration
@property(readonly, copy) NSArray <NSHTTPCookie *> *cookies
Discussion
If you want to sort the cookie storage’s cookies, you should use the sortedCookiesUsingDescriptors: method instead of sorting the result of this method.
Availability
Available in iOS 2.0 and later.
See Also
– cookiesForURL:
Returns all the cookie storage’s cookies that are sent to a specified URL.
Declaration
- (NSArray <NSHTTPCookie *> *)cookiesForURL:(NSURL *)theURL
Parameters
| 参数 | 含义 |
|---|---|
| theURL | The URL to filter on. |
Return Value
An array of cookies whose URL matches the provided URL.
Discussion
An application can use NSHTTPCookie method requestHeaderFieldsWithCookies: to turn this array into a set of header fields to add to an NSMutableURLRequest object.
Availability
Available in iOS 2.0 and later.
See Also
– cookies
- sortedCookiesUsingDescriptors:
Returns all of the cookie storage’s cookies, sorted according to a given set of sort descriptors.
Declaration
- (NSArray)<NSHTTPCookie *> *)sortedCookiesUsingDescriptors:(NSArray <NSSortDescriptor *> *)sortOrder
Parameters
| 参数 | 含义 |
|---|---|
| sortOrder | The sort descriptors to use for sorting, as an array of NSSortDescriptor objects. |
Return Value
The cookie storage’s cookies, sorted according to sortOrder
, as an array of NSHTTPCookie objects.
Availability
Available in iOS 5.0 and later.
三、数据类型（Data Types）
NSHTTPCookieAcceptPolicy
specifies the cookie acceptance policies implemented by theNSHTTPCookieStorage
class.
Declaration
typedef enum {
NSHTTPCookieAcceptPolicyAlways, // Accept all cookies. This is the default cookie accept policy. Available in iOS 2.0 and later.
NSHTTPCookieAcceptPolicyNever, // Reject all cookies. Available in iOS 2.0 and later.
NSHTTPCookieAcceptPolicyOnlyFromMainDocumentDomain // Accept cookies only from the main document domain. Available in iOS 2.0 and later.
} NSHTTPCookieAcceptPolicy;
四、通知（Notifications）
NSHTTPCookieManagerCookiesChangedNotification
This notification is posted when the cookies stored in the NSHTTPCookieStorage instance have changed.
In OS X, cookies are shared among applications, meaning this notification can be sent in response to another application’s actions. Cookies are not shared among applications in iOS.
The notification object is the NSHTTPCookieStorage instance. This notification does not contain a userInfo dictionary.
NSHTTPCookieManagerAcceptPolicyChangedNotification
This notification is posted when the acceptance policy of the NSHTTPCookieStorage instance has changed.
In OS X, cookies are shared among applications, meaning this notification can be sent in response to another application’s actions. Cookies are not shared among applications in iOS.
The notification object is the NSHTTPCookieStorage instance. This notification does not contain a userInfo dictionary.
参考（Reference）
问题（Question）
- NSHTTPCookieStorage 在什么场景下需要用到？
