SoupCookieJar: libsoup Reference Manual

## SoupCookieJar SoupCookieJar — Automatic cookie handling for SoupSession |

## Functions

SoupCookieJar * | soup_cookie_jar_new ()
char * | soup_cookie_jar_get_cookies ()
GSList * | soup_cookie_jar_get_cookie_list ()
GSList * | soup_cookie_jar_get_cookie_list_with_same_site_info ()
void | soup_cookie_jar_set_cookie ()
void | soup_cookie_jar_set_cookie_with_first_party ()
void | soup_cookie_jar_add_cookie ()
void | soup_cookie_jar_add_cookie_with_first_party ()
void | soup_cookie_jar_add_cookie_full ()
void | soup_cookie_jar_delete_cookie ()
GSList * | soup_cookie_jar_all_cookies ()
SoupCookieJarAcceptPolicy | soup_cookie_jar_get_accept_policy ()
void | soup_cookie_jar_set_accept_policy ()
gboolean | soup_cookie_jar_is_persistent ()

## Properties

SoupCookieJarAcceptPolicy | accept-policy | Read / Write
gboolean | read-only | Read / Write / Construct Only

## Signals

void | changed | Run First

## Types and Values

| SoupCookieJar
enum | SoupCookieJarAcceptPolicy
#define | SOUP_COOKIE_JAR_READ_ONLY
#define | SOUP_COOKIE_JAR_ACCEPT_POLICY

## Object Hierarchy

        GObject
        ╰── SoupCookieJar
            ├── SoupCookieJarDB
            ╰── SoupCookieJarText

## Implemented Interfaces

SoupCookieJar implements SoupSessionFeature.

## Includes

    #include <libsoup/soup.h>

## Description

A SoupCookieJar stores SoupCookies and arrange for them to be sent with the appropriate SoupMessages. SoupCookieJar implements SoupSessionFeature, so you can add a cookie jar to a session with `soup_session_add_feature()` or `soup_session_add_feature_by_type()`.

Note that the base SoupCookieJar class does not support any form of long-term cookie persistence.

## Functions

### soup_cookie_jar_new ()

    SoupCookieJar *
    soup_cookie_jar_new (void);

Creates a new SoupCookieJar. The base SoupCookieJar class does not support persistent storage of cookies; use a subclass for that.

#### Returns

a new SoupCookieJar

Since: 2.24

### soup_cookie_jar_get_cookies ()

    char *
    soup_cookie_jar_get_cookies (SoupCookieJar *jar,
                                 SoupURI *uri,
                                 gboolean for_http);

Retrieves (in Cookie-header form) the list of cookies that would be sent with a request to `uri` .

If `for_http` is `TRUE`, the return value will include cookies marked "HttpOnly" (that is, cookies that the server wishes to keep hidden from client-side scripting operations such as the JavaScript document.cookies property). Since SoupCookieJar sets the Cookie header itself when making the actual HTTP request, you should almost certainly be setting `for_http` to `FALSE` if you are calling this.

#### Parameters

jar | a SoupCookieJar |
uri | a SoupURI |
for_http | whether or not the return value is being passed directly to an HTTP operation |

#### Returns

the cookies, in string form, or `NULL` if there are no cookies for `uri` .

[nullable]

Since: 2.24

### soup_cookie_jar_get_cookie_list ()

    GSList *
    soup_cookie_jar_get_cookie_list (SoupCookieJar *jar,
                                     SoupURI *uri,
                                     gboolean for_http);

Retrieves the list of cookies that would be sent with a request to `uri` as a GSList of SoupCookie objects.

If `for_http` is `TRUE`, the return value will include cookies marked "HttpOnly" (that is, cookies that the server wishes to keep hidden from client-side scripting operations such as the JavaScript document.cookies property). Since SoupCookieJar sets the Cookie header itself when making the actual HTTP request, you should almost certainly be setting `for_http` to `FALSE` if you are calling this.

#### Parameters

jar | a SoupCookieJar |
uri | a SoupURI |
for_http | whether or not the return value is being passed directly to an HTTP operation |

#### Returns

a GSList with the cookies in the `jar` that would be sent with a request to `uri` .

[transfer full][element-type Soup.Cookie]

Since: 2.40

### soup_cookie_jar_get_cookie_list_with_same_site_info ()

    GSList *
    soup_cookie_jar_get_cookie_list_with_same_site_info
                                   (SoupCookieJar *jar,
                                    SoupURI *uri,
                                    SoupURI *top_level,
                                    SoupURI *site_for_cookies,
                                    gboolean for_http,
                                    gboolean is_safe_method,
                                    gboolean is_top_level_navigation);

This is an extended version of `soup_cookie_jar_get_cookie_list()` that provides more information required to use SameSite cookies. See the SameSite cookies spec for more detailed information.

#### Parameters

jar | a SoupCookieJar |
uri | a SoupURI |
top_level | a SoupURI for the top level document. | [nullable]
site_for_cookies | a SoupURI indicating the origin to get cookies for. | [nullable]
for_http | whether or not the return value is being passed directly to an HTTP operation |
is_safe_method | if the HTTP method is safe, as defined by RFC 7231, ignored when `for_http` is `FALSE` |
is_top_level_navigation | whether or not the HTTP request is part of top level navigation |

#### Returns

a GSList with the cookies in the `jar` that would be sent with a request to `uri` .

[transfer full][element-type Soup.Cookie]

Since: 2.70

### soup_cookie_jar_set_cookie ()

    void
    soup_cookie_jar_set_cookie (SoupCookieJar *jar,
                                SoupURI *uri,
                                const char *cookie);

Adds `cookie` to `jar` , exactly as though it had appeared in a Set-Cookie header returned from a request to `uri` .

Keep in mind that if the SoupCookieJarAcceptPolicy set is either `SOUP_COOKIE_JAR_ACCEPT_NO_THIRD_PARTY` or `SOUP_COOKIE_JAR_ACCEPT_GRANDFATHERED_THIRD_PARTY` you'll need to use `soup_cookie_jar_set_cookie_with_first_party()`, otherwise the jar will have no way of knowing if the cookie is being set by a third party or not.

#### Parameters

jar | a SoupCookieJar |
uri | the URI setting the cookie |
cookie | the stringified cookie to set |

Since: 2.24

### soup_cookie_jar_set_cookie_with_first_party ()

    void
    soup_cookie_jar_set_cookie_with_first_party
                                   (SoupCookieJar *jar,
                                    SoupURI *uri,
                                    SoupURI *first_party,
                                    const char *cookie);

Adds `cookie` to `jar` , exactly as though it had appeared in a Set-Cookie header returned from a request to `uri` . `first_party` will be used to reject cookies coming from third party resources in case such a security policy is set in the `jar` .

#### Parameters

jar | a SoupCookieJar |
uri | the URI setting the cookie |
first_party | the URI for the main document |
cookie | the stringified cookie to set |

Since: 2.30

### soup_cookie_jar_add_cookie ()

    void
    soup_cookie_jar_add_cookie (SoupCookieJar *jar,
                                SoupCookie *cookie);

Adds `cookie` to `jar` , emitting the 'changed' signal if we are modifying an existing cookie or adding a valid new cookie ('valid' means that the cookie's expire date is not in the past).

`cookie` will be 'stolen' by the jar, so don't free it afterwards.

#### Parameters

jar | a SoupCookieJar |
cookie | a SoupCookie. | [transfer full]

Since: 2.26

### soup_cookie_jar_add_cookie_with_first_party ()

    void
    soup_cookie_jar_add_cookie_with_first_party
                                   (SoupCookieJar *jar,
                                    SoupURI *first_party,
                                    SoupCookie *cookie);

Adds `cookie` to `jar` , emitting the 'changed' signal if we are modifying an existing cookie or adding a valid new cookie ('valid' means that the cookie's expire date is not in the past).

`first_party` will be used to reject cookies coming from third party resources in case such a security policy is set in the `jar` .

`cookie` will be 'stolen' by the jar, so don't free it afterwards.

For secure cookies to work properly you may want to use `soup_cookie_jar_add_cookie_full()`.

#### Parameters

jar | a SoupCookieJar |
first_party | the URI for the main document |
cookie | a SoupCookie. | [transfer full]

Since: 2.40

### soup_cookie_jar_add_cookie_full ()

    void
    soup_cookie_jar_add_cookie_full (SoupCookieJar *jar,
                                     SoupCookie *cookie,
                                     SoupURI *uri,
                                     SoupURI *first_party);

Adds `cookie` to `jar` , emitting the 'changed' signal if we are modifying an existing cookie or adding a valid new cookie ('valid' means that the cookie's expire date is not in the past).

`first_party` will be used to reject cookies coming from third party resources in case such a security policy is set in the `jar` .

`uri` will be used to reject setting or overwriting secure cookies from insecure origins. `NULL` is treated as secure.

`cookie` will be 'stolen' by the jar, so don't free it afterwards.

#### Parameters

jar | a SoupCookieJar |
cookie | a SoupCookie. | [transfer full]
uri | the URI setting the cookie. | [nullable]
first_party | the URI for the main document. | [nullable]

Since: 2.68

### soup_cookie_jar_delete_cookie ()

    void
    soup_cookie_jar_delete_cookie (SoupCookieJar *jar,
                                   SoupCookie *cookie);

Deletes `cookie` from `jar` , emitting the 'changed' signal.

#### Parameters

jar | a SoupCookieJar |
cookie | a SoupCookie |

Since: 2.26

### soup_cookie_jar_all_cookies ()

    GSList *
    soup_cookie_jar_all_cookies (SoupCookieJar *jar);

Constructs a GSList with every cookie inside the `jar` . The cookies in the list are a copy of the original, so you have to free them when you are done with them.

#### Parameters

jar | a SoupCookieJar |

#### Returns

a GSList with all the cookies in the `jar` .

[transfer full][element-type Soup.Cookie]

Since: 2.26

### soup_cookie_jar_get_accept_policy ()

    SoupCookieJarAcceptPolicy
    soup_cookie_jar_get_accept_policy (SoupCookieJar *jar);

Gets `jar` 's SoupCookieJarAcceptPolicy

#### Parameters

jar | a SoupCookieJar |

#### Returns

the SoupCookieJarAcceptPolicy set in the `jar`

Since: 2.30

### soup_cookie_jar_set_accept_policy ()

    void
    soup_cookie_jar_set_accept_policy (SoupCookieJar *jar,
                                       SoupCookieJarAcceptPolicy policy);

Sets `policy` as the cookie acceptance policy for `jar` .

#### Parameters

jar | a SoupCookieJar |
policy | a SoupCookieJarAcceptPolicy |

Since: 2.30

### soup_cookie_jar_is_persistent ()

    gboolean
    soup_cookie_jar_is_persistent (SoupCookieJar *jar);

Gets whether `jar` stores cookies persistenly.

#### Parameters

jar | a SoupCookieJar |

#### Returns

`TRUE` if `jar` storage is persistent or `FALSE` otherwise.

Since: 2.40

## Types and Values

### SoupCookieJar

    typedef struct _SoupCookieJar SoupCookieJar;

### enum SoupCookieJarAcceptPolicy

The policy for accepting or rejecting cookies returned in responses.

#### Members

SOUP_COOKIE_JAR_ACCEPT_ALWAYS | accept all cookies unconditionally. |
SOUP_COOKIE_JAR_ACCEPT_NEVER | reject all cookies unconditionally. |
SOUP_COOKIE_JAR_ACCEPT_NO_THIRD_PARTY | accept all cookies set by the main document loaded in the application using libsoup. An example of the most common case, web browsers, would be: If http://www.example.com is the page loaded, accept all cookies set by example.com, but if a resource from http://www.third-party.com is loaded from that page reject any cookie that it could try to set. For libsoup to be able to tell apart first party cookies from the rest, the application must call `soup_message_set_first_party()` on each outgoing SoupMessage, setting the SoupURI of the main document. If no first party is set in a message when this policy is in effect, cookies will be assumed to be third party by default. |
SOUP_COOKIE_JAR_ACCEPT_GRANDFATHERED_THIRD_PARTY | accept all cookies set by the main document loaded in the application using libsoup, and from domains that have previously set at least one cookie when loaded as the main document. An example of the most common case, web browsers, would be: if http://www.example.com is the page loaded, accept all cookies set by example.com, but if a resource from http://www.third-party.com is loaded from that page, reject any cookie that it could try to set unless it already has a cookie in the cookie jar. For libsoup to be able to tell apart first party cookies from the rest, the application must call `soup_message_set_first_party()` on each outgoing SoupMessage, setting the SoupURI of the main document. If no first party is set in a message when this policy is in effect, cookies will be assumed to be third party by default. Since 2.72. |

Since: 2.30

### SOUP_COOKIE_JAR_READ_ONLY

    #define SOUP_COOKIE_JAR_READ_ONLY "read-only"

Alias for the “read-only” property. (Whether or not the cookie jar is read-only.)

### SOUP_COOKIE_JAR_ACCEPT_POLICY

    #define SOUP_COOKIE_JAR_ACCEPT_POLICY "accept-policy"

Alias for the “accept-policy” property.

Since: 2.30

## Property Details

### The `“accept-policy”` property

      “accept-policy”            SoupCookieJarAcceptPolicy

The policy the jar should follow to accept or reject cookies

Owner: SoupCookieJar

Flags: Read / Write

Default value: SOUP_COOKIE_JAR_ACCEPT_ALWAYS

Since: 2.30

### The `“read-only”` property

      “read-only”                gboolean

Whether or not the cookie jar is read-only.

Owner: SoupCookieJar

Flags: Read / Write / Construct Only

Default value: FALSE

## Signal Details

### The `“changed”` signal

    void
    user_function (SoupCookieJar *jar,
                   SoupCookie    *old_cookie,
                   SoupCookie    *new_cookie,
                   gpointer       user_data)

Emitted when `jar` changes. If a cookie has been added, `new_cookie` will contain the newly-added cookie and `old_cookie` will be `NULL`. If a cookie has been deleted, `old_cookie` will contain the to-be-deleted cookie and `new_cookie` will be `NULL`. If a cookie has been changed, `old_cookie` will contain its old value, and `new_cookie` its new value.

#### Parameters

jar | the SoupCookieJar |
old_cookie | the old SoupCookie value |
new_cookie | the new SoupCookie value |
user_data | user data set when the signal handler was connected. |

Flags: Run First