SoupSession: libsoup Reference Manual

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

void | request-queued | Run Last
void | request-unqueued | Run Last

## Types and Values

| SoupSession
enum | SoupSessionError

## 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. | [nullable]
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. | [nullable]
callback | the callback to invoke. | [scope async]
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. | [nullable]
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. | [nullable]
callback | the callback to invoke. | [scope async]
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. | [nullable]
protocols | a `NULL`-terminated array of protocols supported. | [nullable][array zero-terminated=1]
io_priority | the I/O priority of the request |
cancellable | a GCancellable. | [nullable]
callback | the callback to invoke. | [scope async]
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` . You cannot add multiple features of the same GType to a 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. Adding multiple features of the same `feature_type` is not allowed.

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_feature ()

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

Gets the feature in `session` of type `feature_type` .

#### 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 feature in `session` of type `feature_type` , provided that it is not disabled for `msg` .

#### 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. | [nullable]
callback | the callback to invoke when the operation finishes. | [nullable][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 |
SOUP_SESSION_ERROR_MESSAGE_ALREADY_IN_QUEUE | the message is already in the session queue. Messages can only be reused after unqueued. |

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

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