Library: Net
Package: HTTP
Header: Poco/Net/HTTPCookie.h
Description
This class represents a HTTP Cookie.
A cookie is a small amount of information sent by a Web server to a Web browser, saved by the browser, and later sent back to the server. A cookie's value can uniquely identify a client, so cookies are commonly used for session management.
A cookie has a name, a single value, and optional attributes such as a comment, path and domain qualifiers, a maximum age, and a version number.
This class supports cookies according to RFC 6265. Support for RFC 2109 ("Version 1") has been deprecated.
Note: "Version 0" cookies were formerly referred to as "Netscape" cookies, but were supposed to be replaced with "Version 1" cookies defined in RFC 2109 (and later obsoleted by RFC 2965). However, However, as stated in RFC 6265, "none of these documents describe how the Cookie and Set-Cookie headers are actually used on the Internet".
Member Summary
Member Functions: escape, getComment, getDomain, getHttpOnly, getMaxAge, getName, getPath, getPriority, getSameSite, getSecure, getValue, getVersion, operator =, setComment, setDomain, setHttpOnly, setMaxAge, setName, setPath, setPriority, setSameSite, setSecure, setValue, setVersion, toString, unescape
Enumerations
SameSite
Constructors
HTTPCookie
HTTPCookie();
Creates an empty HTTPCookie.
HTTPCookie
explicit HTTPCookie(
const std::string & name
);
Creates a cookie with the given name. The cookie never expires.
HTTPCookie
explicit HTTPCookie(
const NameValueCollection & nvc
);
Creates a cookie from the given NameValueCollection.
HTTPCookie
HTTPCookie(
const HTTPCookie & cookie
);
Creates the HTTPCookie by copying another one.
HTTPCookie
HTTPCookie(
const std::string & name,
const std::string & value
);
Creates a cookie with the given name and value. The cookie never expires.
Note: If value contains whitespace or non-alphanumeric characters, the value should be escaped by calling escape() before passing it to the constructor.
Destructor
~HTTPCookie
~HTTPCookie();
Destroys the HTTPCookie.
Member Functions
escape 
static std::string escape(
const std::string & str
);
Escapes the given string by replacing all non-alphanumeric characters with escape sequences in the form %xx, where xx is the hexadecimal character code.
The following characters will be replaced with escape sequences:
- percent sign %
- less-than and greater-than < and >
- curly brackets { and }
- square brackets [ and ]
- parenthesis ( and )
- solidus /
- vertical line |
- reverse solidus (backslash /)
- quotation mark "
- apostrophe '
- circumflex accent ^
- grave accent
- comma and semicolon , and ;
- whitespace and control characters
getComment 
const std::string & getComment() const;
Returns the comment for the cookie.
getDomain
const std::string & getDomain() const;
Returns the domain for the cookie.
getHttpOnly
bool getHttpOnly() const;
Returns true iff the cookie's HttpOnly flag is set.
getMaxAge
int getMaxAge() const;
Returns the maximum age in seconds for the cookie.
getName
const std::string & getName() const;
Returns the name of the cookie.
getPath
const std::string & getPath() const;
Returns the path for the cookie.
getPriority
const std::string & getPriority() const;
Returns the priority for the cookie.
getSameSite
SameSite getSameSite() const;
Returns the cookie's SameSite attribute.
getSecure
bool getSecure() const;
Returns the value of the secure flag for the cookie.
getValue
const std::string & getValue() const;
Returns the value of the cookie.
getVersion
int getVersion() const;
Returns the version of the cookie, which is either 0 or 1.
operator =
HTTPCookie & operator = (
const HTTPCookie & cookie
);
Assigns a cookie.
setComment
void setComment(
const std::string & comment
);
Sets the comment for the cookie.
Comments are only supported for version 1 cookies.
setDomain
void setDomain(
const std::string & domain
);
Sets the domain for the cookie.
setHttpOnly
void setHttpOnly(
bool flag = true
);
Sets the HttpOnly flag for the cookie.
setMaxAge
void setMaxAge(
int maxAge
);
Sets the maximum age in seconds for the cookie.
A value of -1 (default) causes the cookie to become a session cookie, which will be deleted when the browser window is closed.
A value of 0 deletes the cookie on the client.
setName
void setName(
const std::string & name
);
Sets the name of the cookie.
setPath
void setPath(
const std::string & path
);
Sets the path for the cookie.
setPriority
void setPriority(
const std::string & priority
);
Sets the priority for the cookie.
This is a non-standard field.
setSameSite
void setSameSite(
SameSite value
);
Sets the cookie's SameSite attribute.
setSecure
void setSecure(
bool secure
);
Sets the value of the secure flag for the cookie.
setValue
void setValue(
const std::string & value
);
Sets the value of the cookie.
According to the cookie specification, the size of the value should not exceed 4 Kbytes.
Note: If value contains whitespace or non-alphanumeric characters, the value should be escaped by calling escape() prior to passing it to setName().
setVersion
void setVersion(
int version
);
Sets the version of the cookie.
Version must be either 0 (denoting a RFC6265 cookie) or 1 (denoting a RFC 2109 cookie).
toString
std::string toString() const;
Returns a string representation of the cookie, suitable for use in a Set-Cookie header.
unescape
static std::string unescape(
const std::string & str
);
Unescapes the given string by replacing all escape sequences in the form %xx with the respective characters.