版本記錄

前言

我們做APP發(fā)起網(wǎng)絡(luò)請求靶衍，一般都是使用框架邀层，這些框架的底層也都是蘋果的API棕洋，接下來幾篇就一起來看一下和網(wǎng)絡(luò)有關(guān)的幾個類微饥。感興趣的可以看上面幾篇文章逗扒。
1. 詳細解析幾個和網(wǎng)絡(luò)請求有關(guān)的類 （一） —— NSURLSession
2. 詳細解析幾個和網(wǎng)絡(luò)請求有關(guān)的類（二） —— NSURLRequest和NSMutableURLRequest
3. 詳細解析幾個和網(wǎng)絡(luò)請求有關(guān)的類（三） —— NSURLConnection
4. 詳細解析幾個和網(wǎng)絡(luò)請求有關(guān)的類（四） —— NSURLSession和NSURLConnection的區(qū)別
5. 詳細解析幾個和網(wǎng)絡(luò)請求有關(guān)的類（五） —— 關(guān)于NSURL加載系統(tǒng)（一）
6. 詳細解析幾個和網(wǎng)絡(luò)請求有關(guān)的類（六） —— 使用NSURLSession（二）
7. 詳細解析幾個和網(wǎng)絡(luò)請求有關(guān)的類（七） —— URL數(shù)據(jù)的編碼和解碼（三）
8. 詳細解析幾個和網(wǎng)絡(luò)請求有關(guān)的類（八） —— 處理重定向和其他請求更改（四）
9. 詳細解析幾個和網(wǎng)絡(luò)請求有關(guān)的類（九） —— 身份驗證挑戰(zhàn)和TLS鏈驗證（五）
10. 詳細解析幾個和網(wǎng)絡(luò)請求有關(guān)的類（十） —— 理解獲取緩存（六）
11. 詳細解析幾個和網(wǎng)絡(luò)請求有關(guān)的類（十一） —— Cookies和自定義協(xié)議（七）
12. 詳細解析幾個和網(wǎng)絡(luò)請求有關(guān)的類（十二） —— URL Session的生命周期（八）
13. 詳細解析幾個和網(wǎng)絡(luò)請求有關(guān)的類（十三） —— NSURLResponse（一）
14. 詳細解析幾個和網(wǎng)絡(luò)請求有關(guān)的類（十四） —— NSHTTPCookie（一）

回顧

上一篇講述關(guān)于NSHTTPCookie，下面這篇我們就主要看一下NSHTTPCookieStorage欠橘。

基本信息

首先我們看一下該類的基本信息矩肩。

1. Overview

管理cookie存儲的單例對象（共享實例）。

每個cookie都由NSHTTPCookie類的實例表示肃续。 通常黍檩，Cookie在所有應(yīng)用程序之間共享，并跨越進程邊界保持同步始锚。 Session cookie（cookie對象的sessionOnly方法返回true）對于單個進程是本地的刽酱，不共享。

iOS Note：在iOS中cookie在程序之間是不共享的瞧捌。

注意：對cookie接受策略所做的更改會影響使用cookie存儲的所有當前正在運行的應(yīng)用程序棵里。

當你訪問一個網(wǎng)站時，NSURLRequest都會幫你主動記錄下來你訪問的站點設(shè)置的Cookie姐呐，如果 Cookie 存在的話殿怜，會把這些信息放在 NSHTTPCookieStorage 容器中共享，當你下次再訪問這個站點時曙砂，NSURLRequest會拿著上次保存下來了的Cookie繼續(xù)去請求头谜。

NSHTTPCookieStorage 實現(xiàn)了一個管理Cookie的單例對象(只有一個實例)，每個Cookie都是NSHTTPCookie類的實例鸠澈，作為一個規(guī)則乔夯，Cookie在所有應(yīng)用之間共享并在不同進程之間保持同步。Session Cookie(一個isSessionOnly方法返回YES的Cookie)只能在單一進程中使用款侵。

2. Thread Safety - 線程安全

在macOS 10.9及更高版本和iOS 7及更高版本中，NSHTTPCookieStorage是線程安全的侧纯。

Topics

1. Creating and Initializing a Cookie Storage Object - 創(chuàng)建和初始化Cookie Storage對象

• - initWithStorageLocation:
  • 返回一個具有給定文件系統(tǒng)位置的初始化NSHTTPCookieStorage對象新锈，以將Cookie信息存儲在磁盤上。

2. Getting the Shared Cookie Storage Object - 獲取共享的Cookie Storage對象

• sharedHTTPCookieStorage
  • 獲取共享的Cookie Storage對象
• + sharedCookieStorageForGroupContainerIdentifier:

3. Getting and Setting the Cookie Accept Policy - 獲取和設(shè)置Cookie Accept Policy

• cookieAcceptPolicy
  • cookie storage的cookie接受策略眶熬。

4. Adding and Removing Cookies - 增加和移除Cookie

• - removeCookiesSinceDate:

• - deleteCookie:

  • 從cookie storage中刪除指定的cookie

• - setCookie:

  • 如果cookie接受策略許可妹笆，則將指定的cookie存儲在cookie存儲中块请。

• - setCookies:forURL:mainDocumentURL:

  • 如果接收者的cookie接受策略允許，則向接收者添加一系列cookie拳缠。

• - storeCookies:forTask:

5. Retrieving Cookies - 檢索Cookies

• cookies
• - getCookiesForTask:completionHandler:
• - cookiesForURL:
  • 返回發(fā)送到指定URL的所有Cookie存儲的Cookie墩新。
• - sortedCookiesUsingDescriptors:
  • 返回所有Cookie存儲的Cookie，按照給定的一組排序描述符進行排序窟坐。

6. Constants

• NSHTTPCookieAcceptPolicy
  • NSHTTPCookieAcceptPolicy指定由NSHTTPCookieStorage類實現(xiàn)的Cookie接受策略海渊。

7. Notifications

• NSHTTPCookieManagerCookiesChangedNotification
  • 當存儲在NSHTTPCookieStorage實例中的Cookie發(fā)生更改時，會發(fā)布此通知哲鸳。
• NSHTTPCookieManagerAcceptPolicyChangedNotification
  • 此通知在NSHTTPCookieStorage實例的接受策略已更改時發(fā)布臣疑。

API 文檔

NSHTTPCookieStorage分類

接下來我們看一下API文檔，我在里面增加了注釋徙菠。

#import <Foundation/NSObject.h>
#import <Foundation/NSNotification.h>

@class NSArray<ObjectType>;
@class NSHTTPCookie;
@class NSURL;
@class NSDate;
@class NSURLSessionTask;
@class NSSortDescriptor;

NS_ASSUME_NONNULL_BEGIN

/*!
    @enum NSHTTPCookieAcceptPolicy
    @abstract Values for the different cookie accept policies
    @constant NSHTTPCookieAcceptPolicyAlways Accept all cookies
    @constant NSHTTPCookieAcceptPolicyNever Reject all cookies
    @constant NSHTTPCookieAcceptPolicyOnlyFromMainDocumentDomain Accept cookies
    only from the main document domain
*/
// 這里是不同cookie接受策略的值
typedef NS_ENUM(NSUInteger, NSHTTPCookieAcceptPolicy) {
    // 接受所有的cookie
    NSHTTPCookieAcceptPolicyAlways,

    // 拒絕所有的cookie
    NSHTTPCookieAcceptPolicyNever,
    
    //只接受來自主文件域的cookie
    NSHTTPCookieAcceptPolicyOnlyFromMainDocumentDomain
};


@class NSHTTPCookieStorageInternal;

/*!
    @class NSHTTPCookieStorage 
    @discussion NSHTTPCookieStorage implements a singleton object (shared
    instance) which manages the shared cookie store.  It has methods
    to allow clients to set and remove cookies, and get the current
    set of cookies.  It also has convenience methods to parse and
    generate cookie-related HTTP header fields.
*/
// NSHTTPCookieStorage實現(xiàn)了一個管理共享cookie存儲的單例對象（共享實例）讯沈。 它具有允許客戶設(shè)置和刪除Cookie的方法，并獲得當前的一組Cookie婿奔。 它還具有解析和生成與cookie相關(guān)的HTTP頭字段的便捷方法缺狠。

@interface NSHTTPCookieStorage : NSObject
{
    @private
    NSHTTPCookieStorageInternal *_internal;
}

/*!
    @property sharedHTTPCookieStorage
    @abstract Get the shared cookie storage in the default location.
    @result The shared cookie storage
    @discussion Starting in OS X 10.11, each app has its own sharedHTTPCookieStorage singleton, 
    which will not be shared with other applications.
*/
// 獲取在默認位置的共享cookie storage。從OS X 10.11開始萍摊，
// 每一個app都有自己的sharedHTTPCookieStorage單例挤茄，不會和其他程序分享。

@property(class, readonly, strong) NSHTTPCookieStorage *sharedHTTPCookieStorage;

/*!
    @method sharedCookieStorageForGroupContainerIdentifier:
    @abstract Get the cookie storage for the container associated with the specified application group identifier
    @param identifier The application group identifier
    @result A cookie storage with a persistent store in the application group container
    @discussion By default, applications and associated app extensions have different data containers, which means
    that the sharedHTTPCookieStorage singleton will refer to different persistent cookie stores in an application and
    any app extensions that it contains. This method allows clients to create a persistent cookie storage that can be
    shared among all applications and extensions with access to the same application group. Subsequent calls to this
    method with the same identifier will return the same cookie storage instance.
 */
// 獲取與指定應(yīng)用程序組標識符關(guān)聯(lián)的容器的Cookie存儲记餐。
// identifier：應(yīng)用程序組標識符
// result：在應(yīng)用程序組容器中具有持久性存儲的Cookie存儲
// 默認情況下驮樊，應(yīng)用程序和關(guān)聯(lián)的應(yīng)用程序擴展具有不同的數(shù)據(jù)容器，
// 這意味著sharedHTTPCookieStorage單例將引用應(yīng)用程序中的不同持久性cookie
// 存儲以及它包含的任何應(yīng)用程序擴展片酝。 此方法允許客戶端創(chuàng)建持久性cookie存儲囚衔，
// 可以在所有應(yīng)用程序和擴展中共享，并訪問相同的應(yīng)用程序組雕沿。 隨后使用相同標識符調(diào)用
// 此方法將返回相同的cookie存儲實例练湿。

+ (NSHTTPCookieStorage *)sharedCookieStorageForGroupContainerIdentifier:(NSString *)identifier API_AVAILABLE(macos(10.11), ios(9.0), watchos(2.0), tvos(9.0));

/*!
    @abstract Get all the cookies
    @result An NSArray of NSHTTPCookies
*/
// 獲取所有的cookies

@property (nullable , readonly, copy) NSArray<NSHTTPCookie *> *cookies;

/*!
    @method setCookie:
    @abstract Set a cookie
    @discussion The cookie will override an existing cookie with the
    same name, domain and path, if any.
*/
// 設(shè)置cookie，該cookie將覆蓋具有相同名稱审轮，域和路徑的現(xiàn)有cookie肥哎，如果有的話。

- (void)setCookie:(NSHTTPCookie *)cookie;

/*!
    @method deleteCookie:
    @abstract Delete the specified cookie
*/
// 刪除指定的cookie
- (void)deleteCookie:(NSHTTPCookie *)cookie;

/*!
 @method removeCookiesSince:
 @abstract Delete all cookies from the cookie storage since the provided date.
 */
// 刪除指定日期cookie storage中所有的cookie

- (void)removeCookiesSinceDate:(NSDate *)date API_AVAILABLE(macos(10.10), ios(8.0), watchos(2.0), tvos(9.0));

/*!
    @method cookiesForURL:
    @abstract Returns an array of cookies to send to the given URL.
    @param URL The URL for which to get cookies.
    @result an NSArray of NSHTTPCookie objects.
    @discussion The cookie manager examines the cookies it stores and
    includes those which should be sent to the given URL. You can use
    <tt>+[NSCookie requestHeaderFieldsWithCookies:]</tt> to turn this array
    into a set of header fields to add to a request.
*/
// 返回要發(fā)送到給定URL的Cookie數(shù)組疾渣。
// Cookie管理器檢查它存儲的cookie篡诽，其中包含應(yīng)發(fā)送到給定URL的cookie。 
// 您可以使用<tt> + [NSCookie requestHeaderFieldsWithCookies：] </ tt>
// 將此數(shù)組轉(zhuǎn)換為一組頭字段以添加到請求中

- (nullable NSArray<NSHTTPCookie *> *)cookiesForURL:(NSURL *)URL;

/*!
    @method setCookies:forURL:mainDocumentURL:
    @abstract Adds an array cookies to the cookie store, following the
    cookie accept policy.
    @param cookies The cookies to set.
    @param URL The URL from which the cookies were sent.
    @param mainDocumentURL The main document URL to be used as a base for the "same
    domain as main document" policy.
    @discussion For mainDocumentURL, the caller should pass the URL for
    an appropriate main document, if known. For example, when loading
    a web page, the URL of the main html document for the top-level
    frame should be passed. To save cookies based on a set of response
    headers, you can use <tt>+[NSCookie
    cookiesWithResponseHeaderFields:forURL:]</tt> on a header field
    dictionary and then use this method to store the resulting cookies
    in accordance with policy settings.
*/
// 將cookie數(shù)組添加到cookie store榴捡，遵守cookie 接受策略杈女。 
// mainDocumentURL: 主要文檔URL用作“與主文檔相同的域”策略的基礎(chǔ)
// 對于mainDocumentURL，調(diào)用者應(yīng)該傳遞適當主文檔的URL（如果知道）。 
// 例如达椰，在加載網(wǎng)頁時翰蠢，應(yīng)傳遞頂層框架的主要html文檔的URL。 
// 要根據(jù)一組響應(yīng)頭保存cookie啰劲，您可以在頭字段字典中使用<tt> + [NSCookie cookiesWithResponseHeaderFields：forURL：] </ tt>梁沧，
// 然后使用此方法根據(jù)策略設(shè)置存儲生成的cookie。

- (void)setCookies:(NSArray<NSHTTPCookie *> *)cookies forURL:(nullable NSURL *)URL mainDocumentURL:(nullable NSURL *)mainDocumentURL;

/*!
    @abstract The cookie accept policy preference of the
    receiver.
*/
// 接收者的cookie可接受策略蝇裤。

@property NSHTTPCookieAcceptPolicy cookieAcceptPolicy;

/*!
  @method sortedCookiesUsingDescriptors:
  @abstract Returns an array of all cookies in the store, sorted according to the key value and sorting direction of the NSSortDescriptors specified in the parameter.
  @param sortOrder an array of NSSortDescriptors which represent the preferred sort order of the resulting array.
  @discussion proper sorting of cookies may require extensive string conversion, which can be avoided by allowing the system to perform the sorting.  This API is to be preferred over the more generic -[NSHTTPCookieStorage cookies] API, if sorting is going to be performed.
*/
// 返回存儲區(qū)中所有Cookie的數(shù)組廷支，根據(jù)參數(shù)中指定的NSSortDescriptors的鍵值和排序方向進行排序
// sortOrder：一個NSSortDescriptors數(shù)組，表示結(jié)果數(shù)組的首選排序順序
// 恰當?shù)胤诸恈ookies可能需要大量的字符串轉(zhuǎn)換猖辫，這可以通過允許系統(tǒng)執(zhí)行分類來避免酥泞。 
// 如果要執(zhí)行排序，則此API比更通用的[NSHTTPCookieStorage cookie] API更受歡迎

- (NSArray<NSHTTPCookie *> *)sortedCookiesUsingDescriptors:(NSArray<NSSortDescriptor *> *) sortOrder API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));

@end

NSHTTPCookieStorage分類NSURLSessionTaskAdditions

這個是針對給定任務(wù)的NSHTTPCookieStorage分類

@interface NSHTTPCookieStorage (NSURLSessionTaskAdditions)

// 根據(jù)給定的task存儲Cookie
- (void)storeCookies:(NSArray<NSHTTPCookie *> *)cookies forTask:(NSURLSessionTask *)task API_AVAILABLE(macos(10.10), ios(8.0), watchos(2.0), tvos(9.0));

// 獲取指定任務(wù)的Cookie啃憎，并處理完成回調(diào)
- (void)getCookiesForTask:(NSURLSessionTask *)task completionHandler:(void (^) (NSArray<NSHTTPCookie *> * _Nullable cookies))completionHandler API_AVAILABLE(macos(10.10), ios(8.0), watchos(2.0), tvos(9.0));

@end

/*!
    @const NSHTTPCookieManagerAcceptPolicyChangedNotification
    @discussion Name of notification that should be posted to the
    distributed notification center whenever the accept cookies
    preference is changed
*/
FOUNDATION_EXPORT NSNotificationName const NSHTTPCookieManagerAcceptPolicyChangedNotification;

/*!
    @const NSHTTPCookieManagerCookiesChangedNotification
    @abstract Notification sent when the set of cookies changes
*/
FOUNDATION_EXPORT NSNotificationName const NSHTTPCookieManagerCookiesChangedNotification;

NS_ASSUME_NONNULL_END

后記

本篇主要講述了NSHTTPCookieStorage這個類的使用芝囤，喜歡的給個贊和關(guān)注哈~~~~