manpagez: man pages & more
html files: libsoup-2.4
Home | html | info | man

SoupCookieJar

SoupCookieJar — Automatic cookie handling for SoupSession

Properties

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

Signals

void changed Run First

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

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

© manpagez.com 2000-2018
Individual documents may contain additional copyright information.