### Class

# Soup Session

#### Description [src]

    class Soup.Session : GObject.Object {
      parent_instance: GObject
    }

Soup session state object.

`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 `SoupSession`s 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.

Note that all async methods will invoke their callbacks on the thread-default context at the time of the function call.

#### Hierarchy

#### Ancestors

- GObject

#### Constructors

###### soup_session_new

Creates a `SoupSession` with the default options.

###### soup_session_new_with_options

Creates a `SoupSession` with the specified options.

#### Instance methods

###### soup_session_abort

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

###### soup_session_add_feature

Adds `feature`‘s functionality to `session`. You cannot add multiple features of the same `GType` to a session.

###### soup_session_add_feature_by_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.

###### soup_session_get_accept_language

Get the value used by `session` for the “Accept-Language” header on new requests.

###### soup_session_get_accept_language_auto

Gets whether `session` automatically sets the “Accept-Language” header on new requests.

###### soup_session_get_async_result_message

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

###### soup_session_get_feature

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

###### soup_session_get_feature_for_message

Gets the feature in `session` of type `feature_type`, provided that it is not disabled for `msg`.

###### soup_session_get_idle_timeout

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

###### soup_session_get_local_address

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

###### soup_session_get_max_conns

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

###### soup_session_get_max_conns_per_host

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

###### soup_session_get_proxy_resolver

Get the `GProxyResolver` currently used by `session`.

###### soup_session_get_remote_connectable

Gets the remote connectable if one set.

###### soup_session_get_timeout

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

###### soup_session_get_tls_database

Get the `GTlsDatabase` currently used by `session`.

###### soup_session_get_tls_interaction

Get the `GTlsInteraction` currently used by `session`.

###### soup_session_get_user_agent

Get the value used by `session` for the “User-Agent” header on new requests.

###### soup_session_has_feature

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`).

###### soup_session_preconnect_async

Start a preconnection to `msg`.

###### soup_session_preconnect_finish

Complete a preconnect async operation started with `soup_session_preconnect_async()`.

###### soup_session_remove_feature

Removes `feature`‘s functionality from `session`.

###### soup_session_remove_feature_by_type

Removes all features of type `feature_type` (or any subclass of `feature_type`) from `session`.

###### soup_session_send

Synchronously sends `msg` and waits for the beginning of a response.

###### soup_session_send_and_read

Synchronously sends `msg` and reads the response body.

###### soup_session_send_and_read_async

Asynchronously sends `msg` and reads the response body.

###### soup_session_send_and_read_finish

Gets the response to a `soup_session_send_and_read_async()`.

###### soup_session_send_and_splice

Synchronously sends `msg` and splices the response body stream into `out_stream`.

since: 3.4

###### soup_session_send_and_splice_async

Asynchronously sends `msg` and splices the response body stream into `out_stream`. When `callback` is called, then either `msg` has been sent and its response body spliced, or else an error has occurred.

since: 3.4

###### soup_session_send_and_splice_finish

Gets the response to a `soup_session_send_and_splice_async()`.

since: 3.4

###### soup_session_send_async

Asynchronously sends `msg` and waits for the beginning of a response.

###### soup_session_send_finish

Gets the response to a `soup_session_send_async()` call.

###### soup_session_set_accept_language

Set the value to use for the “Accept-Language” header on `SoupMessage`s sent from `session`.

###### soup_session_set_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()`.

###### soup_session_set_idle_timeout

Set a timeout in seconds for idle connection lifetime to be used by `session` on new connections.

###### soup_session_set_proxy_resolver

Set a `GProxyResolver` to be used by `session` on new connections.

###### soup_session_set_timeout

Set a timeout in seconds for socket I/O operations to be used by `session` on new connections.

###### soup_session_set_tls_database

Set a GIo.TlsDatabase to be used by `session` on new connections.

###### soup_session_set_tls_interaction

Set a `GTlsInteraction` to be used by `session` on new connections.

###### soup_session_set_user_agent

Set the value to use for the “User-Agent” header on `SoupMessage`s sent from `session`.

###### soup_session_websocket_connect_async

Asynchronously creates a `SoupWebsocketConnection` to communicate with a remote server.

###### soup_session_websocket_connect_finish

Gets the `SoupWebsocketConnection` response to a `soup_session_websocket_connect_async()` call.

##### Methods inherited from GObject (43)

Please see GObject for a full list of methods.

#### Properties

###### Soup.Session:accept-language

If non-`NULL`, the value to use for the “Accept-Language” header on `SoupMessage`s sent from this session.

###### Soup.Session:accept-language-auto

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()`.

###### Soup.Session:idle-timeout

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

###### Soup.Session:local-address

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

###### Soup.Session:max-conns

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

###### Soup.Session:max-conns-per-host

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

###### Soup.Session:proxy-resolver

A `GProxyResolver` to use with this session.

###### Soup.Session:remote-connectable

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.

###### Soup.Session:timeout

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

###### Soup.Session:tls-database

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

###### Soup.Session:tls-interaction

A `GTlsInteraction` object that will be passed on to any `GTlsConnection`s created by the session.

###### Soup.Session:user-agent

User-Agent string.

#### Signals

###### Soup.Session::request-queued

Emitted when a request is queued on `session`.

###### Soup.Session::request-unqueued

Emitted when a request is removed from `session`‘s queue, indicating that `session` is done with it.

##### Signals inherited from GObject (1)

###### GObject::notify

The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.

#### Class structure

    struct SoupSessionClass {
      GObjectClass parent_class;
      void (* request_queued) (
        SoupSession* session,
        SoupMessage* msg
      );
      void (* request_unqueued) (
        SoupSession* session,
        SoupMessage* msg
      );
      void (* _soup_reserved1) (
    void
      );
      void (* _soup_reserved2) (
    void
      );
      void (* _soup_reserved3) (
    void
      );
      void (* _soup_reserved4) (
    void
      );
      void (* _soup_reserved5) (
    void
      );
      void (* _soup_reserved6) (
    void
      );
      void (* _soup_reserved7) (
    void
      );
      void (* _soup_reserved8) (
    void
      );

    }

No description available.

###### Class members

`parent_class: GObjectClass`
  No description available.
`request_queued: void (* request_queued) ( SoupSession* session, SoupMessage* msg )`
  No description available.
`request_unqueued: void (* request_unqueued) ( SoupSession* session, SoupMessage* msg )`
  No description available.
`_soup_reserved1: void (* _soup_reserved1) ( void )`
  No description available.
`_soup_reserved2: void (* _soup_reserved2) ( void )`
  No description available.
`_soup_reserved3: void (* _soup_reserved3) ( void )`
  No description available.
`_soup_reserved4: void (* _soup_reserved4) ( void )`
  No description available.
`_soup_reserved5: void (* _soup_reserved5) ( void )`
  No description available.
`_soup_reserved6: void (* _soup_reserved6) ( void )`
  No description available.
`_soup_reserved7: void (* _soup_reserved7) ( void )`
  No description available.
`_soup_reserved8: void (* _soup_reserved8) ( void )`
  No description available.

#### Virtual methods

###### Soup.SessionClass.request_queued

No description available.

###### Soup.SessionClass.request_unqueued

No description available.