com.trolltech.qt.network
Class QNetworkCookie

java.lang.Object
  extended by com.trolltech.qt.internal.QSignalEmitterInternal
      extended by com.trolltech.qt.QSignalEmitter
          extended by com.trolltech.qt.QtJambiObject
              extended by com.trolltech.qt.network.QNetworkCookie
All Implemented Interfaces:
QtJambiInterface, java.lang.Cloneable

public class QNetworkCookie
extends QtJambiObject
implements java.lang.Cloneable

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

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

See also:
QNetworkCookieJar, QNetworkRequest, and QNetworkReply.


Nested Class Summary
static class QNetworkCookie.RawForm
          This enum is used with the toRawForm() function to declare which form of a cookie shall be returned.
 
Nested classes/interfaces inherited from class com.trolltech.qt.QSignalEmitter
QSignalEmitter.AbstractSignal, QSignalEmitter.PrivateSignal0, QSignalEmitter.PrivateSignal1, QSignalEmitter.PrivateSignal2, QSignalEmitter.PrivateSignal3, QSignalEmitter.PrivateSignal4, QSignalEmitter.PrivateSignal5, QSignalEmitter.PrivateSignal6, QSignalEmitter.PrivateSignal7, QSignalEmitter.PrivateSignal8, QSignalEmitter.PrivateSignal9, QSignalEmitter.Signal0, QSignalEmitter.Signal1, QSignalEmitter.Signal2, QSignalEmitter.Signal3, QSignalEmitter.Signal4, QSignalEmitter.Signal5, QSignalEmitter.Signal6, QSignalEmitter.Signal7, QSignalEmitter.Signal8, QSignalEmitter.Signal9
 
Nested classes/interfaces inherited from class com.trolltech.qt.internal.QSignalEmitterInternal
com.trolltech.qt.internal.QSignalEmitterInternal.AbstractSignalInternal
 
Field Summary
 
Fields inherited from class com.trolltech.qt.internal.QSignalEmitterInternal
currentSender
 
Constructor Summary
QNetworkCookie()
          Create a new QNetworkCookie object, initializing the cookie name to name and its value to value.
QNetworkCookie(QByteArray name)
          Create a new QNetworkCookie object, initializing the cookie name to name and its value to value.
QNetworkCookie(QByteArray name, QByteArray value)
          Create a new QNetworkCookie object, initializing the cookie name to name and its value to value.
QNetworkCookie(QNetworkCookie other)
          Creates a new QNetworkCookie object by copying the contents of other.
 
Method Summary
 QNetworkCookie clone()
          This method is reimplemented for internal reasons
 java.lang.String domain()
          Returns the domain this cookie is associated with.
 QDateTime expirationDate()
          Returns the expiration date for this cookie.
 boolean isHttpOnly()
          Returns true if the "HttpOnly" flag is enabled for this cookie.
 boolean isSecure()
          Returns true if the "secure" option was specified in the cookie string, false otherwise.
 boolean isSessionCookie()
          Returns true if this cookie is a session cookie.
 QByteArray name()
          Returns the name of this cookie.
static java.util.List parseCookies(QByteArray cookieString)
          Parses the cookie string cookieString as received from a server response in the "Set-Cookie." header.
 java.lang.String path()
          Returns the path associated with this cookie.
 void setDomain(java.lang.String domain)
          Sets the domain associated with this cookie to be domain.
 void setExpirationDate(QDateTime date)
          Sets the expiration date of this cookie to date.
 void setHttpOnly(boolean enable)
          Sets this cookie's "HttpOnly" flag to enable.
 void setName(QByteArray cookieName)
          Sets the name of this cookie to be cookieName.
 void setPath(java.lang.String path)
          Sets the path associated with this cookie to be path.
 void setSecure(boolean enable)
          Sets the secure flag of this cookie to enable.
 void setValue(QByteArray value)
          Sets the value of this cookie to be value.
 QByteArray toRawForm()
          Returns the raw form of this QNetworkCookie.
 QByteArray toRawForm(QNetworkCookie.RawForm form)
          Returns the raw form of this QNetworkCookie.
 java.lang.String toString()
          Returns a string representation of the this QNetworkCookie.
 QByteArray value()
          Returns this cookies value, as specified in the cookie string.
 
Methods inherited from class com.trolltech.qt.QtJambiObject
dispose, disposed, equals, finalize, reassignNativeResources, tr, tr, tr
 
Methods inherited from class com.trolltech.qt.QSignalEmitter
blockSignals, disconnect, disconnect, signalsBlocked, signalSender, thread
 
Methods inherited from class com.trolltech.qt.internal.QSignalEmitterInternal
__qt_signalInitialization
 
Methods inherited from class java.lang.Object
getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface com.trolltech.qt.QtJambiInterface
disableGarbageCollection, nativeId, nativePointer, reenableGarbageCollection, setJavaOwnership
 

Constructor Detail

QNetworkCookie

public QNetworkCookie(QByteArray name)
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.


QNetworkCookie

public QNetworkCookie()
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.


QNetworkCookie

public QNetworkCookie(QByteArray name,
                      QByteArray value)
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.


QNetworkCookie

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

Method Detail

domain

public final java.lang.String domain()
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().


expirationDate

public final QDateTime expirationDate()
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(), and setExpirationDate().


isHttpOnly

public final boolean isHttpOnly()
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().


isSecure

public final boolean isSecure()
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().


isSessionCookie

public final boolean isSessionCookie()
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(), and setExpirationDate().


name

public final QByteArray name()
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(), and value().


path

public final java.lang.String path()
Returns the path associated with this cookie. This corresponds to the "path" field of the cookie string.

See also:
setPath().


setDomain

public final void setDomain(java.lang.String domain)
Sets the domain associated with this cookie to be domain.

See also:
domain().


setExpirationDate

public final void setExpirationDate(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(), and expirationDate().


setHttpOnly

public final void setHttpOnly(boolean enable)
Sets this cookie's "HttpOnly" flag to enable.

See also:
isHttpOnly().


setName

public final void setName(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(), and value().


setPath

public final void setPath(java.lang.String path)
Sets the path associated with this cookie to be path.

See also:
path().


setSecure

public final void setSecure(boolean 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().


setValue

public final void setValue(QByteArray value)
Sets the value of this cookie to be value.

See also:
value(), and name().


toRawForm

public final QByteArray toRawForm()
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().


toRawForm

public final QByteArray toRawForm(QNetworkCookie.RawForm form)
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().


value

public final QByteArray value()
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(), and name().


parseCookies

public static java.util.List parseCookies(QByteArray cookieString)
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().


toString

public java.lang.String toString()
Returns a string representation of the this QNetworkCookie.

Overrides:
toString in class java.lang.Object

clone

public QNetworkCookie clone()
This method is reimplemented for internal reasons

Overrides:
clone in class java.lang.Object