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 ()
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_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_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 `SOUP_COOKIE_JAR_ACCEPT_NO_THIRD_PARTY` is set 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.

#### Parameters

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

Since: 2.40

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

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

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.

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