The QNetworkCookie class holds one network cookie. More...

#include <qnetworkcookie.h>

Collaboration diagram for QNetworkCookie:

Public Types
enum	RawForm { NameAndValueOnly , Full }
	This enum is used with the toRawForm() function to declare which form of a cookie shall be returned. More...

enum class	SameSite { Default , None , Lax , Strict }

Public Member Functions
	QNetworkCookie (const QByteArray &name=QByteArray(), const QByteArray &value=QByteArray())
	Create a new QNetworkCookie object, initializing the cookie name to name and its value to value.

	QNetworkCookie (const QNetworkCookie &other)
	Creates a new QNetworkCookie object by copying the contents of other.

	~QNetworkCookie ()
	Destroys this QNetworkCookie object.

QNetworkCookie &	operator= (QNetworkCookie &&other) noexcept

QNetworkCookie &	operator= (const QNetworkCookie &other)
	Copies the contents of the QNetworkCookie object other to this object.

void	swap (QNetworkCookie &other) noexcept

bool	operator== (const QNetworkCookie &other) const

bool	operator!= (const QNetworkCookie &other) const
	Returns `true` if this cookie is not equal to other.

bool	isSecure () const
	Returns `true` if the "secure" option was specified in the cookie string, false otherwise.

void	setSecure (bool enable)
	Sets the secure flag of this cookie to enable.

bool	isHttpOnly () const

void	setHttpOnly (bool enable)

SameSite	sameSitePolicy () const
	Returns the "SameSite" option if specified in the cookie string, `SameSite::Default` if not present.

void	setSameSitePolicy (SameSite sameSite)
	Sets the "SameSite" option of this cookie to sameSite.

bool	isSessionCookie () const
	Returns `true` if this cookie is a session cookie.

QDateTime	expirationDate () const
	Returns the expiration date for this cookie.

void	setExpirationDate (const QDateTime &date)
	Sets the expiration date of this cookie to date.

QString	domain () const
	Returns the domain this cookie is associated with.

void	setDomain (const QString &domain)
	Sets the domain associated with this cookie to be domain.

QString	path () const
	Returns the path associated with this cookie.

void	setPath (const QString &path)
	Sets the path associated with this cookie to be path.

QByteArray	name () const
	Returns the name of this cookie.

void	setName (const QByteArray &cookieName)
	Sets the name of this cookie to be cookieName.

QByteArray	value () const
	Returns this cookies value, as specified in the cookie string.

void	setValue (const QByteArray &value)
	Sets the value of this cookie to be value.

QByteArray	toRawForm (RawForm form=Full) const
	Returns the raw form of this QNetworkCookie.

bool	hasSameIdentifier (const QNetworkCookie &other) const
	Returns `true` if this cookie has the same identifier tuple as other.

void	normalize (const QUrl &url)

Static Public Member Functions
static QList< QNetworkCookie >	parseCookies (QByteArrayView cookieString)
	Parses the cookie string cookieString as received from a server response in the "Set-Cookie:" header.

Friends
class	QNetworkCookiePrivate

Detailed Description

The QNetworkCookie class holds one network cookie.

Since: 4.4

\inmodule QtNetwork

Cookies are small bits of information that stateless protocols like HTTP use to maintain some persistent information across requests.

A cookie is set by a remote server when it replies to a request and it expects the same cookie to be sent back when further requests are sent.

QNetworkCookie holds one such cookie as received from the network. A cookie has a name and a value, but those are opaque to the application (that is, the information stored in them has no meaning to the application). A cookie has an associated path name and domain, which indicate when the cookie should be sent again to the server.

A cookie can also have an expiration date, indicating its validity. If the expiration date is not present, the cookie is considered a "session cookie" and should be discarded when the application exits (or when its concept of session is over).

QNetworkCookie provides a way of parsing a cookie from the HTTP header format using the QNetworkCookie::parseCookies() function. However, when received in a QNetworkReply, the cookie is already parsed.

This class implements cookies as described by the \l{Netscape Cookie Specification}{initial cookie specification by Netscape}, which is somewhat similar to the \l{http://www.rfc-editor.org/rfc/rfc2109.txt}{RFC 2109} specification, plus the \l{Mitigating Cross-site Scripting With HTTP-only Cookies} {"HttpOnly" extension}. The more recent \l{http://www.rfc-editor.org/rfc/rfc2965.txt}{RFC 2965} specification (which uses the Set-Cookie2 header) is not supported.

See also: QNetworkCookieJar, QNetworkRequest, QNetworkReply

Definition at line 22 of file qnetworkcookie.h.

Member Enumeration Documentation

◆ RawForm

enum QNetworkCookie::RawForm

This enum is used with the toRawForm() function to declare which form of a cookie shall be returned.

\value NameAndValueOnly makes toRawForm() return only the "NAME=VALUE" part of the cookie, as suitable for sending back to a server in a client request's "Cookie:" header. Multiple cookies are separated by a semi-colon in the "Cookie:" header field.

\value Full makes toRawForm() return the full cookie contents, as suitable for sending to a client in a server's "Set-Cookie:" header.

Note that only the Full form of the cookie can be parsed back into its original contents.

See also: toRawForm(), parseCookies()

Enumerator
NameAndValueOnly
Full

Definition at line 26 of file qnetworkcookie.h.

◆ SameSite

enum class QNetworkCookie::SameSite

strong

Since: 6.1

\value Default SameSite is not set. Can be interpreted as None or Lax by the browser. \value None Cookies can be sent in all contexts. This used to be default, but recent browsers made Lax default, and will now require the cookie to be both secure and to set SameSite=None. \value Lax Cookies are sent on first party requests and GET requests initiated by third party website. This is the default in modern browsers (since mid 2020). \value Strict Cookies will only be sent in a first-party context.

See also: setSameSitePolicy(), sameSitePolicy()

Enumerator
Default
None
Lax
Strict

Definition at line 30 of file qnetworkcookie.h.

Constructor & Destructor Documentation

◆ QNetworkCookie() [1/2]

QNetworkCookie::QNetworkCookie	(	const QByteArray &	name = QByteArray(),
		const QByteArray &	value = QByteArray() )

explicit

Create a new QNetworkCookie object, initializing the cookie name to name and its value to value.

A cookie is only valid if it has a name. However, the value is opaque to the application and being empty may have significance to the remote server.

Definition at line 82 of file qnetworkcookie.cpp.

◆ QNetworkCookie() [2/2]

QNetworkCookie::QNetworkCookie ( const QNetworkCookie & other )

Creates a new QNetworkCookie object by copying the contents of other.

Definition at line 96 of file qnetworkcookie.cpp.

◆ ~QNetworkCookie()

QNetworkCookie::~QNetworkCookie ( )

Destroys this QNetworkCookie object.

Definition at line 104 of file qnetworkcookie.cpp.

Member Function Documentation

◆ domain()

QString QNetworkCookie::domain ( ) const

Returns the domain this cookie is associated with.

This corresponds to the "domain" field of the cookie string.

Note that the domain here may start with a dot, which is not a valid hostname. However, it means this cookie matches all hostnames ending with that domain name.

See also: setDomain()

Definition at line 296 of file qnetworkcookie.cpp.

◆ expirationDate()

QDateTime QNetworkCookie::expirationDate ( ) const

Returns the expiration date for this cookie.

If this cookie is a session cookie, the QDateTime returned will not be valid. If the date is in the past, this cookie has already expired and should not be sent again back to a remote server.

The expiration date corresponds to the parameters of the "expires" entry in the cookie string.

See also: isSessionCookie(), setExpirationDate()

Definition at line 269 of file qnetworkcookie.cpp.

◆ hasSameIdentifier()

bool QNetworkCookie::hasSameIdentifier ( const QNetworkCookie & other ) const

Returns true if this cookie has the same identifier tuple as other.

The identifier tuple is composed of the name, domain and path.

See also: operator==()

Definition at line 164 of file qnetworkcookie.cpp.

◆ isHttpOnly()

bool QNetworkCookie::isHttpOnly ( ) const

Since: 4.5

Returns true if the "HttpOnly" flag is enabled for this cookie.

A cookie that is "HttpOnly" is only set and retrieved by the network requests and replies; i.e., the HTTP protocol. It is not accessible from scripts running on browsers.

See also: isSecure()

Definition at line 230 of file qnetworkcookie.cpp.

◆ isSecure()

bool QNetworkCookie::isSecure ( ) const

Returns true if the "secure" option was specified in the cookie string, false otherwise.

Secure cookies may contain private information and should not be resent over unencrypted connections.

See also: setSecure()

Definition at line 178 of file qnetworkcookie.cpp.

◆ isSessionCookie()

bool QNetworkCookie::isSessionCookie ( ) const

Returns true if this cookie is a session cookie.

A session cookie is a cookie which has no expiration date, which means it should be discarded when the application's concept of session is over (usually, when the application exits).

See also: expirationDate(), setExpirationDate()

Definition at line 253 of file qnetworkcookie.cpp.

◆ name()

QByteArray QNetworkCookie::name ( ) const

Returns the name of this cookie.

The only mandatory field of a cookie is its name, without which it is not considered valid.

See also: setName(), value()

Definition at line 338 of file qnetworkcookie.cpp.

◆ normalize()

void QNetworkCookie::normalize ( const QUrl & url )

Since: 5.0 This functions normalizes the path and domain of the cookie if they were previously empty. The url parameter is used to determine the correct domain and path.

Definition at line 1064 of file qnetworkcookie.cpp.

◆ operator!=()

bool QNetworkCookie::operator!= ( const QNetworkCookie & other ) const

inline

Returns true if this cookie is not equal to other.

See also: operator==()

Definition at line 47 of file qnetworkcookie.h.

◆ operator=() [1/2]

QNetworkCookie & QNetworkCookie::operator= ( const QNetworkCookie & other )

Copies the contents of the QNetworkCookie object other to this object.

Definition at line 114 of file qnetworkcookie.cpp.

◆ operator=() [2/2]

QNetworkCookie & QNetworkCookie::operator= ( QNetworkCookie && other )

inlinenoexcept

Definition at line 41 of file qnetworkcookie.h.

◆ operator==()

bool QNetworkCookie::operator== ( const QNetworkCookie & other ) const

Since: 5.0 Returns true if this cookie is equal to other. This function only returns true if all fields of the cookie are the same.

However, in some contexts, two cookies of the same name could be considered equal.

See also: operator!=(), hasSameIdentifier()

Definition at line 144 of file qnetworkcookie.cpp.

◆ parseCookies()

QList< QNetworkCookie > QNetworkCookie::parseCookies ( QByteArrayView cookieString )

static

Parses the cookie string cookieString as received from a server response in the "Set-Cookie:" header.

If there's a parsing error, this function returns an empty list.

Since the HTTP header can set more than one cookie at the same time, this function returns a QList<QNetworkCookie>, one for each cookie that is parsed.

See also: toRawForm()

Note: In Qt versions prior to 6.7, this function took QByteArray only.

Definition at line 938 of file qnetworkcookie.cpp.

◆ path()

QString QNetworkCookie::path ( ) const

Returns the path associated with this cookie.

This corresponds to the "path" field of the cookie string.

See also: setPath()

Definition at line 317 of file qnetworkcookie.cpp.

◆ sameSitePolicy()

QNetworkCookie::SameSite QNetworkCookie::sameSitePolicy ( ) const

Returns the "SameSite" option if specified in the cookie string, SameSite::Default if not present.

Since: 6.1

See also: setSameSitePolicy()

Definition at line 203 of file qnetworkcookie.cpp.

◆ setDomain()

void QNetworkCookie::setDomain ( const QString & domain )

Sets the domain associated with this cookie to be domain.

See also: domain()

Definition at line 306 of file qnetworkcookie.cpp.

◆ setExpirationDate()

void QNetworkCookie::setExpirationDate ( const QDateTime & date )

Sets the expiration date of this cookie to date.

Setting an invalid expiration date to this cookie will mean it's a session cookie.

See also: isSessionCookie(), expirationDate()

Definition at line 281 of file qnetworkcookie.cpp.

◆ setHttpOnly()

void QNetworkCookie::setHttpOnly ( bool enable )

Since: 4.5

Sets this cookie's "HttpOnly" flag to enable.

Definition at line 240 of file qnetworkcookie.cpp.

◆ setName()

void QNetworkCookie::setName ( const QByteArray & cookieName )

Sets the name of this cookie to be cookieName.

Note that setting a cookie name to an empty QByteArray will make this cookie invalid.

See also: name(), value()

Definition at line 350 of file qnetworkcookie.cpp.

◆ setPath()

void QNetworkCookie::setPath ( const QString & path )

Sets the path associated with this cookie to be path.

See also: path()

Definition at line 327 of file qnetworkcookie.cpp.

◆ setSameSitePolicy()

void QNetworkCookie::setSameSitePolicy ( QNetworkCookie::SameSite sameSite )

Sets the "SameSite" option of this cookie to sameSite.

Since: 6.1

See also: sameSitePolicy()

Definition at line 214 of file qnetworkcookie.cpp.

◆ setSecure()

void QNetworkCookie::setSecure ( bool enable )

Sets the secure flag of this cookie to enable.

Secure cookies may contain private information and should not be resent over unencrypted connections.

See also: isSecure()

Definition at line 191 of file qnetworkcookie.cpp.

◆ setValue()

void QNetworkCookie::setValue ( const QByteArray & value )

Sets the value of this cookie to be value.

See also: value(), name()

Definition at line 374 of file qnetworkcookie.cpp.

◆ swap()

void QNetworkCookie::swap ( QNetworkCookie & other )

inlinenoexcept

Since: 5.0 \memberswap{cookie}

Definition at line 44 of file qnetworkcookie.h.

◆ toRawForm()

QByteArray QNetworkCookie::toRawForm ( RawForm form = Full ) const

Returns the raw form of this QNetworkCookie.

The QByteArray returned by this function is suitable for an HTTP header, either in a server response (the Set-Cookie header) or the client request (the Cookie header). You can choose from one of two formats, using form.

See also: parseCookies()

Definition at line 488 of file qnetworkcookie.cpp.

◆ value()

QByteArray QNetworkCookie::value ( ) const

Returns this cookies value, as specified in the cookie string.

Note that a cookie is still valid if its value is empty.

Cookie name-value pairs are considered opaque to the application: that is, their values don't mean anything.

See also: setValue(), name()

Definition at line 364 of file qnetworkcookie.cpp.

Friends And Related Symbol Documentation

◆ QNetworkCookiePrivate

friend class QNetworkCookiePrivate

friend

Definition at line 85 of file qnetworkcookie.h.

The documentation for this class was generated from the following files:

qtbase/src/network/access/qnetworkcookie.h (3c80e8892459f47a6261df317eb6eb4d9c790837)
qtbase/src/network/access/qnetworkcookie.cpp (94df2e81324b4a1e8703fa5011b299a0635450b2)

Public Types

Public Member Functions

Static Public Member Functions

Friends