rwsf::Cookie Class Reference

Represents a single HTTP cookie. More...

#include <rwsf/servlet/http/Cookie.h>

Public Member Functions
	Cookie ()
	Cookie (const std::string &name)
	Cookie (const std::string &name, const std::string &value)
	Cookie (const Cookie &second)
	~Cookie ()
std::string	getComment () const
std::string	getDomain () const
std::string	getExpires () const
int	getMaxAge () const
std::string	getName () const
std::string	getPath () const
bool	getSecure () const
std::string	getValue () const
int	getVersion () const
Cookie &	operator= (const Cookie &second)
void	setComment (const std::string &purpose)
void	setDomain (const std::string &pattern)
void	setExpires (const std::string &expiry)
void	setMaxAge (int seconds)
void	setPath (const std::string &uri)
void	setSecure (bool flag)
void	setValue (const std::string &newValue)
void	setVersion (int v)

Detailed Description

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 saves the application state on the server and sends 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 rwsf::HttpServletResponse::addCookie(). To access cookies in a request, use either rwsf::HttpServletRequest::getCookie() or rwsf::HttpServletRequest::getCookies().

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 this product 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 behavior of the following functions are inconsistent with or not defined in the Java Servlet Specification v2.3.

constructors and assignment operator	Added members
getExpires()	Added method for getting expiration for version 0 cookies
setExpires()	Added method for setting expiration for version 0 cookies
clone()	Not included in this implementation (functionality replaced by assignment operator and copy constructor)

Constructor & Destructor Documentation

rwsf::Cookie::Cookie

(

)

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

rwsf::Cookie::Cookie

(

const std::string &

name

)

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

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

Creates a new cookie with the provided name and value.

rwsf::Cookie::Cookie

(

const Cookie &

second

)

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

rwsf::Cookie::~Cookie

(

)

Destructor.

Member Function Documentation

std::string rwsf::Cookie::getComment

(

)

const

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

std::string rwsf::Cookie::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 rwsf::Cookie::getExpires

(

)

const

Returns a string containing the date and time that this cookie expires, as set by setExpires(), and using the same format. Returns the empty string if the client should not save this cookie. Note that this method is only applicable to version 0 cookies.

int rwsf::Cookie::getMaxAge

(

)

const

Returns the maximum age of this cookie in seconds. The default value 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 rwsf::Cookie::getName

(

)

const

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

std::string rwsf::Cookie::getPath

(

)

const

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

bool rwsf::Cookie::getSecure

(

)

const

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

std::string rwsf::Cookie::getValue

(

)

const

Returns the value for this cookie.

int rwsf::Cookie::getVersion

(

)

const

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

A version 0 cookie corresponds to the original Netscape proposal. A version 1 cookie complies with RFC 2109.

Cookie& rwsf::Cookie::operator=

(

const Cookie &

second

)

Makes self a deep copy of second.

void rwsf::Cookie::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 discards comments.

void rwsf::Cookie::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 returns cookies to only the server that originally created the cookie.

void rwsf::Cookie::setExpires

(

const std::string &

expiry

)

Sets the date and time expiration string for version 0 cookies. This string takes the format Wdy, DD-Mon-YYYY HH:MM:SS GMT. For example, Sat, 21-Jun-2003 19:10:00 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 rwsf::Cookie::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 value is -1. This method is only applicable to version 1 cookies. For version 0 cookies, the Agent uses the value set with setExpires().

void rwsf::Cookie::setPath

(

const std::string &

uri

)

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

void rwsf::Cookie::setSecure

(

bool

flag

)

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

void rwsf::Cookie::setValue

(

const std::string &

newValue

)

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

void rwsf::Cookie::setVersion

(

int

v

)

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