# Poco::Net

# class HTTPCookie

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

SAME_SITE_NOT_SPECIFIED

SAME_SITE_NONE

SAME_SITE_LAX

SAME_SITE_STRICT

## 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.