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

Since 2.24

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

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

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.

Since 2.24

soup_cookie_copy ()

SoupCookie*         soup_cookie_copy                    (SoupCookie *cookie);

Copies cookie.

Since 2.24

soup_cookie_equal ()

gboolean            soup_cookie_equal                   (SoupCookie *cookie1,
                                                         SoupCookie *cookie2);

soup_cookie_free ()

void                soup_cookie_free                    (SoupCookie *cookie);

Frees cookie

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

void                soup_cookie_set_value               (SoupCookie *cookie,
                                                         const char *value);

Sets cookie's value to value

Since 2.24

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

void                soup_cookie_set_path                (SoupCookie *cookie,
                                                         const char *path);

Sets cookie's path to path

Since 2.24

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

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.

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

soup_cookies_free ()

void                soup_cookies_free                   (GSList *cookies);

Frees cookies.

Since 2.24