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 both the Version 0 (by Netscape) and Version 1 (by RFC 2109) cookie specifications. By default, cookies are created using Version 0 to ensure the best interoperability.

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

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 inline

const std::string & getComment() const;

Returns the comment for the cookie.

getDomain inline

const std::string & getDomain() const;

Returns the domain for the cookie.

getHttpOnly inline

bool getHttpOnly() const;

Returns true iff the cookie's HttpOnly flag is set.

getMaxAge inline

int getMaxAge() const;

Returns the maximum age in seconds for the cookie.

getName inline

const std::string & getName() const;

Returns the name of the cookie.

getPath inline

const std::string & getPath() const;

Returns the path for the cookie.

getPriority inline

const std::string & getPriority() const;

Returns the priority for the cookie.

getSameSite inline

SameSite getSameSite() const;

Returns the cookie's SameSite attribute.

getSecure inline

bool getSecure() const;

Returns the value of the secure flag for the cookie.

getValue inline

const std::string & getValue() const;

Returns the value of the cookie.

getVersion inline

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.

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 Netscape 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

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.

POCO C++ Libraries 1.14.0-all
Copyright © 2024, Applied Informatics Software Engineering GmbH and Contributors