Top |
Functions
Description
SoupCookie implements HTTP cookies, as described by RFC 6265.
To have a SoupSession handle cookies for your appliction automatically, use a SoupCookieJar.
Functions
soup_cookie_new ()
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.)
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.
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()
.)
Parameters
name |
cookie name |
|
value |
cookie value |
|
domain |
cookie domain or hostname |
|
path |
cookie path, or |
|
max_age |
max age of the cookie, or -1 for a session cookie |
Since 2.24
soup_cookie_parse ()
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.
Parameters
header |
a cookie string (eg, the value of a Set-Cookie header) |
|
origin |
origin of the cookie, or |
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
soup_cookie_set_name ()
void soup_cookie_set_name (SoupCookie *cookie
,const char *name
);
Sets cookie
's name to name
Since 2.24
soup_cookie_get_name ()
const char *
soup_cookie_get_name (SoupCookie *cookie
);
Gets cookie
's name
Since 2.32
soup_cookie_set_value ()
void soup_cookie_set_value (SoupCookie *cookie
,const char *value
);
Sets cookie
's value to value
Since 2.24
soup_cookie_get_value ()
const char *
soup_cookie_get_value (SoupCookie *cookie
);
Gets cookie
's value
Since 2.32
soup_cookie_set_domain ()
void soup_cookie_set_domain (SoupCookie *cookie
,const char *domain
);
Sets cookie
's domain to domain
Since 2.24
soup_cookie_get_domain ()
const char *
soup_cookie_get_domain (SoupCookie *cookie
);
Gets cookie
's domain
Since 2.32
soup_cookie_set_path ()
void soup_cookie_set_path (SoupCookie *cookie
,const char *path
);
Sets cookie
's path to path
Since 2.24
soup_cookie_get_path ()
const char *
soup_cookie_get_path (SoupCookie *cookie
);
Gets cookie
's path
Since 2.32
soup_cookie_set_max_age ()
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()
.)
Since 2.24
SOUP_COOKIE_MAX_AGE_ONE_HOUR
#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
SOUP_COOKIE_MAX_AGE_ONE_DAY
#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
SOUP_COOKIE_MAX_AGE_ONE_WEEK
#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
SOUP_COOKIE_MAX_AGE_ONE_YEAR
#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
soup_cookie_set_expires ()
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()
.)
Since 2.24
soup_cookie_get_expires ()
SoupDate *
soup_cookie_get_expires (SoupCookie *cookie
);
Gets cookie
's expiration time
Returns
cookie
's expiration time, which is
owned by cookie
and should not be modified or freed.
[transfer none]
Since 2.32
soup_cookie_set_secure ()
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.
Since 2.24
soup_cookie_get_secure ()
gboolean
soup_cookie_get_secure (SoupCookie *cookie
);
Gets cookie
's secure attribute
Since 2.32
soup_cookie_set_http_only ()
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.
Since 2.24
soup_cookie_get_http_only ()
gboolean
soup_cookie_get_http_only (SoupCookie *cookie
);
Gets cookie
's HttpOnly attribute
Since 2.32
soup_cookie_applies_to_uri ()
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.)
Since 2.24
soup_cookie_domain_matches ()
gboolean soup_cookie_domain_matches (SoupCookie *cookie
,const char *host
);
Checks if the cookie
's domain and host
match in the sense that
cookie
should be sent when making a request to host
, or that
cookie
should be accepted when receiving a response from host
.
Since 2.30
soup_cookie_to_cookie_header ()
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).
Since 2.24
soup_cookie_to_set_cookie_header ()
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).
Since 2.24
soup_cookies_from_request ()
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()
.)
Returns
a GSList
of SoupCookies, which can be freed with
soup_cookies_free()
.
[element-type SoupCookie][transfer full]
Since 2.24
soup_cookies_from_response ()
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
.
Returns
a GSList
of SoupCookies, which can be freed with
soup_cookies_free()
.
[element-type SoupCookie][transfer full]
Since 2.24
soup_cookies_to_request ()
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.)
Since 2.24
soup_cookies_to_response ()
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.)
Since 2.24
soup_cookies_to_cookie_header ()
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.
Since 2.24
Types and Values
SoupCookie
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 newer "max-age" attribute. 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.
Members
the cookie name |
||
the cookie value |
||
the "domain" attribute, or else the hostname that the cookie came from. |
||
the "path" attribute, or |
||
SoupDate * |
the cookie expiration time, or |
|
gboolean |
|
|
gboolean |
|
Since 2.24