NSHTTPCookie Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in iOS 2.0 and later.
Companion guide
Declared in
NSHTTPCookie.h

Overview

An NSHTTPCookie object represents an HTTP cookie. It is an immutable object, initialized from a dictionary containing the cookie attributes.

The NSHTTPCookie class supports two different cookie versions:

Adopted Protocols

NSCopying

Tasks

Create Cookie Instances

Convert Cookies to Request Headers

Getting Cookie Properties

Class Methods

cookiesWithResponseHeaderFields:forURL:

Returns an array of NSHTTPCookie objects corresponding to the provided response header fields for the provided URL.

+ (NSArray *)cookiesWithResponseHeaderFields:(NSDictionary *)headerFields forURL:(NSURL *)theURL
Parameters
headerFields

The header fields used to create the NSHTTPCookie objects.

theURL

The URL associated with the created cookies.

Return Value

The array of created cookies.

Discussion

This method ignores irrelevant header fields in headerFields, allowing dictionaries to contain additional data.

If headerFields does not specify a domain for a given cookie, the cookie is created with a default domain value of theURL.

If headerFields does not specify a path for a given cookie, the cookie is created with a default path value of "/".

Availability
  • Available in iOS 2.0 and later.
Declared In
NSHTTPCookie.h

cookieWithProperties:

Creates and initializes an NSHTTPCookie object using the provided properties.

+ (id)cookieWithProperties:(NSDictionary *)properties
Parameters
properties

The properties for the new cookie object, expressed as key value pairs.

Return Value

The newly created cookie object. Returns nil if the provided properties are invalid.

Discussion

To successfully create a cookie, you must provide values for (at least) the NSHTTPCookiePath, NSHTTPCookieName, and NSHTTPCookieValue keys, and either the NSHTTPCookieOriginURL key or the NSHTTPCookieDomain key.

See “Constants” for more information on the available cookie attribute constants and the constraints imposed on the values in the dictionary.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSHTTPCookie.h

requestHeaderFieldsWithCookies:

Returns a dictionary of header fields corresponding to a provided array of cookies.

+ (NSDictionary *)requestHeaderFieldsWithCookies:(NSArray *)cookies
Parameters
cookies

The cookies from which the header fields are created.

Return Value

The dictionary of header fields created from the provided cookies.

Discussion

To send these headers as part of a URL request to a remote server, create an NSMutableURLRequest object, then call the setAllHTTPHeaderFields: or setValue:forHTTPHeaderField: method to set the provided headers for the request. Finally, initialize and start an NSURLSessionTask, NSURLConnection, or NSURLDownload object based on that request object.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSHTTPCookie.h

Instance Methods

comment

Returns the receiver's comment string.

- (NSString *)comment
Return Value

The receiver’s comment string or nil if the cookie has no comment. This string is suitable for presentation to the user, explaining the contents and purpose of this cookie.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSHTTPCookie.h

commentURL

Returns the receiver’s comment URL.

- (NSURL *)commentURL
Return Value

The receiver’s comment URL or nil if the cookie has none. This value specifies a URL which is suitable for presentation to the user as a link for further information about this cookie.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSHTTPCookie.h

domain

Returns the domain of the receiver’s cookie.

- (NSString *)domain
Return Value

The domain of the receiver’s cookie.

Discussion

If the domain does not start with a dot, then the cookie is only sent to the exact host specified by the domain. If the domain does start with a dot, then the cookie is sent to other hosts in that domain as well, subject to certain restrictions. See RFC 2965 for more detail.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSHTTPCookie.h

expiresDate

Returns the receiver’s expiration date.

- (NSDate *)expiresDate
Return Value

The receiver’s expiration date, or nil if there is no specific expiration date such as in the case of “session-only” cookies. The expiration date is the date when the cookie should be deleted.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSHTTPCookie.h

initWithProperties:

Returns an initialized NSHTTPCookie object using the provided properties.

- (id)initWithProperties:(NSDictionary *)properties
Parameters
properties

The properties for the new cookie object, expressed as key value pairs.

Return Value

The initialized cookie object. Returns nil if the provided properties are invalid.

Discussion

To successfully create a cookie, you must provide values for (at least) the NSHTTPCookiePath, NSHTTPCookieName, and NSHTTPCookieValue keys, and either the NSHTTPCookieOriginURL key or the NSHTTPCookieDomain key.

See “Constants” for more information on the available cookie attribute constants and the constraints imposed on the values in the dictionary.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSHTTPCookie.h

isHTTPOnly

Returns whether the receiver should only be sent to HTTP servers per RFC 2965.

- (BOOL)isHTTPOnly
Return Value

Returns YES if this cookie should only be sent via HTTP headers, NO otherwise.

Discussion

Cookies may be marked as HTTP only by a server (or by a javascript). Cookies marked as such must only be sent via HTTP Headers in HTTP requests for URL's that match both the path and domain of the respective cookies.

Availability
  • Available in iOS 2.2 and later.
Declared In
NSHTTPCookie.h

isSecure

Returns whether his cookie should only be sent over secure channels.

- (BOOL)isSecure
Return Value

YES if this cookie should only be sent over secure channels, otherwise NO.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSHTTPCookie.h

isSessionOnly

Returns whether the receiver should be discarded at the end of the session (regardless of expiration date).

- (BOOL)isSessionOnly
Return Value

YES if the receiver should be discarded at the end of the session (regardless of expiration date), otherwise NO.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSHTTPCookie.h

name

Returns the receiver’s name.

- (NSString *)name
Return Value

The receiver's name.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSHTTPCookie.h

path

Returns the receiver’s path.

- (NSString *)path
Return Value

The receiver's path.

Discussion

The cookie will be sent with requests for this path in the cookie's domain, and all paths that have this prefix. A path of "/" means the cookie will be sent for all URLs in the domain.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSHTTPCookie.h

portList

Returns the receiver's port list.

- (NSArray *)portList
Return Value

The list of ports for the cookie, returned as an array of NSNumber objects containing integers. If the cookie has no port list this method returns nil and the cookie will be sent to any port. Otherwise, the cookie is only sent to ports specified in the port list.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSHTTPCookie.h

properties

Returns the receiver’s cookie properties.

- (NSDictionary *)properties
Return Value

A dictionary representation of the receiver’s cookie properties.

Discussion

This dictionary can be used with initWithProperties: or cookieWithProperties: to create an equivalent NSHTTPCookie object.

See initWithProperties: for more information on the constraints imposed on the properties dictionary.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSHTTPCookie.h

value

Returns the receiver’s value.

- (NSString *)value
Return Value

The receiver's value.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSHTTPCookie.h

version

Returns the receiver’s version.

- (NSUInteger)version
Return Value

The receiver's version. Version 0 maps to “old-style” Netscape cookies. Version 1 maps to RFC 2965 cookies.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSHTTPCookie.h

Constants

HTTP Cookie Attribute Keys

These constants define the supported keys in a cookie attributes dictionary.

extern NSString *NSHTTPCookieComment;
extern NSString *NSHTTPCookieCommentURL;
extern NSString *NSHTTPCookieDiscard;
extern NSString *NSHTTPCookieDomain;
extern NSString *NSHTTPCookieExpires;
extern NSString *NSHTTPCookieMaximumAge;
extern NSString *NSHTTPCookieName;
extern NSString *NSHTTPCookieOriginURL;
extern NSString *NSHTTPCookiePath;
extern NSString *NSHTTPCookiePort;
extern NSString *NSHTTPCookieSecure;
extern NSString *NSHTTPCookieValue;
extern NSString *NSHTTPCookieVersion;
Constants
NSHTTPCookieComment

An NSString object containing the comment for the cookie.

Only valid for Version 1 cookies and later. This cookie attribute is optional.

Available in iOS 2.0 and later.

Declared in NSHTTPCookie.h.

NSHTTPCookieCommentURL

An NSURL object or NSString object containing the comment URL for the cookie.

Only valid for Version 1 cookies or later. This cookie attribute is optional.

Available in iOS 2.0 and later.

Declared in NSHTTPCookie.h.

NSHTTPCookieDiscard

An NSString object stating whether the cookie should be discarded at the end of the session.

String value must be either "TRUE" or "FALSE". This cookie attribute is optional. The default is "FALSE", unless this cookie is version 1 or greater and a value for NSHTTPCookieMaximumAge is not specified, in which case it is assumed to be "TRUE".

Available in iOS 2.0 and later.

Declared in NSHTTPCookie.h.

NSHTTPCookieDomain

An NSString object containing the domain for the cookie.

If this cookie attribute is missing, the domain is inferred from the value for NSHTTPCookieOriginURL. If you do not specify a value for NSHTTPCookieOriginURL, you must specify a value for NSHTTPCookieDomain.

Available in iOS 2.0 and later.

Declared in NSHTTPCookie.h.

NSHTTPCookieExpires

An NSDate object or NSString object specifying the expiration date for the cookie.

This cookie attribute is only used for Version 0 cookies. This cookie attribute is optional.

Available in iOS 2.0 and later.

Declared in NSHTTPCookie.h.

NSHTTPCookieMaximumAge

An NSString object containing an integer value stating how long in seconds the cookie should be kept, at most.

Only valid for Version 1 cookies and later. Default is "0". This cookie attribute is optional.

Available in iOS 2.0 and later.

Declared in NSHTTPCookie.h.

NSHTTPCookieName

An NSString object containing the name of the cookie. This cookie attribute is required.

Available in iOS 2.0 and later.

Declared in NSHTTPCookie.h.

NSHTTPCookieOriginURL

An NSURL or NSString object containing the URL that set this cookie.

If you do not provide a value for NSHTTPCookieOriginURL, you must provide a value for NSHTTPCookieDomain.

Available in iOS 2.0 and later.

Declared in NSHTTPCookie.h.

NSHTTPCookiePath

An NSString object containing the path for the cookie.

This cookie attribute is required.

Available in iOS 2.0 and later.

Declared in NSHTTPCookie.h.

NSHTTPCookiePort

An NSString object containing comma-separated integer values specifying the ports for the cookie.

Only valid for Version 1 cookies or later. The default value is an empty string (""). This cookie attribute is optional.

Available in iOS 2.0 and later.

Declared in NSHTTPCookie.h.

NSHTTPCookieSecure

An NSString object indicating that the cookie should be transmitted only over secure channels.

Providing any value for this key indicates that the cookie should remain secure.

Available in iOS 2.0 and later.

Declared in NSHTTPCookie.h.

NSHTTPCookieValue

An NSString object containing the value of the cookie.

This cookie attribute is required.

Available in iOS 2.0 and later.

Declared in NSHTTPCookie.h.

NSHTTPCookieVersion

An NSString object that specifies the version of the cookie.

Must be either "0" or "1". The default is "0". This cookie attribute is optional.

Available in iOS 2.0 and later.

Declared in NSHTTPCookie.h.

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