NSHTTPCookieStorage Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in OS X v10.2 with Safari 1.0 installed.
Available in OS X v10.2.7 and later.
Companion guide
Declared in
NSHTTPCookieStorage.h

Overview

NSHTTPCookieStorage implements a singleton object (shared instance) that manages storage of cookies. Each cookie is represented by an instance of the NSHTTPCookie class. As a rule, cookies are shared among all applications and are kept in sync across process boundaries. Session cookies (where the cookie object’s isSessionOnly method returns YES) are local to a single process and are not shared.

Tasks

Creating and Initializing a Cookie Storage Object

Getting the Shared Cookie Storage Object

Getting and Setting the Cookie Accept Policy

Adding and Removing Cookies

Retrieving Cookies

Class Methods

sharedHTTPCookieStorage

Returns the shared cookie storage instance.

+ (NSHTTPCookieStorage *)sharedHTTPCookieStorage
Return Value

The shared cookie storage instance.

Availability
  • Available in OS X v10.2 with Safari 1.0 installed.
  • Available in OS X v10.2.7 and later.
Declared In
NSHTTPCookieStorage.h

Instance Methods

cookieAcceptPolicy

Returns the cookie storage’s cookie accept policy.

- (NSHTTPCookieAcceptPolicy)cookieAcceptPolicy
Return Value

The cookie storage’s cookie accept policy. The default cookie accept policy is NSHTTPCookieAcceptPolicyAlways.

Availability
  • Available in OS X v10.2 with Safari 1.0 installed.
  • Available in OS X v10.2.7 and later.
Declared In
NSHTTPCookieStorage.h

cookies

Returns the cookie storage’s cookies.

- (NSArray *)cookies
Return Value

An array containing all of the cookie storage’s cookies.

Availability
  • Available in OS X v10.2 with Safari 1.0 installed.
  • Available in OS X v10.2.7 and later.
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.

Declared In
NSHTTPCookieStorage.h

cookiesForURL:

Returns all the cookie storage’s cookies that are sent to a specified URL.

- (NSArray *)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 OS X v10.2 with Safari 1.0 installed.
  • Available in OS X v10.2.7 and later.
See Also
Declared In
NSHTTPCookieStorage.h

deleteCookie:

Deletes the specified cookie from the cookie storage.

- (void)deleteCookie:(NSHTTPCookie *)aCookie
Parameters
aCookie

The cookie to delete.

Availability
  • Available in OS X v10.2 with Safari 1.0 installed.
  • Available in OS X v10.2.7 and later.
Declared In
NSHTTPCookieStorage.h

setCookie:

Stores a specified cookie in the cookie storage if the cookie accept policy permits.

- (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 is NSHTTPCookieAcceptPolicyAlways or NSHTTPCookieAcceptPolicyOnlyFromMainDocumentDomain. The cookie is ignored if the receiver’s cookie accept policy is NSHTTPCookieAcceptPolicyNever.

Availability
  • Available in OS X v10.2 with Safari 1.0 installed.
  • Available in OS X v10.2.7 and later.
Declared In
NSHTTPCookieStorage.h

setCookieAcceptPolicy:

Sets the cookie accept policy of the cookie storage.

- (void)setCookieAcceptPolicy:(NSHTTPCookieAcceptPolicy)aPolicy
Parameters
aPolicy

The new cookie accept policy.

Discussion

The default cookie accept policy is NSHTTPCookieAcceptPolicyAlways. Changing the cookie policy affects all currently running applications using the cookie storage.

Availability
  • Available in OS X v10.2 with Safari 1.0 installed.
  • Available in OS X v10.2.7 and later.
Declared In
NSHTTPCookieStorage.h

setCookies:forURL:mainDocumentURL:

Adds an array of cookies to the receiver if the receiver’s cookie acceptance policy permits.

- (void)setCookies:(NSArray *)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 OS X v10.2 with Safari 1.0 installed.
  • Available in OS X v10.2.7 and later.
Declared In
NSHTTPCookieStorage.h

sortedCookiesUsingDescriptors:

Returns all of the cookie storage’s cookies, sorted according to a given set of sort descriptors.

- (NSArray *)sortedCookiesUsingDescriptors:(NSArray *)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 OS X v10.7 and later.
Declared In
NSHTTPCookieStorage.h

Constants

NSHTTPCookieAcceptPolicy

NSHTTPCookieAcceptPolicy specifies the cookie acceptance policies implemented by the NSHTTPCookieStorage class.

typedef enum {
   NSHTTPCookieAcceptPolicyAlways,
   NSHTTPCookieAcceptPolicyNever,
   NSHTTPCookieAcceptPolicyOnlyFromMainDocumentDomain
} NSHTTPCookieAcceptPolicy;
Constants
NSHTTPCookieAcceptPolicyAlways

Accept all cookies. This is the default cookie accept policy.

Available in OS X v10.2 and later.

Declared in NSHTTPCookieStorage.h.

NSHTTPCookieAcceptPolicyNever

Reject all cookies.

Available in OS X v10.2 and later.

Declared in NSHTTPCookieStorage.h.

NSHTTPCookieAcceptPolicyOnlyFromMainDocumentDomain

Accept cookies only from the main document domain.

Available in OS X v10.2 and later.

Declared in NSHTTPCookieStorage.h.

Availability
  • Available in OS X v10.2 with Safari 1.0 installed.
  • Available in OS X v10.2.7 and later.
Declared In
NSHTTPCookieStorage.h

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.

Availability
Declared In
NSHTTPCookieStorage.h

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.

Availability
Declared In
NSHTTPCookieStorage.h