SoupCookie

SoupCookie — HTTP Cookies

Types and Values

Object Hierarchy

    GBoxed
    ╰── SoupCookie

Includes

#include <libsoup/soup.h>

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 NULL

 

max_age

max age of the cookie, or -1 for a session cookie

 

Returns

a new SoupCookie.

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

[nullable]

Since: 2.24


soup_cookie_copy ()

SoupCookie *
soup_cookie_copy (SoupCookie *cookie);

Copies cookie .

Parameters

cookie

a SoupCookie

 

Returns

a copy of cookie

Since: 2.24


soup_cookie_free ()

void
soup_cookie_free (SoupCookie *cookie);

Frees cookie

Parameters

cookie

a SoupCookie

 

Since: 2.24


soup_cookie_set_name ()

void
soup_cookie_set_name (SoupCookie *cookie,
                      const char *name);

Sets cookie 's name to name

Parameters

cookie

a SoupCookie

 

name

the new name

 

Since: 2.24


soup_cookie_get_name ()

const char *
soup_cookie_get_name (SoupCookie *cookie);

Gets cookie 's name

Parameters

cookie

a SoupCookie

 

Returns

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

Parameters

cookie

a SoupCookie

 

value

the new value

 

Since: 2.24


soup_cookie_get_value ()

const char *
soup_cookie_get_value (SoupCookie *cookie);

Gets cookie 's value

Parameters

cookie

a SoupCookie

 

Returns

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

Parameters

cookie

a SoupCookie

 

domain

the new domain

 

Since: 2.24


soup_cookie_get_domain ()

const char *
soup_cookie_get_domain (SoupCookie *cookie);

Gets cookie 's domain

Parameters

cookie

a SoupCookie

 

Returns

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

Parameters

cookie

a SoupCookie

 

path

the new path

 

Since: 2.24


soup_cookie_get_path ()

const char *
soup_cookie_get_path (SoupCookie *cookie);

Gets cookie 's path

Parameters

cookie

a SoupCookie

 

Returns

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

Parameters

cookie

a SoupCookie

 

max_age

the new max age

 

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

Parameters

cookie

a SoupCookie

 

expires

the new expiration time, or NULL

 

Since: 2.24


soup_cookie_get_expires ()

SoupDate *
soup_cookie_get_expires (SoupCookie *cookie);

Gets cookie 's expiration time

Parameters

cookie

a SoupCookie

 

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.

Parameters

cookie

a SoupCookie

 

secure

the new value for the secure attribute

 

Since: 2.24


soup_cookie_get_secure ()

gboolean
soup_cookie_get_secure (SoupCookie *cookie);

Gets cookie 's secure attribute

Parameters

cookie

a SoupCookie

 

Returns

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.

Parameters

cookie

a SoupCookie

 

http_only

the new value for the HttpOnly attribute

 

Since: 2.24


soup_cookie_get_http_only ()

gboolean
soup_cookie_get_http_only (SoupCookie *cookie);

Gets cookie 's HttpOnly attribute

Parameters

cookie

a SoupCookie

 

Returns

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

Parameters

cookie

a SoupCookie

 

uri

a SoupURI

 

Returns

TRUE if cookie should be sent to uri , FALSE if not

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 .

Parameters

cookie

a SoupCookie

 

host

a URI

 

Returns

TRUE if the domains match, FALSE otherwise

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

Parameters

cookie

a SoupCookie

 

Returns

the header

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

Parameters

cookie

a SoupCookie

 

Returns

the header

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

Parameters

msg

a SoupMessage containing a "Cookie" request header

 

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 .

Parameters

msg

a SoupMessage containing a "Set-Cookie" response header

 

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

Parameters

cookies

a GSList of SoupCookie.

[element-type SoupCookie]

msg

a SoupMessage

 

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

Parameters

cookies

a GSList of SoupCookie.

[element-type SoupCookie]

msg

a SoupMessage

 

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.

Parameters

cookies

a GSList of SoupCookie.

[element-type SoupCookie]

Returns

the serialization of cookies

Since: 2.24


soup_cookies_free ()

void
soup_cookies_free (GSList *cookies);

Frees cookies .

[skip]

Parameters

cookies

a GSList of SoupCookie.

[element-type SoupCookie]

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

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