![]() |
![]() |
![]() |
libsoup Reference Manual | ![]() |
---|---|---|---|---|
SoupCookie; SoupCookie* soup_cookie_new (const char *name, const char *value, const char *domain, const char *path, int max_age); SoupCookie* soup_cookie_parse (const char *header, SoupURI *origin); SoupCookie* soup_cookie_copy (SoupCookie *cookie); gboolean soup_cookie_equal (SoupCookie *cookie1, SoupCookie *cookie2); void soup_cookie_free (SoupCookie *cookie); void soup_cookie_set_name (SoupCookie *cookie, const char *name); void soup_cookie_set_value (SoupCookie *cookie, const char *value); void soup_cookie_set_domain (SoupCookie *cookie, const char *domain); void soup_cookie_set_path (SoupCookie *cookie, const char *path); void soup_cookie_set_max_age (SoupCookie *cookie, int max_age); #define SOUP_COOKIE_MAX_AGE_ONE_HOUR #define SOUP_COOKIE_MAX_AGE_ONE_DAY #define SOUP_COOKIE_MAX_AGE_ONE_WEEK #define SOUP_COOKIE_MAX_AGE_ONE_YEAR void soup_cookie_set_expires (SoupCookie *cookie, SoupDate *expires); void soup_cookie_set_secure (SoupCookie *cookie, gboolean secure); void soup_cookie_set_http_only (SoupCookie *cookie, gboolean http_only); gboolean soup_cookie_applies_to_uri (SoupCookie *cookie, SoupURI *uri); char* soup_cookie_to_cookie_header (SoupCookie *cookie); char* soup_cookie_to_set_cookie_header (SoupCookie *cookie); GSList* soup_cookies_from_request (SoupMessage *msg); GSList* soup_cookies_from_response (SoupMessage *msg); void soup_cookies_to_request (GSList *cookies, SoupMessage *msg); void soup_cookies_to_response (GSList *cookies, SoupMessage *msg); char* soup_cookies_to_cookie_header (GSList *cookies); void soup_cookies_free (GSList *cookies);
SoupCookie implements HTTP cookies, primarily as described by the original Netscape cookie specification, but with slight modifications based on RFC 2109, Microsoft's HttpOnly extension attribute, and observed real-world usage (and, in particular, based on what Firefox does).
To have a SoupSession handle cookies for your appliction automatically, use a SoupCookieJar.
typedef struct { char *name; char *value; char *domain; char *path; SoupDate *expires; gboolean secure; gboolean http_only; } SoupCookie;
An HTTP cookie.
name
and value
will be set for all cookies. If the cookie is
generated from a string that appears to have no name, then name
will be the empty string.
domain
and path
give the host or domain, and path within that
host/domain, to restrict this cookie to. If domain
starts with
".", that indicates a domain (which matches the string after the
".", or any hostname that has domain
as a suffix). Otherwise, it
is a hostname and must match exactly.
expires
will be non-NULL
if the cookie uses either the original
"expires" attribute, or the "max-age" attribute specified in RFC
2109. If expires
is NULL
, it indicates that neither "expires" nor
"max-age" was specified, and the cookie expires at the end of the
session.
If http_only
is set, the cookie should not be exposed to untrusted
code (eg, javascript), so as to minimize the danger posed by
cross-site scripting attacks.
char *name ; |
the cookie name |
char *value ; |
the cookie value |
char *domain ; |
the "domain" attribute, or else the hostname that the cookie came from. |
char *path ; |
the "path" attribute, or NULL
|
SoupDate *expires ; |
the cookie expiration time, or NULL for a session cookie
|
gboolean secure ; |
TRUE if the cookie should only be tranferred over SSL
|
gboolean http_only ; |
TRUE if the cookie should not be exposed to scripts
|
Since 2.24
SoupCookie* soup_cookie_new (const char *name, const char *value, const char *domain, const char *path, int max_age);
Creates a new SoupCookie with the given attributes. (Use
soup_cookie_set_secure()
and soup_cookie_set_http_only()
if you
need to set those attributes on the returned cookie.)
max_age
is used to set the "expires" attribute on the cookie; pass
-1 to not include the attribute (indicating that the cookie expires
with the current session), 0 for an already-expired cookie, or a
lifetime in seconds. You can use the constants
SOUP_COOKIE_MAX_AGE_ONE_HOUR
, SOUP_COOKIE_MAX_AGE_ONE_DAY
,
SOUP_COOKIE_MAX_AGE_ONE_WEEK
and SOUP_COOKIE_MAX_AGE_ONE_YEAR
(or
multiples thereof) to calculate this value. (If you really care
about setting the exact time that the cookie will expire, use
soup_cookie_set_expires()
.)
name : |
cookie name |
value : |
cookie value |
domain : |
cookie domain or hostname |
path : |
cookie path, or NULL
|
max_age : |
max age of the cookie, or -1 for a session cookie |
Returns : | a new SoupCookie. |
Since 2.24
SoupCookie* soup_cookie_parse (const char *header, SoupURI *origin);
Parses header
and returns a SoupCookie. (If header
contains
multiple cookies, only the first one will be parsed.)
If header
does not have "path" or "domain" attributes, they will
be defaulted from origin
. If origin
is NULL
, path will default
to "/", but domain will be left as NULL
. Note that this is not a
valid state for a SoupCookie, and you will need to fill in some
appropriate string for the domain if you want to actually make use
of the cookie.
header : |
a cookie string (eg, the value of a Set-Cookie header) |
origin : |
origin of the cookie, or NULL
|
Returns : | a new SoupCookie, or NULL if it could not be
parsed, or contained an illegal "domain" attribute for a cookie
originating from origin .
|
Since 2.24
SoupCookie* soup_cookie_copy (SoupCookie *cookie);
Copies cookie
.
cookie : |
a SoupCookie |
Returns : | a copy of cookie
|
Since 2.24
gboolean soup_cookie_equal (SoupCookie *cookie1, SoupCookie *cookie2);
cookie1 : |
|
cookie2 : |
|
Returns : |
void soup_cookie_free (SoupCookie *cookie);
Frees cookie
cookie : |
a SoupCookie |
Since 2.24
void soup_cookie_set_name (SoupCookie *cookie, const char *name);
Sets cookie
's name to name
cookie : |
a SoupCookie |
name : |
the new name |
Since 2.24
void soup_cookie_set_value (SoupCookie *cookie, const char *value);
Sets cookie
's value to value
cookie : |
a SoupCookie |
value : |
the new value |
Since 2.24
void soup_cookie_set_domain (SoupCookie *cookie, const char *domain);
Sets cookie
's domain to domain
cookie : |
a SoupCookie |
domain : |
the new domain |
Since 2.24
void soup_cookie_set_path (SoupCookie *cookie, const char *path);
Sets cookie
's path to path
cookie : |
a SoupCookie |
path : |
the new path |
Since 2.24
void soup_cookie_set_max_age (SoupCookie *cookie, int max_age);
Sets cookie
's max age to max_age
. If max_age
is -1, the cookie
is a session cookie, and will expire at the end of the client's
session. Otherwise, it is the number of seconds until the cookie
expires. You can use the constants SOUP_COOKIE_MAX_AGE_ONE_HOUR
,
SOUP_COOKIE_MAX_AGE_ONE_DAY
, SOUP_COOKIE_MAX_AGE_ONE_WEEK
and
SOUP_COOKIE_MAX_AGE_ONE_YEAR
(or multiples thereof) to calculate
this value. (A value of 0 indicates that the cookie should be
considered already-expired.)
(This sets the same property as soup_cookie_set_expires()
.)
cookie : |
a SoupCookie |
max_age : |
the new max age |
Since 2.24
#define SOUP_COOKIE_MAX_AGE_ONE_HOUR (60 * 60)
A constant corresponding to 1 hour, for use with soup_cookie_new()
and soup_cookie_set_max_age()
.
Since 2.24
#define SOUP_COOKIE_MAX_AGE_ONE_DAY (SOUP_COOKIE_MAX_AGE_ONE_HOUR * 24)
A constant corresponding to 1 day, for use with soup_cookie_new()
and soup_cookie_set_max_age()
.
Since 2.24
#define SOUP_COOKIE_MAX_AGE_ONE_WEEK (SOUP_COOKIE_MAX_AGE_ONE_DAY * 7)
A constant corresponding to 1 week, for use with soup_cookie_new()
and soup_cookie_set_max_age()
.
Since 2.24
#define SOUP_COOKIE_MAX_AGE_ONE_YEAR (SOUP_COOKIE_MAX_AGE_ONE_DAY * 365.2422)
A constant corresponding to 1 year, for use with soup_cookie_new()
and soup_cookie_set_max_age()
.
Since 2.24
void soup_cookie_set_expires (SoupCookie *cookie, SoupDate *expires);
Sets cookie
's expiration time to expires
. If expires
is NULL
,
cookie
will be a session cookie and will expire at the end of the
client's session.
(This sets the same property as soup_cookie_set_max_age()
.)
cookie : |
a SoupCookie |
expires : |
the new expiration time, or NULL
|
Since 2.24
void soup_cookie_set_secure (SoupCookie *cookie, gboolean secure);
Sets cookie
's secure attribute to secure
. If TRUE
, cookie
will
only be transmitted from the client to the server over secure
(https) connections.
cookie : |
a SoupCookie |
secure : |
the new value for the secure attribute |
Since 2.24
void soup_cookie_set_http_only (SoupCookie *cookie, gboolean http_only);
Sets cookie
's HttpOnly attribute to http_only
. If TRUE
, cookie
will be marked as "http only", meaning it should not be exposed to
web page scripts or other untrusted code.
cookie : |
a SoupCookie |
http_only : |
the new value for the HttpOnly attribute |
Since 2.24
gboolean soup_cookie_applies_to_uri (SoupCookie *cookie, SoupURI *uri);
Tests if cookie
should be sent to uri
.
(At the moment, this does not check that cookie
's domain matches
uri
, because it assumes that the caller has already done that.
But don't rely on that; it may change in the future.)
cookie : |
a SoupCookie |
uri : |
a SoupURI |
Returns : | TRUE if cookie should be sent to uri , FALSE if
not
|
Since 2.24
char* soup_cookie_to_cookie_header (SoupCookie *cookie);
Serializes cookie
in the format used by the Cookie header (ie, for
returning a cookie from a SoupSession to a server).
cookie : |
a SoupCookie |
Returns : | the header |
Since 2.24
char* soup_cookie_to_set_cookie_header (SoupCookie *cookie);
Serializes cookie
in the format used by the Set-Cookie header
(ie, for sending a cookie from a SoupServer to a client).
cookie : |
a SoupCookie |
Returns : | the header |
Since 2.24
GSList* soup_cookies_from_request (SoupMessage *msg);
Parses msg
's Cookie request header and returns a GSList of
SoupCookies. As the "Cookie" header, unlike "Set-Cookie",
only contains cookie names and values, none of the other
SoupCookie fields will be filled in. (Thus, you can't generally
pass a cookie returned from this method directly to
soup_cookies_to_response()
.)
msg : |
a SoupMessage containing a "Cookie" request header |
Returns : | a GSList of SoupCookies, which can be freed
with soup_cookies_free() .
|
Since 2.24
GSList* soup_cookies_from_response (SoupMessage *msg);
Parses msg
's Set-Cookie response headers and returns a GSList of
SoupCookies. Cookies that do not specify "path" or
"domain" attributes will have their values defaulted from msg
.
msg : |
a SoupMessage containing a "Set-Cookie" response header |
Returns : | a GSList of SoupCookies, which can be freed
with soup_cookies_free() .
|
Since 2.24
void soup_cookies_to_request (GSList *cookies, SoupMessage *msg);
Adds the name and value of each cookie in cookies
to msg
's
"Cookie" request. (If msg
already has a "Cookie" request header,
these cookies will be appended to the cookies already present. Be
careful that you do not append the same cookies twice, eg, when
requeuing a message.)
cookies : |
a GSList of SoupCookie |
msg : |
a SoupMessage |
Since 2.24
void soup_cookies_to_response (GSList *cookies, SoupMessage *msg);
Appends a "Set-Cookie" response header to msg
for each cookie in
cookies
. (This is in addition to any other "Set-Cookie" headers
msg
may already have.)
cookies : |
a GSList of SoupCookie |
msg : |
a SoupMessage |
Since 2.24
char* soup_cookies_to_cookie_header (GSList *cookies);
Serializes a GSList of SoupCookie into a string suitable for setting as the value of the "Cookie" header.
cookies : |
a GSList of SoupCookie |
Returns : | the serialization of cookies
|
Since 2.24
void soup_cookies_free (GSList *cookies);
Frees cookies
.
cookies : |
a GSList of SoupCookie |
Since 2.24