Contents

• Public Types
• Public Functions
• Static Public Members
• Detailed Description

Detailed Description

TheQNetworkCookie class holds one network cookie.

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 theQNetworkCookie::parseCookies() function. However, when received in aQNetworkReply, the cookie is already parsed.

This class implements cookies as described by theinitial cookie specification by Netscape, which is somewhat similar to theRFC 2109 specification, plus the"HttpOnly" extension. The more recentRFC 2965 specification (which uses the Set-Cookie2 header) is not supported.

Member Type Documentation

enum QNetworkCookie::RawForm

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

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

See alsotoRawForm() andparseCookies().

Member Function Documentation

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

Create a newQNetworkCookie object, initializing the cookie name toname and its value tovalue.

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.

QNetworkCookie::QNetworkCookie(constQNetworkCookie & other)

Creates a newQNetworkCookie object by copying the contents ofother.

QNetworkCookie::~QNetworkCookie()

Destroys thisQNetworkCookie object.

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 alsosetDomain().

QDateTime QNetworkCookie::expirationDate() const

Returns the expiration date for this cookie. If this cookie is a session cookie, theQDateTime 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 alsoisSessionCookie() andsetExpirationDate().

bool QNetworkCookie::isHttpOnly() const

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.

This function was introduced in Qt 4.5.

See alsoisSecure().

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 alsosetSecure().

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 alsoexpirationDate() andsetExpirationDate().

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 alsosetName() andvalue().

[static]QList<QNetworkCookie> QNetworkCookie::parseCookies(constQByteArray & cookieString)

Parses the cookie stringcookieString 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 aQList<QNetworkCookie>, one for each cookie that is parsed.

See alsotoRawForm().

QString QNetworkCookie::path() const

Returns the path associated with this cookie. This corresponds to the "path" field of the cookie string.

See alsosetPath().

void QNetworkCookie::setDomain(constQString & domain)

Sets the domain associated with this cookie to bedomain.

See alsodomain().

void QNetworkCookie::setExpirationDate(constQDateTime & date)

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

See alsoisSessionCookie() andexpirationDate().

void QNetworkCookie::setHttpOnly(bool enable)

Sets this cookie's "HttpOnly" flag toenable.

This function was introduced in Qt 4.5.

See alsoisHttpOnly().

void QNetworkCookie::setName(constQByteArray & cookieName)

Sets the name of this cookie to becookieName. Note that setting a cookie name to an emptyQByteArray will make this cookie invalid.

See alsoname() andvalue().

void QNetworkCookie::setPath(constQString & path)

Sets the path associated with this cookie to bepath.

See alsopath().

void QNetworkCookie::setSecure(bool enable)

Sets the secure flag of this cookie toenable.

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

See alsoisSecure().

void QNetworkCookie::setValue(constQByteArray & value)

Sets the value of this cookie to bevalue.

See alsovalue() andname().

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

Returns the raw form of thisQNetworkCookie. TheQByteArray 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, usingform.

See alsoparseCookies().

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 alsosetValue() andname().

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

Returns true if this cookie is not equal toother.

See alsooperator==().

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

Copies the contents of theQNetworkCookie objectother to this object.

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

Returns true if this cookie is equal toother. 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 alsooperator!=().