Soup session state object.
[class@Session] is the object that controls client-side HTTP. A [class@Session] 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 [class@Session]; 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 [class@Message] 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 [class@Session] functionality is provided by [iface@SessionFeature] objects, which can be added to a session with [
method@Session.add_feature] or [method@Session.add_feature_by_type] For example, [class@Logger] provides support for logging HTTP traffic,
[class@ContentDecoder] provides support for compressed response handling, and [class@ContentSniffer] provides support for HTML5-style
response body content sniffing. Additionally, subtypes of [class@Auth] can be added as features, to add support for additional
authentication types.
All `SoupSession`s are created with a [class@AuthManager], and support for soup_type_auth_basic and
soup_type_auth_digest. Additionally, sessions using the plain [class@Session] class (rather than one of
its deprecated subtypes) have a [class@ContentDecoder] by default.
Note that all async methods will invoke their callbacks on the thread-default context at the time of the function call.
- public string accept_language { owned get; set; }
If non-null, the value to use for
the "Accept-Language" header on [class@Message]s sent from this session.
- public bool accept_language_auto { get; set; }
If true, [class@Session] will
automatically set the string for the "Accept-Language" header on every [class@Message] sent, based on the return value of [func@GLib.
- public MainContext async_context { get; owned construct; }
The
MainContext that miscellaneous session-related asynchronous callbacks are invoked on.
- public string[] http_aliases { owned get; set; }
A null-terminated array of URI
schemes that should be considered to be aliases for "http".
- public string[] https_aliases { owned get; set; }
A comma-delimited list of URI schemes that should be considered to be
aliases for "https".
- public uint idle_timeout { get; set; }
Connection lifetime (in seconds) when idle.
- public Address local_address { owned get; construct; }
Sets the [class@Gio.
- public int max_conns { get; set; }
The maximum number of connections that the session can open at once.
- public int max_conns_per_host { get; set; }
The maximum number of connections that the session can open at once to
a given host.
- public ProxyResolver proxy_resolver { owned get; set; }
A [iface@Gio.
- public URI proxy_uri { owned get; set; }
A proxy to use for all http and https requests in this session.
- public string ssl_ca_file { owned get; set; }
File containing SSL CA certificates.
- public bool ssl_strict { get; set; }
Normally, if
tls_database is set (including if it was set via
ssl_use_system_ca_file or
ssl_ca_file), then libsoup will reject any certificate that is invalid (
ie, expired) or that is not signed by one of the given CA certificates, and the Message
will fail with the status soup_status_ssl_failed.
- public bool ssl_use_system_ca_file { get; set; }
Setting this to true is equivalent
to setting tls_database to the default system CA database.
- public uint timeout { get; set; }
The timeout (in seconds) for socket I/O operations (including
connecting to a server, and waiting for a reply to an HTTP request).
- public TlsDatabase tls_database { owned get; set; }
Sets the [class@Gio.
- public TlsInteraction tls_interaction { owned get; set; }
A [class@Gio.
- public bool use_ntlm { get; set; }
Whether or not to use NTLM authentication.
- public bool use_thread_context { get; set; }
If true (which it always is on a
plain Session), asynchronous HTTP requests in this session will run in whatever the thread-default
MainContext is at the time they are started, rather than always
occurring in async_context.
- public string user_agent { owned get; set; }
User-Agent string.
- public void abort ()
Cancels all pending requests in this
and closes all idle persistent connections.
- public void add_feature (SessionFeature feature)
Adds feature's functionality to
this.
- public void add_feature_by_type (Type feature_type)
If feature_type is the type of a class that implements [
iface@SessionFeature], this creates a new feature of that type and adds it to this as with [
method@Session.
- public virtual void auth_required (Message msg, Auth auth, bool retrying)
- public virtual void cancel_message (Message msg, uint status_code)
Causes this to immediately finish
processing msg (regardless of its current state) with a final status_code of status_code.
- public async IOStream connect_async (URI uri, Cancellable? cancellable, SessionConnectProgressCallback? progress_callback) throws Error
Start a connection to uri.
- public virtual void flush_queue ()
- public unowned MainContext? get_async_context ()
- public unowned SessionFeature? get_feature (Type feature_type)
Gets the feature in this of type
feature_type.
- public unowned SessionFeature? get_feature_for_message (Type feature_type, Message msg)
Gets the feature in this of type
feature_type, provided that it is not disabled for msg.
- public SList<SessionFeature> get_features (Type feature_type)
Generates a list of this's features
of type feature_type.
- public bool has_feature (Type feature_type)
Tests if this has at a feature of
type feature_type (which can be the type of either a [iface@SessionFeature], or else a subtype of some class managed by
another feature, such as [class@Auth]).
- public virtual void kick ()
- public void pause_message (Message msg)
Pauses HTTP I/O on msg.
- public void prefetch_dns (string hostname, Cancellable? cancellable, AddressCallback? callback)
Tells this that an URI from the
given hostname may be requested shortly, and so the session can try to prepare by resolving the domain name in advance,
in order to work more quickly once the URI is actually requested.
- public void prepare_for_uri (URI uri)
Tells this that uri may
be requested shortly, and so the session can try to prepare (resolving the domain name, obtaining proxy address, etc.
- public virtual void queue_message (owned Message msg, SessionCallback? callback)
Queues the message msg for asynchronously sending the
request and receiving a response in the current thread-default MainContext
.
- public bool redirect_message (Message msg)
Updates msg's URI according to its status code and
"Location" header, and requeues it on this.
- public void remove_feature (SessionFeature feature)
Removes feature's functionality from
this.
- public void remove_feature_by_type (Type feature_type)
Removes all features of type feature_type (or any
subclass of feature_type) from this.
- public Request request (string uri_string) throws Error
Creates a Request for
retrieving uri_string.
- public RequestHTTP request_http (string method, string uri_string) throws Error
- public RequestHTTP request_http_uri (string method, URI uri) throws Error
- public Request request_uri (URI uri) throws Error
Creates a Request for
retrieving uri.
- public virtual void requeue_message (Message msg)
This causes msg to be placed back on the queue to be
attempted again.
- public InputStream send (Message msg, Cancellable? cancellable = null) throws Error
Synchronously sends msg and waits for the beginning of a
response.
- public async InputStream send_async (Message msg, Cancellable? cancellable = null) throws Error
Asynchronously sends msg and waits for the beginning of a
response.
- public virtual uint send_message (Message msg)
Synchronously send msg.
- public IOStream steal_connection (Message msg)
"Steals" the HTTP connection associated with msg from
this.
- public void unpause_message (Message msg)
Resumes HTTP I/O on msg.
- public async WebsocketConnection websocket_connect_async (Message msg, string? origin, string[]? protocols, Cancellable? cancellable) throws Error
Asynchronously creates a [class@WebsocketConnection] to communicate
with a remote server.
- public bool would_redirect (Message msg)
Checks if msg contains a response that would cause
this to redirect it to a new URL (ignoring msg's
soup_message_no_redirect flag, and the number of times it has already been redirected).
