SoupCookieJar

SoupCookieJar — Automatic cookie handling for SoupSession

Functions

Properties

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

Signals

Types and Values

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

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