Session

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

In the past, #SoupSession was an abstract class, and users needed to choose between #SoupSessionAsync (which always uses #GMainLoop-based I/O), or #SoupSessionSync (which always uses blocking I/O and can be used from multiple threads simultaneously). This is no longer necessary; you can (and should) use a plain #SoupSession, which supports both synchronous and asynchronous use. (When using a plain #SoupSession, soup_session_queue_message() behaves like it traditionally did on a #SoupSessionAsync, and soup_session_send_message() behaves like it traditionally did on a #SoupSessionSync.)

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() (or at construct time with the %SOUP_SESSION_ADD_FEATURE_BY_TYPE pseudo-property). 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 and #SoupRequest can be added as features, to add support for additional authentication and URI types.

All #SoupSessions are created with a #SoupAuthManager, and support for %SOUP_TYPE_AUTH_BASIC and %SOUP_TYPE_AUTH_DIGEST. For #SoupRequest types, #SoupRequestHTTP, #SoupRequestFile, and #SoupRequestData are supported. Additionally, sessions using the plain #SoupSession class (rather than one of its deprecated subtypes) have a #SoupContentDecoder by default.

class Session : ObjectG {

protected

SoupSession* soupSession;

SoupSession* getSessionStruct(bool transferOwnership);

void* getStruct();

this(SoupSession* soupSession, bool ownedRef);

static GType getType();

this();

void abort();

void addFeature(SessionFeatureIF feature);

void addFeatureByType(GType featureType);

void cancelMessage(Message msg, uint statusCode);

void connectAsync(URI uri, Cancellable cancellable, SoupSessionConnectProgressCallback progressCallback, GAsyncReadyCallback callback, void* userData);

IOStream connectFinish(AsyncResultIF result);

MainContext getAsyncContext();

SessionFeatureIF getFeature(GType featureType);

SessionFeatureIF getFeatureForMessage(GType featureType, Message msg);

ListSG getFeatures(GType featureType);

bool hasFeature(GType featureType);

void pauseMessage(Message msg);

void prefetchDns(string hostname, Cancellable cancellable, SoupAddressCallback callback, void* userData);

void prepareForUri(URI uri);

void queueMessage(Message msg, SoupSessionCallback callback, void* userData);

bool redirectMessage(Message msg);

void removeFeature(SessionFeatureIF feature);

void removeFeatureByType(GType featureType);

Request request(string uriString);

RequestHTTP requestHttp(string method, string uriString);

RequestHTTP requestHttpUri(string method, URI uri);

Request requestUri(URI uri);

void requeueMessage(Message msg);

InputStream send(Message msg, Cancellable cancellable);

void sendAsync(Message msg, Cancellable cancellable, GAsyncReadyCallback callback, void* userData);

InputStream sendFinish(AsyncResultIF result);

uint sendMessage(Message msg);

IOStream stealConnection(Message msg);

void unpauseMessage(Message msg);

void websocketConnectAsync(Message msg, string origin, string[] protocols, Cancellable cancellable, GAsyncReadyCallback callback, void* userData);

WebsocketConnection websocketConnectFinish(AsyncResultIF result);

bool wouldRedirect(Message msg);

gulong addOnAuthenticate(void delegate(Message, Auth, bool, Session) dlg, ConnectFlags connectFlags);

gulong addOnConnectionCreated(void delegate(ObjectG, Session) dlg, ConnectFlags connectFlags);

gulong addOnRequestQueued(void delegate(Message, Session) dlg, ConnectFlags connectFlags);

gulong addOnRequestStarted(void delegate(Message, Socket, Session) dlg, ConnectFlags connectFlags);

gulong addOnRequestUnqueued(void delegate(Message, Session) dlg, ConnectFlags connectFlags);

gulong addOnTunneling(void delegate(ObjectG, Session) dlg, ConnectFlags connectFlags);

}

Constructors

this this(SoupSession* soupSession, bool ownedRef): Sets our main struct and passes it to the parent class.
this this(): Creates a #SoupSession with the default options.

Members

Functions

abort void abort(): Cancels all pending requests in @session and closes all idle persistent connections.
addFeature void addFeature(SessionFeatureIF feature): Adds @feature's functionality to @session. You can also add a feature to the session at construct time by using the %SOUP_SESSION_ADD_FEATURE property.
addFeatureByType void addFeatureByType(GType featureType): 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.
addOnAuthenticate gulong addOnAuthenticate(void delegate(Message, Auth, bool, Session) dlg, ConnectFlags connectFlags): Emitted when the session requires authentication. If credentials are available call soup_auth_authenticate() on @auth. If these credentials fail, the signal will be emitted again, with @retrying set to %TRUE, which will continue until you return without calling soup_auth_authenticate() on @auth.
addOnConnectionCreated gulong addOnConnectionCreated(void delegate(ObjectG, Session) dlg, ConnectFlags connectFlags): Emitted when a new connection is created. This is an internal signal intended only to be used for debugging purposes, and may go away in the future.
addOnRequestQueued gulong addOnRequestQueued(void delegate(Message, Session) dlg, ConnectFlags connectFlags): Emitted when a request is queued on @session. (Note that "queued" doesn't just mean soup_session_queue_message(); soup_session_send_message() implicitly queues the message as well.)
addOnRequestStarted gulong addOnRequestStarted(void delegate(Message, Socket, Session) dlg, ConnectFlags connectFlags): Emitted just before a request is sent. See #SoupSession::request_queued for a detailed description of the message lifecycle within a session.
addOnRequestUnqueued gulong addOnRequestUnqueued(void delegate(Message, Session) dlg, ConnectFlags connectFlags): Emitted when a request is removed from @session's queue, indicating that @session is done with it. See #SoupSession::request_queued for a detailed description of the message lifecycle within a session.
addOnTunneling gulong addOnTunneling(void delegate(ObjectG, Session) dlg, ConnectFlags connectFlags): Emitted when an SSL tunnel is being created on a proxy connection. This is an internal signal intended only to be used for debugging purposes, and may go away in the future.
cancelMessage void cancelMessage(Message msg, uint statusCode): Causes @session to immediately finish processing @msg (regardless of its current state) with a final status_code of @status_code. You may call this at any time after handing @msg off to @session; if @session has started sending the request but has not yet received the complete response, then it will close the request's connection. Note that with requests that have side effects (eg, <literal>POST</literal>, <literal>PUT</literal>, <literal>DELETE</literal>) 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.
connectAsync void connectAsync(URI uri, Cancellable cancellable, SoupSessionConnectProgressCallback progressCallback, GAsyncReadyCallback callback, void* userData): Start a connection to @uri. The operation can be monitored by providing a @progress_callback and finishes when the connection is done or an error ocurred.
connectFinish IOStream connectFinish(AsyncResultIF result): Gets the #GIOStream created for the connection to communicate with the server.
getAsyncContext MainContext getAsyncContext(): Gets @session's #SoupSession:async-context. This does not add a ref to the context, so you will need to ref it yourself if you want it to outlive its session.
getFeature SessionFeatureIF getFeature(GType featureType): Gets the first feature in @session of type @feature_type. For features where there may be more than one feature of a given type, use soup_session_get_features().
getFeatureForMessage SessionFeatureIF getFeatureForMessage(GType featureType, Message msg): Gets the first feature in @session of type @feature_type, provided that it is not disabled for @msg. As with soup_session_get_feature(), this should only be used for features where @feature_type is only expected to match a single feature. In particular, if there are two matching features, and the first is disabled on @msg, and the second is not, then this will return %NULL, not the second feature.
getFeatures ListSG getFeatures(GType featureType): Generates a list of @session's features of type @feature_type. (If you want to see all features, you can pass %SOUP_TYPE_SESSION_FEATURE for @feature_type.)
getSessionStruct SoupSession* getSessionStruct(bool transferOwnership): Get the main Gtk struct
getStruct void* getStruct(): the main Gtk struct as a void*
hasFeature bool hasFeature(GType featureType): 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 or #SoupRequest).
pauseMessage void pauseMessage(Message msg): Pauses HTTP I/O on @msg. Call soup_session_unpause_message() to resume I/O.
prefetchDns void prefetchDns(string hostname, Cancellable cancellable, SoupAddressCallback callback, void* userData): Tells @session 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.
prepareForUri void prepareForUri(URI uri): Tells @session that @uri may be requested shortly, and so the session can try to prepare (resolving the domain name, obtaining proxy address, etc.) in order to work more quickly once the URI is actually requested.
queueMessage void queueMessage(Message msg, SoupSessionCallback callback, void* userData): Queues the message @msg for asynchronously sending the request and receiving a response in the current thread-default #GMainContext. If @msg has been processed before, any resources related to the time it was last sent are freed.
redirectMessage bool redirectMessage(Message msg): Updates @msg's URI according to its status code and "Location" header, and requeues it on @session. Use this when you have set %SOUP_MESSAGE_NO_REDIRECT on a message, but have decided to allow a particular redirection to occur, or if you want to allow a redirection that #SoupSession will not perform automatically (eg, redirecting a non-safe method such as DELETE).
removeFeature void removeFeature(SessionFeatureIF feature): Removes @feature's functionality from @session.
removeFeatureByType void removeFeatureByType(GType featureType): 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 %SOUP_SESSION_REMOVE_FEATURE_BY_TYPE property.
request Request request(string uriString): Creates a #SoupRequest for retrieving @uri_string.
requestHttp RequestHTTP requestHttp(string method, string uriString): Creates a #SoupRequest for retrieving @uri_string, which must be an "http" or "https" URI (or another protocol listed in @session's #SoupSession:http-aliases or #SoupSession:https-aliases).
requestHttpUri RequestHTTP requestHttpUri(string method, URI uri): Creates a #SoupRequest for retrieving @uri, which must be an "http" or "https" URI (or another protocol listed in @session's #SoupSession:http-aliases or #SoupSession:https-aliases).
requestUri Request requestUri(URI uri): Creates a #SoupRequest for retrieving @uri.
requeueMessage void requeueMessage(Message msg): This causes @msg to be placed back on the queue to be attempted again.
send InputStream send(Message msg, Cancellable cancellable): 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.)
sendAsync void sendAsync(Message msg, Cancellable cancellable, GAsyncReadyCallback callback, void* userData): 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.
sendFinish InputStream sendFinish(AsyncResultIF result): 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.
sendMessage uint sendMessage(Message msg): Synchronously send @msg. This call will not return until the transfer is finished successfully or there is an unrecoverable error.
stealConnection IOStream stealConnection(Message msg): "Steals" the HTTP connection associated with @msg from @session. This happens immediately, regardless of the current state of the connection, and @msg's callback will not be called. You can steal the connection from a #SoupMessage signal handler if you need to wait for part or all of the response to be received first.
unpauseMessage void unpauseMessage(Message msg): Resumes HTTP I/O on @msg. Use this to resume after calling soup_session_pause_message().
websocketConnectAsync void websocketConnectAsync(Message msg, string origin, string[] protocols, Cancellable cancellable, GAsyncReadyCallback callback, void* userData): Asynchronously creates a #SoupWebsocketConnection to communicate with a remote server.
websocketConnectFinish WebsocketConnection websocketConnectFinish(AsyncResultIF result): 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.
wouldRedirect bool wouldRedirect(Message msg): Checks if @msg contains a response that would cause @session 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).

Static functions

getType GType getType()

Variables

soupSession SoupSession* soupSession;: the main Gtk struct