## SoupCookieJar

SoupCookieJar — Automatic cookie handling for SoupSession

## Synopsis

    #include <libsoup/soup.h>

                        SoupCookieJar;
    SoupCookieJar *     soup_cookie_jar_new                 (void);
    void                soup_cookie_jar_save                (SoupCookieJar *jar);
    char *              soup_cookie_jar_get_cookies         (SoupCookieJar *jar,
                                                             SoupURI *uri,
                                                             gboolean for_http);
    void                soup_cookie_jar_set_cookie          (SoupCookieJar *jar,
                                                             SoupURI *uri,
                                                             const char *cookie);

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

    #define             SOUP_COOKIE_JAR_READ_ONLY

## Object Hierarchy

      GObject
       +----SoupCookieJar
             +----SoupCookieJarText
             +----SoupCookieJarSqlite

## 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_save ()

    void                soup_cookie_jar_save                (SoupCookieJar *jar);

### Warning

`soup_cookie_jar_save` is deprecated and should not be used in newly-written code.

`jar` : |

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

Since 2.26

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

Since 2.26

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

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

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