## SoupCookie

SoupCookie — HTTP Cookies

## Synopsis

    #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);

## Description

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.

## Details

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

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

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

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

`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

### soup_cookie_copy ()

    SoupCookie *        soup_cookie_copy                    (SoupCookie *cookie);

Copies `cookie`.

`cookie` : | a SoupCookie
Returns : | a copy of `cookie`

Since 2.24

### soup_cookie_equal ()

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

`cookie1` : |
`cookie2` : |
Returns : |

### soup_cookie_free ()

    void                soup_cookie_free                    (SoupCookie *cookie);

Frees `cookie`

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

`cookie` : | a SoupCookie
`name` : | the new name

Since 2.24

### soup_cookie_set_value ()

    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

### soup_cookie_set_domain ()

    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

### soup_cookie_set_path ()

    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

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

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

`cookie` : | a SoupCookie
`expires` : | the new expiration time, or `NULL`

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.

`cookie` : | a SoupCookie
`secure` : | the new value for the secure attribute

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.

`cookie` : | a SoupCookie
`http_only` : | the new value for the HttpOnly attribute

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

`cookie` : | a SoupCookie
`uri` : | a SoupURI
Returns : | `TRUE` if `cookie` should be sent to `uri`, `FALSE` if not

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

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

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

`msg` : | a SoupMessage containing a "Cookie" request header
Returns : | a GSList of SoupCookies, which can be freed with `soup_cookies_free()`.

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

`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

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

`cookies` : | a GSList of 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.)

`cookies` : | a GSList of 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.

`cookies` : | a GSList of SoupCookie
Returns : | the serialization of `cookies`

Since 2.24

### soup_cookies_free ()

    void                soup_cookies_free                   (GSList *cookies);

Frees `cookies`.

`cookies` : | a GSList of SoupCookie

Since 2.24

## See Also

#SoupMessage