Class

SoupSession

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

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

Ancestors

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 features 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 features 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_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 SoupMessages 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 SoupMessages 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 SoupMessages 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 GTlsConnections 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 sessions queue, indicating that session is done with it.

Signals inherited from GObject (1)
GObject.Object::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
  );
  
}
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.