Qt 4.8
Public Types | Public Functions | Static Public Functions | Properties | Friends | List of all members
QNetworkCookie Class Reference

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

#include <qnetworkcookie.h>

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

Public Functions

QString domain () const
 Returns the domain this cookie is associated with. More...
 
QDateTime expirationDate () const
 Returns the expiration date for this cookie. More...
 
bool isHttpOnly () const
 Returns true if the "HttpOnly" flag is enabled for this cookie. More...
 
bool isSecure () const
 Returns true if the "secure" option was specified in the cookie string, false otherwise. More...
 
bool isSessionCookie () const
 Returns true if this cookie is a session cookie. More...
 
QByteArray name () const
 Returns the name of this cookie. More...
 
bool operator!= (const QNetworkCookie &other) const
 Returns true if this cookie is not equal to other. More...
 
QNetworkCookieoperator= (const QNetworkCookie &other)
 Copies the contents of the QNetworkCookie object other to this object. More...
 
bool operator== (const QNetworkCookie &other) const
 Returns true if this cookie is equal to other. More...
 
QString path () const
 Returns the path associated with this cookie. More...
 
 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. More...
 
 QNetworkCookie (const QNetworkCookie &other)
 Creates a new QNetworkCookie object by copying the contents of other. More...
 
void setDomain (const QString &domain)
 Sets the domain associated with this cookie to be domain. More...
 
void setExpirationDate (const QDateTime &date)
 Sets the expiration date of this cookie to date. More...
 
void setHttpOnly (bool enable)
 Sets this cookie's "HttpOnly" flag to enable. More...
 
void setName (const QByteArray &cookieName)
 Sets the name of this cookie to be cookieName. More...
 
void setPath (const QString &path)
 Sets the path associated with this cookie to be path. More...
 
void setSecure (bool enable)
 Sets the secure flag of this cookie to enable. More...
 
void setValue (const QByteArray &value)
 Sets the value of this cookie to be value. More...
 
QByteArray toRawForm (RawForm form=Full) const
 Returns the raw form of this QNetworkCookie. More...
 
QByteArray value () const
 Returns this cookies value, as specified in the cookie string. More...
 
 ~QNetworkCookie ()
 Destroys this QNetworkCookie object. More...
 

Static Public Functions

static QList< QNetworkCookieparseCookies (const QByteArray &cookieString)
 Parses the cookie string cookieString as received from a server response in the "Set-Cookie:" header. More...
 

Properties

QSharedDataPointer< QNetworkCookiePrivated
 

Friends

class QNetworkCookiePrivate
 

Detailed Description

The QNetworkCookie class holds one network cookie.

Since
4.4

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 Netscape Cookie Specification{initial cookie specification by Netscape}, which is somewhat similar to the RFC 2109 specification, plus the Mitigating Cross-site Scripting With HTTP-only Cookies {"HttpOnly" extension}. The more recent RFC 2965 specification (which uses the Set-Cookie2 header) is not supported.

See also
QNetworkCookieJar, QNetworkRequest, QNetworkReply

Definition at line 62 of file qnetworkcookie.h.

Enumerations

◆ RawForm

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

  • 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.
  • 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 65 of file qnetworkcookie.h.

Constructors and Destructors

◆ QNetworkCookie() [1/2]

QNetworkCookie::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.

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 109 of file qnetworkcookie.cpp.

110  : d(new QNetworkCookiePrivate)
111 {
112  qRegisterMetaType<QNetworkCookie>();
113  qRegisterMetaType<QList<QNetworkCookie> >();
114 
115  d->name = name;
116  d->value = value;
117 }
QSharedDataPointer< QNetworkCookiePrivate > d
QByteArray name() const
Returns the name of this cookie.
QByteArray value() const
Returns this cookies value, as specified in the cookie string.

◆ QNetworkCookie() [2/2]

QNetworkCookie::QNetworkCookie ( const QNetworkCookie other)

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

Definition at line 123 of file qnetworkcookie.cpp.

124  : d(other.d)
125 {
126 }
QSharedDataPointer< QNetworkCookiePrivate > d

◆ ~QNetworkCookie()

QNetworkCookie::~QNetworkCookie ( )

Destroys this QNetworkCookie object.

Definition at line 131 of file qnetworkcookie.cpp.

132 {
133  // QSharedDataPointer auto deletes
134  d = 0;
135 }
QSharedDataPointer< QNetworkCookiePrivate > d

Functions

◆ 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 290 of file qnetworkcookie.cpp.

Referenced by QNetworkCookieJar::setCookiesFromUrl(), and setDomain().

291 {
292  return d->domain;
293 }
QSharedDataPointer< QNetworkCookiePrivate > d

◆ 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 263 of file qnetworkcookie.cpp.

Referenced by QNetworkCookieJar::setCookiesFromUrl().

264 {
265  return d->expirationDate;
266 }
QSharedDataPointer< QNetworkCookiePrivate > d

◆ isHttpOnly()

bool QNetworkCookie::isHttpOnly ( ) const

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

Since
4.5

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 221 of file qnetworkcookie.cpp.

Referenced by toRawForm().

222 {
223  return d->httpOnly;
224 }
QSharedDataPointer< QNetworkCookiePrivate > d

◆ 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 189 of file qnetworkcookie.cpp.

Referenced by toRawForm().

190 {
191  return d->secure;
192 }
QSharedDataPointer< QNetworkCookiePrivate > d

◆ 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 247 of file qnetworkcookie.cpp.

Referenced by QNetworkCookieJar::setCookiesFromUrl(), and toRawForm().

248 {
249  return !d->expirationDate.isValid();
250 }
QSharedDataPointer< QNetworkCookiePrivate > d
bool isValid() const
Returns true if both the date and the time are valid; otherwise returns false.
Definition: qdatetime.cpp:2346

◆ 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 332 of file qnetworkcookie.cpp.

Referenced by QNetworkCookiePrivate::parseSetCookieHeaderLine(), QNetworkCookie(), and QNetworkCookieJar::setCookiesFromUrl().

333 {
334  return d->name;
335 }
QSharedDataPointer< QNetworkCookiePrivate > d

◆ 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 75 of file qnetworkcookie.h.

76  { return !(*this == other); }

◆ operator=()

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

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

Definition at line 141 of file qnetworkcookie.cpp.

142 {
143  d = other.d;
144  return *this;
145 }
QSharedDataPointer< QNetworkCookiePrivate > d

◆ operator==()

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

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!=()

Definition at line 167 of file qnetworkcookie.cpp.

168 {
169  if (d == other.d)
170  return true;
171  return d->name == other.d->name &&
172  d->value == other.d->value &&
173  d->expirationDate.toUTC() == other.d->expirationDate.toUTC() &&
174  d->domain == other.d->domain &&
175  d->path == other.d->path &&
176  d->secure == other.d->secure &&
177  d->comment == other.d->comment;
178 }
QSharedDataPointer< QNetworkCookiePrivate > d
QDateTime toUTC() const
Returns a datetime containing the date and time information in this datetime, but specified using the...
Definition: qdatetime.h:251

◆ parseCookies()

QList< QNetworkCookie > QNetworkCookie::parseCookies ( const QByteArray 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()

Definition at line 944 of file qnetworkcookie.cpp.

Referenced by parseCookieHeader(), and parseHeaderValue().

945 {
946  // cookieString can be a number of set-cookie header strings joined together
947  // by \n, parse each line separately.
948  QList<QNetworkCookie> cookies;
949  QList<QByteArray> list = cookieString.split('\n');
950  for (int a = 0; a < list.size(); a++)
952  return cookies;
953 }
static QList< QNetworkCookie > parseSetCookieHeaderLine(const QByteArray &cookieString)
long ASN1_INTEGER_get ASN1_INTEGER * a
const T & at(int i) const
Returns the item at index position i in the list.
Definition: qlist.h:468
QList< QByteArray > split(char sep) const
Splits the byte array into subarrays wherever sep occurs, and returns the list of those arrays...
int size() const
Returns the number of items in the list.
Definition: qlist.h:137

◆ 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 311 of file qnetworkcookie.cpp.

Referenced by QNetworkCookiePrivate::parseSetCookieHeaderLine(), QNetworkCookieJar::setCookiesFromUrl(), and setPath().

312 {
313  return d->path;
314 }
QSharedDataPointer< QNetworkCookiePrivate > d

◆ setDomain()

void QNetworkCookie::setDomain ( const QString domain)

Sets the domain associated with this cookie to be domain.

See also
domain()

Definition at line 300 of file qnetworkcookie.cpp.

Referenced by QNetworkCookiePrivate::parseSetCookieHeaderLine(), and QNetworkCookieJar::setCookiesFromUrl().

301 {
302  d->domain = domain;
303 }
QString domain() const
Returns the domain this cookie is associated with.
QSharedDataPointer< QNetworkCookiePrivate > d

◆ 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 275 of file qnetworkcookie.cpp.

Referenced by QNetworkCookiePrivate::parseSetCookieHeaderLine().

276 {
277  d->expirationDate = date;
278 }
QSharedDataPointer< QNetworkCookiePrivate > d

◆ setHttpOnly()

void QNetworkCookie::setHttpOnly ( bool  enable)

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

Since
4.5

Definition at line 234 of file qnetworkcookie.cpp.

Referenced by QNetworkCookiePrivate::parseSetCookieHeaderLine().

235 {
236  d->httpOnly = enable;
237 }
QSharedDataPointer< QNetworkCookiePrivate > d

◆ 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 344 of file qnetworkcookie.cpp.

Referenced by QNetworkCookiePrivate::parseSetCookieHeaderLine().

345 {
346  d->name = cookieName;
347 }
QSharedDataPointer< QNetworkCookiePrivate > d

◆ setPath()

void QNetworkCookie::setPath ( const QString path)

Sets the path associated with this cookie to be path.

See also
path()

Definition at line 321 of file qnetworkcookie.cpp.

Referenced by QNetworkCookiePrivate::parseSetCookieHeaderLine(), and QNetworkCookieJar::setCookiesFromUrl().

322 {
323  d->path = path;
324 }
QSharedDataPointer< QNetworkCookiePrivate > d
QString path() const
Returns the path associated with this cookie.

◆ 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 202 of file qnetworkcookie.cpp.

Referenced by QNetworkCookiePrivate::parseSetCookieHeaderLine().

203 {
204  d->secure = enable;
205 }
QSharedDataPointer< QNetworkCookiePrivate > d

◆ setValue()

void QNetworkCookie::setValue ( const QByteArray value)

Sets the value of this cookie to be value.

See also
value(), name()

Definition at line 368 of file qnetworkcookie.cpp.

Referenced by QNetworkCookiePrivate::parseSetCookieHeaderLine().

369 {
370  d->value = value;
371 }
QSharedDataPointer< QNetworkCookiePrivate > d
QByteArray value() const
Returns this cookies value, as specified in the cookie string.

◆ 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 496 of file qnetworkcookie.cpp.

Referenced by headerValue(), and operator<<().

497 {
498  QByteArray result;
499  if (d->name.isEmpty())
500  return result; // not a valid cookie
501 
502  result = d->name;
503  result += '=';
504  if ((d->value.contains(';') ||
505  d->value.contains('"')) &&
506  (!d->value.startsWith('"') &&
507  !d->value.endsWith('"'))) {
508  result += '"';
509 
510  QByteArray value = d->value;
511  value.replace('"', "\\\"");
512  result += value;
513 
514  result += '"';
515  } else {
516  result += d->value;
517  }
518 
519  if (form == Full) {
520  // same as above, but encoding everything back
521  if (isSecure())
522  result += "; secure";
523  if (isHttpOnly())
524  result += "; HttpOnly";
525  if (!isSessionCookie()) {
526  result += "; expires=";
527  result += QLocale::c().toString(d->expirationDate.toUTC(),
528  QLatin1String("ddd, dd-MMM-yyyy hh:mm:ss 'GMT")).toLatin1();
529  }
530  if (!d->domain.isEmpty()) {
531  result += "; domain=";
532  QString domainNoDot = d->domain;
533  if (domainNoDot.startsWith(QLatin1Char('.'))) {
534  result += '.';
535  domainNoDot = domainNoDot.mid(1);
536  }
537  result += QUrl::toAce(domainNoDot);
538  }
539  if (!d->path.isEmpty()) {
540  result += "; path=";
541  result += QUrl::toPercentEncoding(d->path, "/");
542  }
543  }
544  return result;
545 }
static QByteArray toPercentEncoding(const QString &, const QByteArray &exclude=QByteArray(), const QByteArray &include=QByteArray())
Returns an encoded copy of input.
Definition: qurl.cpp:6009
bool isSessionCookie() const
Returns true if this cookie is a session cookie.
QSharedDataPointer< QNetworkCookiePrivate > d
The QByteArray class provides an array of bytes.
Definition: qbytearray.h:135
bool startsWith(const QString &s, Qt::CaseSensitivity cs=Qt::CaseSensitive) const
Returns true if the string starts with s; otherwise returns false.
Definition: qstring.cpp:3734
QLatin1String(DBUS_INTERFACE_DBUS))) Q_GLOBAL_STATIC_WITH_ARGS(QString
The QString class provides a Unicode character string.
Definition: qstring.h:83
bool startsWith(const QByteArray &a) const
Returns true if this byte array starts with byte array ba; otherwise returns false.
QString toString(qlonglong i) const
Returns a localized string representation of i.
Definition: qlocale.cpp:1295
static QByteArray toAce(const QString &)
Returns the ASCII Compatible Encoding of the given domain name domain.
Definition: qurl.cpp:6158
bool isEmpty() const
Returns true if the string has no characters; otherwise returns false.
Definition: qstring.h:704
QDateTime toUTC() const
Returns a datetime containing the date and time information in this datetime, but specified using the...
Definition: qdatetime.h:251
QString mid(int position, int n=-1) const Q_REQUIRED_RESULT
Returns a string that contains n characters of this string, starting at the specified position index...
Definition: qstring.cpp:3706
static QLocale c()
Returns a QLocale object initialized to the "C" locale.
Definition: qlocale.h:773
bool isHttpOnly() const
Returns true if the "HttpOnly" flag is enabled for this cookie.
bool isSecure() const
Returns true if the "secure" option was specified in the cookie string, false otherwise.
QByteArray & replace(int index, int len, const char *s)
This is an overloaded member function, provided for convenience. It differs from the above function o...
bool isEmpty() const
Returns true if the byte array has size 0; otherwise returns false.
Definition: qbytearray.h:421
QByteArray value() const
Returns this cookies value, as specified in the cookie string.
The QLatin1Char class provides an 8-bit ASCII/Latin-1 character.
Definition: qchar.h:55
bool endsWith(const QByteArray &a) const
Returns true if this byte array ends with byte array ba; otherwise returns false. ...
QBool contains(char c) const
Returns true if the byte array contains the character ch; otherwise returns false.
Definition: qbytearray.h:525

◆ 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 358 of file qnetworkcookie.cpp.

Referenced by QNetworkCookie(), setValue(), and toRawForm().

359 {
360  return d->value;
361 }
QSharedDataPointer< QNetworkCookiePrivate > d

Friends and Related Functions

◆ QNetworkCookiePrivate

Definition at line 105 of file qnetworkcookie.h.

Properties

◆ d

QSharedDataPointer<QNetworkCookiePrivate> QNetworkCookie::d
private

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