SoupCookieJar

## SoupCookieJar SoupCookieJar — Automatic cookie handling for SoupSession |

## Synopsis

    #include <libsoup/soup.h>

                        SoupCookieJar;
    SoupCookieJar *     soup_cookie_jar_new                 (void);
    char *              soup_cookie_jar_get_cookies         (SoupCookieJar *jar,
                                                             SoupURI *uri,
                                                             gboolean for_http);
    GSList *            soup_cookie_jar_get_cookie_list     (SoupCookieJar *jar,
                                                             SoupURI *uri,
                                                             gboolean for_http);
    void                soup_cookie_jar_set_cookie          (SoupCookieJar *jar,
                                                             SoupURI *uri,
                                                             const char *cookie);
    void                soup_cookie_jar_set_cookie_with_first_party
                                                            (SoupCookieJar *jar,
                                                             SoupURI *uri,
                                                             SoupURI *first_party,
                                                             const char *cookie);

    void                soup_cookie_jar_add_cookie          (SoupCookieJar *jar,
                                                             SoupCookie *cookie);
    void                soup_cookie_jar_add_cookie_with_first_party
                                                            (SoupCookieJar *jar,
                                                             SoupURI *first_party,
                                                             SoupCookie *cookie);
    void                soup_cookie_jar_delete_cookie       (SoupCookieJar *jar,
                                                             SoupCookie *cookie);
    GSList *            soup_cookie_jar_all_cookies         (SoupCookieJar *jar);

    enum                SoupCookieJarAcceptPolicy;
    SoupCookieJarAcceptPolicy soup_cookie_jar_get_accept_policy
                                                            (SoupCookieJar *jar);
    void                soup_cookie_jar_set_accept_policy   (SoupCookieJar *jar,
                                                             SoupCookieJarAcceptPolicy policy);

    gboolean            soup_cookie_jar_is_persistent       (SoupCookieJar *jar);

    #define             SOUP_COOKIE_JAR_READ_ONLY
    #define             SOUP_COOKIE_JAR_ACCEPT_POLICY

## Object Hierarchy

      GObject
       +----SoupCookieJar
             +----SoupCookieJarDB
             +----SoupCookieJarText

## Implemented Interfaces

SoupCookieJar implements SoupSessionFeature.

## Properties

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

## Signals

      "changed"                                        : Run First

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

## Details

### SoupCookieJar

    typedef struct _SoupCookieJar SoupCookieJar;

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

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

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.

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

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

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

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

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

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

`jar` : | a SoupCookieJar
Returns : | a GSList with all the cookies in the `jar`. [transfer full][element-type Soup.Cookie]

Since 2.26

### enum SoupCookieJarAcceptPolicy

    typedef enum {
    	SOUP_COOKIE_JAR_ACCEPT_ALWAYS,
    	SOUP_COOKIE_JAR_ACCEPT_NEVER,
    	SOUP_COOKIE_JAR_ACCEPT_NO_THIRD_PARTY
    } SoupCookieJarAcceptPolicy;

The policy for accepting or rejecting cookies returned in responses.

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

    SoupCookieJarAcceptPolicy soup_cookie_jar_get_accept_policy
                                                            (SoupCookieJar *jar);

Gets `jar`'s SoupCookieJarAcceptPolicy

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

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

`jar` : | a SoupCookieJar
Returns : | `TRUE` if `jar` storage is persistent or `FALSE` otherwise.

Since 2.40

### 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  : Read / Write

The policy the jar should follow to accept or reject cookies

Default value: SOUP_COOKIE_JAR_ACCEPT_ALWAYS

Since 2.30

### The `"read-only"` property

      "read-only"                gboolean              : Read / Write / Construct Only

Whether or not the cookie jar is read-only.

Default value: FALSE

## Signal Details

### The `"changed"` signal

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

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.

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