SoupSession

SoupSession — Soup session state object

Functions

SoupSession * soup_session_new ()
SoupSession * soup_session_new_with_options ()
GInetSocketAddress * soup_session_get_local_address ()
guint soup_session_get_max_conns ()
guint soup_session_get_max_conns_per_host ()
void soup_session_set_proxy_resolver ()
GProxyResolver * soup_session_get_proxy_resolver ()
void soup_session_set_tls_database ()
GTlsDatabase * soup_session_get_tls_database ()
void soup_session_set_tls_interaction ()
GTlsInteraction * soup_session_get_tls_interaction ()
void soup_session_set_timeout ()
guint soup_session_get_timeout ()
void soup_session_set_idle_timeout ()
guint soup_session_get_idle_timeout ()
void soup_session_set_user_agent ()
const char * soup_session_get_user_agent ()
void soup_session_set_accept_language ()
const char * soup_session_get_accept_language ()
void soup_session_set_accept_language_auto ()
gboolean soup_session_get_accept_language_auto ()
SoupMessage * soup_session_get_async_result_message ()
GSocketConnectable * soup_session_get_remote_connectable ()
GInputStream * soup_session_send ()
void soup_session_send_async ()
GInputStream * soup_session_send_finish ()
GBytes * soup_session_send_and_read ()
void soup_session_send_and_read_async ()
GBytes * soup_session_send_and_read_finish ()
void soup_session_websocket_connect_async ()
SoupWebsocketConnection * soup_session_websocket_connect_finish ()
void soup_session_abort ()
void soup_session_add_feature ()
void soup_session_add_feature_by_type ()
void soup_session_remove_feature ()
void soup_session_remove_feature_by_type ()
GSList * soup_session_get_features ()
SoupSessionFeature * soup_session_get_feature ()
SoupSessionFeature * soup_session_get_feature_for_message ()
gboolean soup_session_has_feature ()
void soup_session_preconnect_async ()
gboolean soup_session_preconnect_finish ()

Properties

char * accept-language Read / Write
gboolean accept-language-auto Read / Write
guint idle-timeout Read / Write
GInetSocketAddress * local-address Read / Write / Construct Only
int max-conns Read / Write / Construct Only
int max-conns-per-host Read / Write / Construct Only
GProxyResolver * proxy-resolver Read / Write
GSocketConnectable * remote-connectable Read / Write / Construct Only
guint timeout Read / Write
GTlsDatabase * tls-database Read / Write
GTlsInteraction * tls-interaction Read / Write
char * user-agent Read / Write

Signals

Types and Values

Object Hierarchy

    GObject
    ╰── SoupSession

Includes

#include <libsoup/soup.h>

Description

SoupSession is the object that controls client-side HTTP. A SoupSession encapsulates all of the state that libsoup is keeping on behalf of your program; cached HTTP connections, authentication information, etc. It also keeps track of various global options and features that you are using.

Most applications will only need a single SoupSession; the primary reason you might need multiple sessions is if you need to have multiple independent authentication contexts. (Eg, you are connecting to a server and authenticating as two different users at different times; the easiest way to ensure that each SoupMessage is sent with the authentication information you intended is to use one session for the first user, and a second session for the other user.)

Additional SoupSession functionality is provided by SoupSessionFeature objects, which can be added to a session with soup_session_add_feature() or soup_session_add_feature_by_type() For example, SoupLogger provides support for logging HTTP traffic, SoupContentDecoder provides support for compressed response handling, and SoupContentSniffer provides support for HTML5-style response body content sniffing. Additionally, subtypes of SoupAuth can be added as features, to add support for additional authentication types.

All SoupSessions are created with a SoupAuthManager, and support for SOUP_TYPE_AUTH_BASIC and SOUP_TYPE_AUTH_DIGEST. Additionally, sessions using the plain SoupSession class (rather than one of its deprecated subtypes) have a SoupContentDecoder by default.

Functions

soup_session_new ()

SoupSession *
soup_session_new (void);

Creates a SoupSession with the default options.

Returns

the new session.


soup_session_new_with_options ()

SoupSession *
soup_session_new_with_options (const char *optname1,
                               ...);

Creates a SoupSession with the specified options.

Parameters

optname1

name of first property to set

 

...

value of optname1 , followed by additional property/value pairs

 

Returns

the new session.


soup_session_get_local_address ()

GInetSocketAddress *
soup_session_get_local_address (SoupSession *session);

Get the GInetSocketAddress to use for the client side of connections in session .

Parameters

session

a SoupSession

 

Returns

a GInetSocketAddress or NULL.

[transfer none][nullable]


soup_session_get_max_conns ()

guint
soup_session_get_max_conns (SoupSession *session);

Get the maximum number of connections that session can open at once.

Parameters

session

a SoupSession

 

Returns

the maximum number of connections


soup_session_get_max_conns_per_host ()

guint
soup_session_get_max_conns_per_host (SoupSession *session);

Get the maximum number of connections that session can open at once to a given host.

Parameters

session

a SoupSession

 

Returns

the maximum number of connections per host


soup_session_set_proxy_resolver ()

void
soup_session_set_proxy_resolver (SoupSession *session,
                                 GProxyResolver *proxy_resolver);

Set a GProxyResolver to be used by session on new connections. If proxy_resolver is NULL then no proxies will be used. See “proxy-resolver” for more information.

Parameters

session

a SoupSession

 

proxy_resolver

a GProxyResolver or NULL.

[nullable]

soup_session_get_proxy_resolver ()

GProxyResolver *
soup_session_get_proxy_resolver (SoupSession *session);

Get the GProxyResolver currently used by session .

Parameters

session

a SoupSession

 

Returns

a GProxyResolver or NULL if proxies are disabled in session .

[transfer none][nullable]


soup_session_set_tls_database ()

void
soup_session_set_tls_database (SoupSession *session,
                               GTlsDatabase *tls_database);

Set a GTlsDatabase to be used by session on new connections. If tls_database is NULL then certificate validation will always fail. See “tls-database” for more information.

Parameters

session

a SoupSession

 

tls_database

a GTlsDatabase or NULL.

[nullable]

soup_session_get_tls_database ()

GTlsDatabase *
soup_session_get_tls_database (SoupSession *session);

Get the GTlsDatabase currently used by session .

Parameters

session

a SoupSession

 

Returns

a GTlsDatabase or NULL.

[transfer none][nullable]


soup_session_set_tls_interaction ()

void
soup_session_set_tls_interaction (SoupSession *session,
                                  GTlsInteraction *tls_interaction);

Set a GTlsInteraction to be used by session on new connections. If tls_interaction is NULL then client certificate validation will always fail. See “tls-interaction” for more information.

Parameters

session

a SoupSession

 

tls_interaction

a GTlsInteraction or NULL.

[nullable]

soup_session_get_tls_interaction ()

GTlsInteraction *
soup_session_get_tls_interaction (SoupSession *session);

Get the GTlsInteraction currently used by session .

Parameters

session

a SoupSession

 

Returns

a GTlsInteraction or NULL.

[transfer none][nullable]


soup_session_set_timeout ()

void
soup_session_set_timeout (SoupSession *session,
                          guint timeout);

Set a timeout in seconds for socket I/O operations to be used by session on new connections. See “timeout” for more information.

Parameters

session

a SoupSession

 

timeout

a timeout in seconds

 

soup_session_get_timeout ()

guint
soup_session_get_timeout (SoupSession *session);

Get the timeout in seconds for socket I/O operations currently used by session .

Parameters

session

a SoupSession

 

Returns

the timeout in seconds


soup_session_set_idle_timeout ()

void
soup_session_set_idle_timeout (SoupSession *session,
                               guint timeout);

Set a timeout in seconds for idle connection lifetime to be used by session on new connections. See “idle-timeout” for more information.

Parameters

session

a SoupSession

 

timeout

a timeout in seconds

 

soup_session_get_idle_timeout ()

guint
soup_session_get_idle_timeout (SoupSession *session);

Get the timeout in seconds for idle connection lifetime currently used by session .

Parameters

session

a SoupSession

 

Returns

the timeout in seconds


soup_session_set_user_agent ()

void
soup_session_set_user_agent (SoupSession *session,
                             const char *user_agent);

Set the value to use for the "User-Agent" header on SoupMessages sent from session . If user_agent has trailing whitespace, session will append its own product token (eg, "libsoup/3.0.0") to the end of the header for you. If user_agent is NULL then no "User-Agent" will be included in requests. See “user-agent” for more information.

Parameters

session

a SoupSession

 

user_agent

the user agent string

 

soup_session_get_user_agent ()

const char *
soup_session_get_user_agent (SoupSession *session);

Get the value used by session for the "User-Agent" header on new requests.

Parameters

session

a SoupSession

 

Returns

the user agent string or NULL.

[transfer none][nullable]


soup_session_set_accept_language ()

void
soup_session_set_accept_language (SoupSession *session,
                                  const char *accept_language);

Set the value to use for the "Accept-Language" header on SoupMessages sent from session . If accept_language is NULL then no "Accept-Language" will be included in requests. See “accept-language” for more information.

Parameters

session

a SoupSession

 

accept_language

the languages string

 

soup_session_get_accept_language ()

const char *
soup_session_get_accept_language (SoupSession *session);

Get the value used by session for the "Accept-Language" header on new requests.

Parameters

session

a SoupSession

 

Returns

the accept language string or NULL.

[transfer none][nullable]


soup_session_set_accept_language_auto ()

void
soup_session_set_accept_language_auto (SoupSession *session,
                                       gboolean accept_language_auto);

Set whether session will automatically set the "Accept-Language" header on requests using a value generated from system languages based on g_get_language_names(). See “accept-language-auto” for more information.

Parameters

session

a SoupSession

 

accept_language_auto

the value to set

 

soup_session_get_accept_language_auto ()

gboolean
soup_session_get_accept_language_auto (SoupSession *session);

Get whether session automatically sets the "Accept-Language" header on new requests.

Parameters

session

a SoupSession

 

Returns

TRUE if session sets "Accept-Language" header automatically, or FALSE otherwise.


soup_session_get_async_result_message ()

SoupMessage *
soup_session_get_async_result_message (SoupSession *session,
                                       GAsyncResult *result);

Gets the SoupMessage of the result asynchronous operation This is useful to get the SoupMessage of an asynchronous operation started by session from its GAsyncReadyCallback.

Parameters

session

a SoupSession

 

result

the GAsyncResult passed to your callback

 

Returns

a SoupMessage or NULL if result is not a valid session async operation result.

[transfer none][nullable]


soup_session_get_remote_connectable ()

GSocketConnectable *
soup_session_get_remote_connectable (SoupSession *session);

Get the remote connectable if one set.

Parameters

session

a SoupSession

 

Returns

the GSocketConnectable or NULL.

[transfer none][nullable]


soup_session_send ()

GInputStream *
soup_session_send (SoupSession *session,
                   SoupMessage *msg,
                   GCancellable *cancellable,
                   GError **error);

Synchronously sends msg and waits for the beginning of a response. On success, a GInputStream will be returned which you can use to read the response body. ("Success" here means only that an HTTP response was received and understood; it does not necessarily mean that a 2xx class status code was received.)

If non-NULL, cancellable can be used to cancel the request; soup_session_send() will return a G_IO_ERROR_CANCELLED error. Note that with requests that have side effects (eg, POST, PUT, DELETE) it is possible that you might cancel the request after the server acts on it, but before it returns a response, leaving the remote resource in an unknown state.

If msg is requeued due to a redirect or authentication, the initial (3xx/401/407) response body will be suppressed, and soup_session_send() will only return once a final response has been received.

Parameters

session

a SoupSession

 

msg

a SoupMessage

 

cancellable

a GCancellable

 

error

return location for a GError, or NULL

 

Returns

a GInputStream for reading the response body, or NULL on error.

[transfer full]


soup_session_send_async ()

void
soup_session_send_async (SoupSession *session,
                         SoupMessage *msg,
                         int io_priority,
                         GCancellable *cancellable,
                         GAsyncReadyCallback callback,
                         gpointer user_data);

Asynchronously sends msg and waits for the beginning of a response. When callback is called, then either msg has been sent, and its response headers received, or else an error has occurred. Call soup_session_send_finish() to get a GInputStream for reading the response body.

See soup_session_send() for more details on the general semantics.

Parameters

session

a SoupSession

 

msg

a SoupMessage

 

io_priority

the I/O priority of the request

 

cancellable

a GCancellable

 

callback

the callback to invoke

 

user_data

data for callback

 

soup_session_send_finish ()

GInputStream *
soup_session_send_finish (SoupSession *session,
                          GAsyncResult *result,
                          GError **error);

Gets the response to a soup_session_send_async() call and (if successful), returns a GInputStream that can be used to read the response body.

Parameters

session

a SoupSession

 

result

the GAsyncResult passed to your callback

 

error

return location for a GError, or NULL

 

Returns

a GInputStream for reading the response body, or NULL on error.

[transfer full]


soup_session_send_and_read ()

GBytes *
soup_session_send_and_read (SoupSession *session,
                            SoupMessage *msg,
                            GCancellable *cancellable,
                            GError **error);

Synchronously sends msg and reads the response body. On success, a GBytes will be returned with the response body. This function should only be used when the resource to be retrieved is not too long and can be stored in memory.

See soup_session_send() for more details on the general semantics.

Parameters

session

a SoupSession

 

msg

a SoupMessage

 

cancellable

a GCancellable

 

error

return location for a GError, or NULL

 

Returns

a GBytes, or NULL on error.

[transfer full]


soup_session_send_and_read_async ()

void
soup_session_send_and_read_async (SoupSession *session,
                                  SoupMessage *msg,
                                  int io_priority,
                                  GCancellable *cancellable,
                                  GAsyncReadyCallback callback,
                                  gpointer user_data);

Asynchronously sends msg and reads the response body. When callback is called, then either msg has been sent, and its response body read, or else an error has occurred. This function should only be used when the resource to be retrieved is not too long and can be stored in memory. Call soup_session_send_and_read_finish() to get a GBytes with the response body.

See soup_session_send() for more details on the general semantics.

Parameters

session

a SoupSession

 

msg

a SoupMessage

 

io_priority

the I/O priority of the request

 

cancellable

a GCancellable

 

callback

the callback to invoke

 

user_data

data for callback

 

soup_session_send_and_read_finish ()

GBytes *
soup_session_send_and_read_finish (SoupSession *session,
                                   GAsyncResult *result,
                                   GError **error);

Gets the response to a soup_session_send_and_read_async() call and (if successful), returns a GBytes with the response body.

Parameters

session

a SoupSession

 

result

the GAsyncResult passed to your callback

 

error

return location for a GError, or NULL

 

Returns

a GBytes, or NULL on error.

[transfer full]


soup_session_websocket_connect_async ()

void
soup_session_websocket_connect_async (SoupSession *session,
                                      SoupMessage *msg,
                                      const char *origin,
                                      char **protocols,
                                      int io_priority,
                                      GCancellable *cancellable,
                                      GAsyncReadyCallback callback,
                                      gpointer user_data);

Asynchronously creates a SoupWebsocketConnection to communicate with a remote server.

All necessary WebSocket-related headers will be added to msg , and it will then be sent and asynchronously processed normally (including handling of redirection and HTTP authentication).

If the server returns "101 Switching Protocols", then msg 's status code and response headers will be updated, and then the WebSocket handshake will be completed. On success, soup_session_websocket_connect_finish() will return a new SoupWebsocketConnection. On failure it will return a GError.

If the server returns a status other than "101 Switching Protocols", then msg will contain the complete response headers and body from the server's response, and soup_session_websocket_connect_finish() will return SOUP_WEBSOCKET_ERROR_NOT_WEBSOCKET.

Parameters

session

a SoupSession

 

msg

SoupMessage indicating the WebSocket server to connect to

 

origin

origin of the connection.

[allow-none]

protocols

a NULL-terminated array of protocols supported.

[allow-none][array zero-terminated=1]

io_priority

the I/O priority of the request

 

cancellable

a GCancellable

 

callback

the callback to invoke

 

user_data

data for callback

 

soup_session_websocket_connect_finish ()

SoupWebsocketConnection *
soup_session_websocket_connect_finish (SoupSession *session,
                                       GAsyncResult *result,
                                       GError **error);

Gets the SoupWebsocketConnection response to a soup_session_websocket_connect_async() call and (if successful), returns a SoupWebsocketConnection that can be used to communicate with the server.

Parameters

session

a SoupSession

 

result

the GAsyncResult passed to your callback

 

error

return location for a GError, or NULL

 

Returns

a new SoupWebsocketConnection, or NULL on error.

[transfer full]


soup_session_abort ()

void
soup_session_abort (SoupSession *session);

Cancels all pending requests in session and closes all idle persistent connections.

Parameters

session

the session

 

soup_session_add_feature ()

void
soup_session_add_feature (SoupSession *session,
                          SoupSessionFeature *feature);

Adds feature 's functionality to session .

See the main SoupSession documentation for information on what features are present in sessions by default.

Parameters

session

a SoupSession

 

feature

an object that implements SoupSessionFeature

 

soup_session_add_feature_by_type ()

void
soup_session_add_feature_by_type (SoupSession *session,
                                  GType feature_type);

If feature_type is the type of a class that implements SoupSessionFeature, this creates a new feature of that type and adds it to session as with soup_session_add_feature(). You can use this when you don't need to customize the new feature in any way.

If feature_type is not a SoupSessionFeature type, this gives each existing feature on session the chance to accept feature_type as a "subfeature". This can be used to add new SoupAuth types, for instance.

See the main SoupSession documentation for information on what features are present in sessions by default.

Parameters

session

a SoupSession

 

feature_type

a GType

 

soup_session_remove_feature ()

void
soup_session_remove_feature (SoupSession *session,
                             SoupSessionFeature *feature);

Removes feature 's functionality from session .

Parameters

session

a SoupSession

 

feature

a feature that has previously been added to session

 

soup_session_remove_feature_by_type ()

void
soup_session_remove_feature_by_type (SoupSession *session,
                                     GType feature_type);

Removes all features of type feature_type (or any subclass of feature_type ) from session . You can also remove standard features from the session at construct time by using the SoupSession:remove-feature-by-type property.

Parameters

session

a SoupSession

 

feature_type

a GType

 

soup_session_get_features ()

GSList *
soup_session_get_features (SoupSession *session,
                           GType feature_type);

Generates a list of session 's features of type feature_type . (If you want to see all features, you can pass SOUP_TYPE_SESSION_FEATURE for feature_type .)

Parameters

session

a SoupSession

 

feature_type

the GType of the class of features to get

 

Returns

a list of features. You must free the list, but not its contents.

[transfer container][element-type Soup.SessionFeature]


soup_session_get_feature ()

SoupSessionFeature *
soup_session_get_feature (SoupSession *session,
                          GType feature_type);

Gets the first feature in session of type feature_type . For features where there may be more than one feature of a given type, use soup_session_get_features().

Parameters

session

a SoupSession

 

feature_type

the GType of the feature to get

 

Returns

a SoupSessionFeature, or NULL. The feature is owned by session .

[nullable][transfer none]


soup_session_get_feature_for_message ()

SoupSessionFeature *
soup_session_get_feature_for_message (SoupSession *session,
                                      GType feature_type,
                                      SoupMessage *msg);

Gets the first feature in session of type feature_type , provided that it is not disabled for msg . As with soup_session_get_feature(), this should only be used for features where feature_type is only expected to match a single feature. In particular, if there are two matching features, and the first is disabled on msg , and the second is not, then this will return NULL, not the second feature.

Parameters

session

a SoupSession

 

feature_type

the GType of the feature to get

 

msg

a SoupMessage

 

Returns

a SoupSessionFeature, or NULL. The feature is owned by session .

[nullable][transfer none]


soup_session_has_feature ()

gboolean
soup_session_has_feature (SoupSession *session,
                          GType feature_type);

Tests if session has at a feature of type feature_type (which can be the type of either a SoupSessionFeature, or else a subtype of some class managed by another feature, such as SoupAuth).

Parameters

session

a SoupSession

 

feature_type

the GType of the class of features to check for

 

Returns

TRUE or FALSE


soup_session_preconnect_async ()

void
soup_session_preconnect_async (SoupSession *session,
                               SoupMessage *msg,
                               int io_priority,
                               GCancellable *cancellable,
                               GAsyncReadyCallback callback,
                               gpointer user_data);

Start a preconnection to msg . Once the connection is done, it will remain in idle state so that it can be reused by future requests. If there's already an idle connection for the given msg host, the operation finishes successfully without creating a new connection. If a new request for the given msg host is made while the preconnect is still ongoing, the request will take the ownership of the connection and the preconnect operation will finish successfully (if there's a connection error it will be handled by the request).

The operation finishes when the connection is done or an error ocurred.

Parameters

session

a SoupSession

 

msg

a SoupMessage

 

io_priority

the I/O priority of the request

 

cancellable

a GCancellable

 

callback

the callback to invoke when the operation finishes.

[allow-none][scope async]

user_data

data for progress_callback and callback

 

soup_session_preconnect_finish ()

gboolean
soup_session_preconnect_finish (SoupSession *session,
                                GAsyncResult *result,
                                GError **error);

Complete a preconnect async operation started with soup_session_preconnect_async().

Parameters

session

a SoupSession

 

result

the GAsyncResult passed to your callback

 

error

return location for a GError, or NULL

 

Returns

TRUE if the preconnect succeeded, or FALSE in case of error.

Types and Values

SoupSession

typedef struct _SoupSession SoupSession;

Class managing options and state for SoupMessages.


enum SoupSessionError

A SoupSession error.

Members

SOUP_SESSION_ERROR_PARSING

the server's response could not be parsed

 

SOUP_SESSION_ERROR_ENCODING

the server's response was in an unsupported format

 

SOUP_SESSION_ERROR_TOO_MANY_REDIRECTS

the message has been redirected too many times

 

SOUP_SESSION_ERROR_TOO_MANY_RESTARTS

the message has been restarted too many times

 

SOUP_SESSION_ERROR_REDIRECT_NO_LOCATION

failed to redirect message because Location header was missing or empty in response

 

SOUP_SESSION_ERROR_REDIRECT_BAD_URI

failed to redirect message because Location header contains an invalid URI

 

Property Details

The “accept-language” property

  “accept-language”          char *

If non-NULL, the value to use for the "Accept-Language" header on SoupMessages sent from this session.

Setting this will disable “accept-language-auto”.

Owner: SoupSession

Flags: Read / Write

Default value: NULL


The “accept-language-auto” property

  “accept-language-auto”     gboolean

If TRUE, SoupSession will automatically set the string for the "Accept-Language" header on every SoupMessage sent, based on the return value of g_get_language_names().

Setting this will override any previous value of “accept-language”.

Owner: SoupSession

Flags: Read / Write

Default value: FALSE


The “idle-timeout” property

  “idle-timeout”             guint

Connection lifetime (in seconds) when idle. Any connection left idle longer than this will be closed.

Although you can change this property at any time, it will only affect newly-created connections, not currently-open ones. You can call soup_session_abort() after setting this if you want to ensure that all future connections will have this timeout value.

Owner: SoupSession

Flags: Read / Write

Default value: 60


The “local-address” property

  “local-address”            GInetSocketAddress *

Sets the GInetSocketAddress to use for the client side of the connection.

Use this property if you want for instance to bind the local socket to a specific IP address.

Owner: SoupSession

Flags: Read / Write / Construct Only


The “max-conns” property

  “max-conns”                int

The maximum number of connections that the session can open at once.

Owner: SoupSession

Flags: Read / Write / Construct Only

Allowed values: >= 1

Default value: 10


The “max-conns-per-host” property

  “max-conns-per-host”       int

The maximum number of connections that the session can open at once to a given host.

Owner: SoupSession

Flags: Read / Write / Construct Only

Allowed values: >= 1

Default value: 2


The “proxy-resolver” property

  “proxy-resolver”           GProxyResolver *

A GProxyResolver to use with this session.

If no proxy resolver is set, then the default proxy resolver will be used. See g_proxy_resolver_get_default(). You can set it to NULL if you don't want to use proxies, or set it to your own GProxyResolver if you want to control what proxies get used.

Owner: SoupSession

Flags: Read / Write


The “remote-connectable” property

  “remote-connectable”       GSocketConnectable *

Sets a socket to make outgoing connections on. This will override the default behaviour of opening TCP/IP sockets to the hosts specified in the URIs.

This function is not required for common HTTP usage, but only when connecting to a HTTP service that is not using standard TCP/IP sockets. An example of this is a local service that uses HTTP over UNIX-domain sockets, in that case a GUnixSocketAddress can be passed to this function.

Owner: SoupSession

Flags: Read / Write / Construct Only


The “timeout” property

  “timeout”                  guint

The timeout (in seconds) for socket I/O operations (including connecting to a server, and waiting for a reply to an HTTP request).

Although you can change this property at any time, it will only affect newly-created connections, not currently-open ones. You can call soup_session_abort() after setting this if you want to ensure that all future connections will have this timeout value.

Not to be confused with “idle-timeout” (which is the length of time that idle persistent connections will be kept open).

Owner: SoupSession

Flags: Read / Write

Default value: 0


The “tls-database” property

  “tls-database”             GTlsDatabase *

Sets the GTlsDatabase to use for validating SSL/TLS certificates.

If no certificate database is set, then the default database will be used. See g_tls_backend_get_default_database().

Owner: SoupSession

Flags: Read / Write


The “tls-interaction” property

  “tls-interaction”          GTlsInteraction *

A GTlsInteraction object that will be passed on to any GTlsConnections created by the session. (This can be used to provide client-side certificates, for example.)

Owner: SoupSession

Flags: Read / Write


The “user-agent” property

  “user-agent”               char *

If non-NULL, the value to use for the "User-Agent" header on SoupMessages sent from this session.

RFC 2616 says: "The User-Agent request-header field contains information about the user agent originating the request. This is for statistical purposes, the tracing of protocol violations, and automated recognition of user agents for the sake of tailoring responses to avoid particular user agent limitations. User agents SHOULD include this field with requests."

The User-Agent header contains a list of one or more product tokens, separated by whitespace, with the most significant product token coming first. The tokens must be brief, ASCII, and mostly alphanumeric (although "-", "_", and "." are also allowed), and may optionally include a "/" followed by a version string. You may also put comments, enclosed in parentheses, between or after the tokens.

If you set a “user_agent” property that has trailing whitespace, SoupSession will append its own product token (eg, "libsoup/2.3.2") to the end of the header for you.

Owner: SoupSession

Flags: Read / Write

Default value: NULL

Signal Details

The “request-queued” signal

void
user_function (SoupSession *session,
               SoupMessage *msg,
               gpointer     user_data)

Emitted when a request is queued on session .

When sending a request, first “request_queued” is emitted, indicating that the session has become aware of the request.

After a connection is available to send the request various SoupMessage signals are emitted as the message is processed. If the message is requeued, it will emit “restarted”, which will then be followed by other SoupMessage signals when the message is re-sent.

Eventually, the message will emit “finished”. Normally, this signals the completion of message processing. However, it is possible that the application will requeue the message from the "finished" handler. In that case the process will loop back.

Eventually, a message will reach "finished" and not be requeued. At that point, the session will emit “request_unqueued” to indicate that it is done with the message.

To sum up: “request_queued” and “request_unqueued” are guaranteed to be emitted exactly once, but “finished” (and all of the other SoupMessage signals) may be invoked multiple times for a given message.

Parameters

session

the session

 

msg

the request that was queued

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “request-unqueued” signal

void
user_function (SoupSession *session,
               SoupMessage *msg,
               gpointer     user_data)

Emitted when a request is removed from session 's queue, indicating that session is done with it. See “request_queued” for a detailed description of the message lifecycle within a session.

Parameters

session

the session

 

msg

the request that was unqueued

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First