---

NSHTTPCookieStorage Class Reference

Overview

NSHTTPCookieStorage implements a singleton object (shared instance) that manages the shared cookie storage. These cookies are shared among all applications and are kept in sync cross-process.

Tasks

Getting the Shared Cookie Storage Object

• + sharedHTTPCookieStorage

Getting and Setting the Cookie Accept Policy

• – cookieAcceptPolicy
• – setCookieAcceptPolicy:

Adding and Removing Cookies

• – cookies
• – cookiesForURL:
• – deleteCookie:
• – setCookie:
• – setCookies:forURL:mainDocumentURL:

Class Methods

sharedHTTPCookieStorage

Returns the shared cookie storage instance.

+ (NSHTTPCookieStorage *)sharedHTTPCookieStorage

Return Value

The shared cookie storage instance.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 installed.
• Available in Mac OS X v10.2.7 and later.

Declared In

NSHTTPCookieStorage.h

Instance Methods

cookieAcceptPolicy

Returns the receiver’s cookie accept policy.

- (NSHTTPCookieAcceptPolicy)cookieAcceptPolicy

Return Value

The receiver's cookie accept policy. The default cookie accept policy is NSHTTPCookieAcceptPolicyAlways.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 installed.
• Available in Mac OS X v10.2.7 and later.

See Also

• – setCookieAcceptPolicy:

Declared In

NSHTTPCookieStorage.h

cookies

Returns the receiver’s cookies.

- (NSArray *)cookies

Return Value

An array containing all of the receiver’s cookies.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 installed.
• Available in Mac OS X v10.2.7 and later.

See Also

• – cookiesForURL:

Declared In

NSHTTPCookieStorage.h

cookiesForURL:

Returns all the receiver's cookies that will be 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’s requestHeaderFieldsWithCookies: method to turn this array into a set of header fields to add to an NSMutableURLRequest object.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 installed.
• Available in Mac OS X v10.2.7 and later.

See Also

• – cookies

Declared In

NSHTTPCookieStorage.h

deleteCookie:

Deletes the specified cookie from the receiver.

- (void)deleteCookie:(NSHTTPCookie *)aCookie

Parameters

aCookie

The cookie to delete.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 installed.
• Available in Mac OS X v10.2.7 and later.

Declared In

NSHTTPCookieStorage.h

setCookie:

Stores a specified cookie in the receiver if the receiver's cookie accept policy permits.

- (void)setCookie:(NSHTTPCookie *)aCookie

Parameters

aCookie

The cookie to store.

Discussion

The cookie will replace an existing cookie with the same name, domain and path, if one exists in the cookie storage. This method will accept the cookie only if the receiver’s cookie accept policy is NSHTTPCookieAcceptPolicyAlways or NSHTTPCookieAcceptPolicyOnlyFromMainDocumentDomain. The cookie will be ignored if the receiver’s cookie accept policy is NSHTTPCookieAcceptPolicyNever.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 installed.
• Available in Mac OS X v10.2.7 and later.

Declared In

NSHTTPCookieStorage.h

setCookieAcceptPolicy:

Sets the cookie accept policy of the receiver

- (void)setCookieAcceptPolicy:(NSHTTPCookieAcceptPolicy)aPolicy

Parameters

aPolicy

The new cookie accept policy.

Discussion

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

Availability

• Available in Mac OS X v10.2 with Safari 1.0 installed.
• Available in Mac OS X v10.2.7 and later.

See Also

• – cookieAcceptPolicy

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

Declared in NSHTTPCookieStorage.h.

NSHTTPCookieAcceptPolicyNever

Reject all cookies.

Available in Mac OS X v10.2 and later.

Declared in NSHTTPCookieStorage.h.

NSHTTPCookieAcceptPolicyOnlyFromMainDocumentDomain

Accept cookies only from the main document domain.

Available in Mac OS X v10.2 and later.

Declared in NSHTTPCookieStorage.h.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 installed.
• Available in Mac 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. Since cookies are shared among applications, this notification can be sent in response to another application’s actions.

The notification object is the NSHTTPCookieStorage instance. This notification does not contain a userInfo dictionary.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 installed.
• Available in Mac OS X v10.2.7 and later.

Declared In

NSHTTPCookieStorage.h

NSHTTPCookieManagerAcceptPolicyChangedNotification

This notification is posted when the acceptance policy of the NSHTTPCookieStorage instance has changed. Since cookies are shared among applications, this notification can be sent in response to another application’s actions.

The notification object is the NSHTTPCookieStorage instance. This notification does not contain a userInfo dictionary.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 installed.
• Available in Mac OS X v10.2.7 and later.

Declared In

NSHTTPCookieStorage.h

---