Struct soup::Session

pub struct Session { /* private fields */ }

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 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 #SoupSession functionality is provided by SessionFeature objects, which can be added to a session with SessionExt::add_feature() or SessionExt::add_feature_by_type() For example, Logger provides support for logging HTTP traffic, ContentDecoder provides support for compressed response handling, and ContentSniffer provides support for HTML5-style response body content sniffing. Additionally, subtypes of Auth can be added as features, to add support for additional authentication types.

All SoupSessions are created with a AuthManager, 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 ContentDecoder by default.

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

Properties

accept-language

If non-None, the value to use for the “Accept-Language” header on Messages sent from this session.

Setting this will disable accept-language-auto.

Readable | Writeable

accept-language-auto

If true, #SoupSession will automatically set the string for the “Accept-Language” header on every Message sent, based on the return value of get_language_names().

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

Readable | Writeable

idle-timeout

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 SessionExt::abort() after setting this if you want to ensure that all future connections will have this timeout value.

Readable | Writeable

local-address

Sets the gio::InetSocketAddress 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.

Readable | Writeable | Construct Only

max-conns

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

Readable | Writeable | Construct Only

max-conns-per-host

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

Readable | Writeable | Construct Only

proxy-resolver

A gio::ProxyResolver to use with this session.

If no proxy resolver is set, then the default proxy resolver will be used. See gio::ProxyResolver::default(). You can set it to None if you don’t want to use proxies, or set it to your own gio::ProxyResolver if you want to control what proxies get used.

Readable | Writeable

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.

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 Gio::UnixSocketAddress can be passed to this function.

Readable | Writeable | Construct Only

timeout

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 SessionExt::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).

Readable | Writeable

tls-database

Sets the gio::TlsDatabase to use for validating SSL/TLS certificates.

If no certificate database is set, then the default database will be used. See Gio::TlsBackend::get_default_database().

Readable | Writeable

tls-interaction

A gio::TlsInteraction object that will be passed on to any Gio::TlsConnections created by the session.

This can be used to provide client-side certificates, for example.

Readable | Writeable

user-agent

User-Agent string.

If non-None, the value to use for the “User-Agent” header on Messages 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.

Readable | Writeable

Signals

request-queued

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 Message signals are emitted as the message is processed. If the message is requeued, it will emit restarted, which will then be followed by other Message 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 Message signals) may be invoked multiple times for a given message.

request-unqueued

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.

Implements

SessionExt, [trait@glib::ObjectExt], SessionExtManual

Implementations

impl Session

pub const NONE: Option<&'static Session> = None

pub fn new() -> Session

Creates a #SoupSession with the default options.

Returns

the new session.

pub fn builder() -> SessionBuilder

Creates a new builder-pattern struct instance to construct Session objects.

This method returns an instance of SessionBuilder which can be used to create Session objects.

Trait Implementations

impl Clone for Session

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Session

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Session

fn default() -> Self

Returns the “default value” for a type.

impl HasParamSpec for Session

type ParamSpec = ParamSpecObject

type SetValue = Session

Preferred value to be used as setter for the associated ParamSpec.

type BuilderFn = fn(_: &str) -> ParamSpecObjectBuilder<'_, Session>

fn param_spec_builder() -> Self::BuilderFn

impl Hash for Session

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Session

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl ParentClassIs for Session

type Parent = Object

impl<OT: ObjectType> PartialEq<OT> for Session

fn eq(&self, other: &OT) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<OT: ObjectType> PartialOrd<OT> for Session

fn partial_cmp(&self, other: &OT) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl StaticType for Session

fn static_type() -> Type

Returns the type identifier of Self.

impl Eq for Session