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);
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_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);

#define             SOUP_COOKIE_JAR_READ_ONLY
#define             SOUP_COOKIE_JAR_ACCEPT_POLICY

Object Hierarchy

  GObject
   +----SoupCookieJar
         +----SoupCookieJarSqlite
         +----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_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

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. [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;

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.

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