HydraExpress™ C++ API Reference Guide

Product Documentation:
   HydraExpress C++
Documentation Home
List of all members | Public Member Functions
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
 
Cookieoperator= (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.

Copyright © 2019 Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave is registered trademark of Rogue Wave Software, Inc. in the United States and other countries, and HydraExpress is a trademark of Rogue Wave Software. All other trademarks are the property of their respective owners.
Provide feedback to Rogue Wave about its documentation.