rwsf::Cookie

Does not inherit

• Local Index
• Header File
• Description
• Public Constructors
• Public Destructors
• Public Member Functions
• Public Operators

Members

Cookie() getComment() getDomain() getExpires() getMaxAge()

getName() getPath() getSecure() getValue() getVersion()

operator=() setComment() setDomain() setExpires() setMaxAge()

setPath() setSecure() setValue() setVersion() ~Cookie()

#include rwsf/servlet/http/Cookie.h

rwsf::Cookie represents an HTTP cookie. A cookie is a small piece of data sent from the server to the client. The client stores the cookie and returns it to the server with later requests. Cookies are typically used to store a small amount of state on the client. If the application requires little state, cookies can maintain the complete state of the application. Otherwise, the application will save the application state on the server and send the client a cookie with a unique token. On later requests, the client returns the token. The application uses the token to associate the saved state with the request. This class provides a simple API for working with cookies.

Each cookie consists of a name, a value, and a set of optional attributes. To add a cookie to a response, use the addCookie function of rwsf::HttpServletResponse. To access cookies in a request, use either the getCookie function or the getCookies function of rwsf::HttpServletRequest.

rwsf::Cookie provides support for both Version 0 (Netscape) and Version 1 (RFC 2109) cookies. However, due to portability concerns we recommend that you use Version 0 cookies (the default).

Note that HydraExpress includes classes that encapsulate the details of associating saved state with a client. For some applications, these classes can eliminate the need for working with cookies directly. See rwsf::HttpSession and related classes for details.

The following table lists methods that are either non-standard or not supported in this release.

Cookie();

Creates an unnamed, empty cookie. Use the copy constructor or assignment operator to create a valid cookie instance.

Cookie(const std::string & name);

Creates a new cookie with the given name. Use the setValue() method to set the value of a cookie.

Cookie(const std::string & name,
    const std::string & value);

Creates a new cookie with the provided name and value.

Cookie(const Cookie & second);

Copy constructor. Constructs a new cookie as a deep copy of second.

~Cookie();

Destructor.

std::string
getComment() const;

Returns the comment for this cookie. If this cookie has no comment, returns the empty string.

std::string
getDomain() const;

Returns the domain name for this cookie. The domain name is defined by RFC 2109. If this cookie has no domain set, returns the empty string.

std::string
getExpires() const;

Returns a string containing the date and time that this cookie expires. Returns the empty string if the client should not save this cookie. Note that this method is only applicable to version 0 cookies.

int
getMaxAge() const;

Returns the maximum age of this cookie in seconds. The default is -1, which means that the client will delete the cookie when the client exits. Note that this method is only applicable to version 1 cookies.

std::string
getName() const;

Returns the name that this cookie contains. The name of the cookie is set when the object is constructed, and cannot be changed.

std::string
getPath() const;

Returns the path associated with this cookie. A client will return the cookie with any request to the server that begins with this path. For example if the path is /examples then the browser will send the cookie to URIs under /examples. See RFC 2109 for more information on the format of paths for cookies.

bool
getSecure() const;

Returns true if the browser is using a secure mechanism for sending cookies, false otherwise. The default is FALSE.

std::string
getValue() const;

Returns the value contained within this cookie.

int
getVersion() const;

Returns the version of this cookie. There are two possible versions, version 0 and version 1.

A version 0 cookie corresponds to the original Netscape proposal. A version 1 cookie complies with RFC 2109. Since RFC 2109 is still fairly new, using only version 0 cookies may facilitate portability between browsers.

void
setComment(const std::string & purpose);

Sets the comment contained within the cookie. The comment describes the purpose of the cookie. Version 0 of the cookie specification does not include comments. A client that only understands version 0 cookies will discard comments.

void
setDomain(const std::string & pattern);

Sets the domain to which this cookie belongs. The form of the domain is specified by RFC 2109. By default, a client will return cookies to only the server that originally created the cookie.

void
setExpires(const std::string & expiry);

Sets the date/time expiration string for version 0 cookies. This string takes the format Wdy, DD-Mon-YYYYHH:MM:SSGMT, for example, "Sat, 21-Jun-2003 \c 19:10:00 \c GMT". An empty string indicates that the client should not save the cookie. This method is only applicable to version 0 cookies. For version 1 cookies, the Agent uses the value set with setMaxAge().

void
setMaxAge(int seconds);

Sets the length of time the client should retain the cookie, in seconds. A negative value indicates that the client should delete the cookie when the client exits. A value of 0 indicates that the client should delete the cookie immediately. The default is -1. This method is only applicable to version 1 cookies. For version 0 cookies, the Agent uses the value set with setExpires().

void
setPath(const std::string & uri);

Sets the path for which this cookie is valid. A client will return the cookie with any request to this server that begins with this path. For example if the path is /examples then the browser will send the cookie to URIs under /examples. See RFC 2109 for more information on the format of paths for cookies.

void
setSecure(bool flag);

Sets whether the browser will return the cookies on a secure connection, or on any connection. If set to true the browser will only return the cookie with requests that use a secure connection such as HTTPS. The default is false.

void
setValue(const std::string & newValue);

Sets the value of this cookie. If binary data needs to be stored, use an encoding such as BASE64.

void
setVersion(int v);

Sets the version of this cookie. Possible values are 0 and 1. A version 1 cookie corresponds to RFC 2109. Version 0 cookies follow the original Netscape specification. Newly-constructed cookies default to 0.

Cookie &
operator=(const Cookie & second);

Makes self a deep copy of second.

© Copyright Rogue Wave Software, Inc. All Rights Reserved. All Rights Reserved. Rogue Wave is a registered trademark of Rogue Wave Software, Inc. in the United States and other countries. HydraExpress is a trademark of Rogue Wave Software, Inc. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.