| libsoup Reference Manual | ||||
|---|---|---|---|---|
| Top | Description | ||||
#include <libsoup/soup.h>
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.
| the cookie name | |
| the cookie value | |
| the "domain" attribute, or else the hostname that the cookie came from. | |
the "path" attribute, or NULL
|
|
SoupDate * |
the cookie expiration time, or NULL for a session cookie
|
gboolean |
TRUE if the cookie should only be tranferred over SSL
|
gboolean |
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().)
|
cookie name |
|
cookie value |
|
cookie domain or hostname |
|
cookie path, or NULL
|
|
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.
|
a cookie string (eg, the value of a Set-Cookie header) |
|
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.
|
a SoupCookie |
Returns : |
a copy of cookie
|
Since 2.24
gboolean soup_cookie_equal (SoupCookie *cookie1,SoupCookie *cookie2);
|
|
|
|
Returns : |
void soup_cookie_free (SoupCookie *cookie);
Frees cookie
|
a SoupCookie |
Since 2.24
void soup_cookie_set_name (SoupCookie *cookie,const char *name);
Sets cookie's name to name
|
a SoupCookie |
|
the new name |
Since 2.24
void soup_cookie_set_value (SoupCookie *cookie,const char *value);
Sets cookie's value to value
|
a SoupCookie |
|
the new value |
Since 2.24
void soup_cookie_set_domain (SoupCookie *cookie,const char *domain);
Sets cookie's domain to domain
|
a SoupCookie |
|
the new domain |
Since 2.24
void soup_cookie_set_path (SoupCookie *cookie,const char *path);
Sets cookie's path to path
|
a SoupCookie |
|
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().)
|
a SoupCookie |
|
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().)
|
a SoupCookie |
|
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.
|
a SoupCookie |
|
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.
|
a SoupCookie |
|
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.)
|
a SoupCookie |
|
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).
|
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).
|
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().)
|
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.
|
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.)
|
a GSList of SoupCookie |
|
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.)
|
a GSList of SoupCookie |
|
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.
|
a GSList of SoupCookie |
Returns : |
the serialization of cookies
|
Since 2.24
void soup_cookies_free (GSList *cookies);
Frees cookies.
|
a GSList of SoupCookie |
Since 2.24