SoupCookie: libsoup Reference Manual

## SoupCookie SoupCookie — HTTP Cookies |

## Functions

SoupCookie * | soup_cookie_new ()
SoupCookie * | soup_cookie_parse ()
SoupCookie * | soup_cookie_copy ()
void | soup_cookie_free ()
void | soup_cookie_set_name ()
const char * | soup_cookie_get_name ()
void | soup_cookie_set_value ()
const char * | soup_cookie_get_value ()
void | soup_cookie_set_domain ()
const char * | soup_cookie_get_domain ()
void | soup_cookie_set_path ()
const char * | soup_cookie_get_path ()
void | soup_cookie_set_max_age ()
void | soup_cookie_set_expires ()
SoupDate * | soup_cookie_get_expires ()
void | soup_cookie_set_secure ()
gboolean | soup_cookie_get_secure ()
void | soup_cookie_set_http_only ()
gboolean | soup_cookie_get_http_only ()
gboolean | soup_cookie_applies_to_uri ()
gboolean | soup_cookie_domain_matches ()
char * | soup_cookie_to_cookie_header ()
char * | soup_cookie_to_set_cookie_header ()
GSList * | soup_cookies_from_request ()
GSList * | soup_cookies_from_response ()
void | soup_cookies_to_request ()
void | soup_cookies_to_response ()
char * | soup_cookies_to_cookie_header ()
void | soup_cookies_free ()

## Types and Values

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

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

[nullable][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

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

## See Also

SoupMessage, SoupCookieJar