SoupSession

## SoupSession SoupSession — Soup session state object |

## Synopsis

    #include <libsoup/soup.h>

                        SoupSession;

    void                (*SoupSessionCallback)              (SoupSession *session,
                                                             SoupMessage *msg,
                                                             gpointer user_data);
    void                soup_session_queue_message          (SoupSession *session,
                                                             SoupMessage *msg,
                                                             SoupSessionCallback callback,
                                                             gpointer user_data);
    void                soup_session_requeue_message        (SoupSession *session,
                                                             SoupMessage *msg);
    guint               soup_session_send_message           (SoupSession *session,
                                                             SoupMessage *msg);
    void                soup_session_cancel_message         (SoupSession *session,
                                                             SoupMessage *msg,
                                                             guint status_code);
    void                soup_session_abort                  (SoupSession *session);

    void                soup_session_pause_message          (SoupSession *session,
                                                             SoupMessage *msg);
    void                soup_session_unpause_message        (SoupSession *session,
                                                             SoupMessage *msg);

    GMainContext *      soup_session_get_async_context      (SoupSession *session);

    void                soup_session_add_feature            (SoupSession *session,
                                                             SoupSessionFeature *feature);
    void                soup_session_add_feature_by_type    (SoupSession *session,
                                                             GType feature_type);
    void                soup_session_remove_feature         (SoupSession *session,
                                                             SoupSessionFeature *feature);
    void                soup_session_remove_feature_by_type (SoupSession *session,
                                                             GType feature_type);
    GSList *            soup_session_get_features           (SoupSession *session,
                                                             GType feature_type);
    SoupSessionFeature * soup_session_get_feature           (SoupSession *session,
                                                             GType feature_type);
    SoupSessionFeature * soup_session_get_feature_for_message
                                                            (SoupSession *session,
                                                             GType feature_type,
                                                             SoupMessage *msg);

    #define             SOUP_SESSION_PROXY_URI
    #define             SOUP_SESSION_MAX_CONNS
    #define             SOUP_SESSION_MAX_CONNS_PER_HOST
    #define             SOUP_SESSION_USE_NTLM
    #define             SOUP_SESSION_SSL_CA_FILE
    #define             SOUP_SESSION_ASYNC_CONTEXT
    #define             SOUP_SESSION_TIMEOUT
    #define             SOUP_SESSION_IDLE_TIMEOUT
    #define             SOUP_SESSION_USER_AGENT
    #define             SOUP_SESSION_ADD_FEATURE
    #define             SOUP_SESSION_ADD_FEATURE_BY_TYPE
    #define             SOUP_SESSION_REMOVE_FEATURE_BY_TYPE

## Object Hierarchy

      GObject
       +----SoupSession
             +----SoupSessionAsync
             +----SoupSessionSync

## Properties

      "accept-language"          gchar*                : Read / Write
      "accept-language-auto"     gboolean              : Read / Write
      "add-feature"              SoupSessionFeature*   : Read / Write
      "add-feature-by-type"      GType*                : Read / Write
      "async-context"            gpointer              : Read / Write / Construct Only
      "idle-timeout"             guint                 : Read / Write
      "max-conns"                gint                  : Read / Write
      "max-conns-per-host"       gint                  : Read / Write
      "proxy-uri"                SoupURI*              : Read / Write
      "remove-feature-by-type"   GType*                : Read / Write
      "ssl-ca-file"              gchar*                : Read / Write
      "ssl-strict"               gboolean              : Read / Write
      "timeout"                  guint                 : Read / Write
      "use-ntlm"                 gboolean              : Read / Write
      "user-agent"               gchar*                : Read / Write

## Signals

      "authenticate"                                   : Run First
      "connection-created"                             : Run First
      "request-queued"                                 : Run First
      "request-started"                                : Run First
      "request-unqueued"                               : Run First
      "tunneling"                                      : Run First

## Description

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.

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

SoupSession itself is an abstract class, with two subclasses. If you are using the glib main loop, you will generally want to use SoupSessionAsync, which uses non-blocking I/O and callbacks. On the other hand, if your application is threaded and you want to do synchronous I/O in a separate thread from the UI, use SoupSessionSync.

## Details

### SoupSession

    typedef struct _SoupSession SoupSession;

### SoupSessionCallback ()

    void                (*SoupSessionCallback)              (SoupSession *session,
                                                             SoupMessage *msg,
                                                             gpointer user_data);

Prototype for the callback passed to `soup_session_queue_message()`, qv.

`session` : | the session
`msg` : | the message that has finished
`user_data` : | the data passed to soup_session_queue_message

### soup_session_queue_message ()

    void                soup_session_queue_message          (SoupSession *session,
                                                             SoupMessage *msg,
                                                             SoupSessionCallback callback,
                                                             gpointer user_data);

Queues the message `msg` for sending. All messages are processed while the glib main loop runs. If `msg` has been processed before, any resources related to the time it was last sent are freed.

Upon message completion, the callback specified in `callback` will be invoked (in the thread associated with `session`'s async context). If after returning from this callback the message has not been requeued, `msg` will be unreffed.

`session` : | a SoupSession
`msg` : | the message to queue. [transfer full]
`callback` : | a SoupSessionCallback which will be called after the message completes or when an unrecoverable error occurs. [allow-none][scope async]
`user_data` : | a pointer passed to `callback`. [allow-none]

### soup_session_requeue_message ()

    void                soup_session_requeue_message        (SoupSession *session,
                                                             SoupMessage *msg);

This causes `msg` to be placed back on the queue to be attempted again.

`session` : | a SoupSession
`msg` : | the message to requeue

### soup_session_send_message ()

    guint               soup_session_send_message           (SoupSession *session,
                                                             SoupMessage *msg);

Synchronously send `msg`. This call will not return until the transfer is finished successfully or there is an unrecoverable error.

`msg` is not freed upon return.

`session` : | a SoupSession
`msg` : | the message to send
Returns : | the HTTP status code of the response

### soup_session_cancel_message ()

    void                soup_session_cancel_message         (SoupSession *session,
                                                             SoupMessage *msg,
                                                             guint status_code);

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 non-idempotent requests (eg, `POST`, `PUT`, `DELETE`) 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.

If the message is cancelled while its response body is being read, then the response body in `msg` will be left partially-filled-in. The response headers, on the other hand, will always be either empty or complete.

For messages queued with `soup_session_queue_message()` (and cancelled from the same thread), the callback will be invoked before `soup_session_cancel_message()` returns.

`session` : | a SoupSession
`msg` : | the message to cancel
`status_code` : | status code to set on `msg` (generally `SOUP_STATUS_CANCELLED`)

### soup_session_abort ()

    void                soup_session_abort                  (SoupSession *session);

Cancels all pending requests in `session`.

`session` : | the session

### soup_session_pause_message ()

    void                soup_session_pause_message          (SoupSession *session,
                                                             SoupMessage *msg);

Pauses HTTP I/O on `msg`. Call `soup_session_unpause_message()` to resume I/O.

`session` : | a SoupSession
`msg` : | a SoupMessage currently running on `session`

### soup_session_unpause_message ()

    void                soup_session_unpause_message        (SoupSession *session,
                                                             SoupMessage *msg);

Resumes HTTP I/O on `msg`. Use this to resume after calling `soup_session_pause_message()`.

If `msg` is being sent via blocking I/O, this will resume reading or writing immediately. If `msg` is using non-blocking I/O, then reading or writing won't resume until you return to the main loop.

`session` : | a SoupSession
`msg` : | a SoupMessage currently running on `session`

### soup_session_get_async_context ()

    GMainContext *      soup_session_get_async_context      (SoupSession *session);

Gets `session`'s 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.

`session` : | a SoupSession
Returns : | `session`'s GMainContext, which may be `NULL`. [transfer none]

### soup_session_add_feature ()

    void                soup_session_add_feature            (SoupSession *session,
                                                             SoupSessionFeature *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.

`session` : | a SoupSession
`feature` : | an object that implements SoupSessionFeature

Since 2.24

### soup_session_add_feature_by_type ()

    void                soup_session_add_feature_by_type    (SoupSession *session,
                                                             GType feature_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.

If `feature_type` is not a SoupSessionFeature type, this gives each existing feature on `session` the chance to accept `feature_type` as a "subfeature". This can be used to add new SoupAuth types, for instance.

You can also add a feature to the session at construct time by using the `SOUP_SESSION_ADD_FEATURE_BY_TYPE` property.

`session` : | a SoupSession
`feature_type` : | a GType

Since 2.24

### soup_session_remove_feature ()

    void                soup_session_remove_feature         (SoupSession *session,
                                                             SoupSessionFeature *feature);

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

`session` : | a SoupSession
`feature` : | a feature that has previously been added to `session`

Since 2.24

### soup_session_remove_feature_by_type ()

    void                soup_session_remove_feature_by_type (SoupSession *session,
                                                             GType feature_type);

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.

`session` : | a SoupSession
`feature_type` : | a GType

Since 2.24

### soup_session_get_features ()

    GSList *            soup_session_get_features           (SoupSession *session,
                                                             GType feature_type);

Generates a list of `session`'s features of type `feature_type`. (If you want to see all features, you can pass `G_TYPE_SESSION_FEATURE` for `feature_type`.)

`session` : | a SoupSession
`feature_type` : | the GType of the class of features to get
Returns : | a list of features. You must free the list, but not its contents. [transfer container]

Since 2.26

### soup_session_get_feature ()

    SoupSessionFeature * soup_session_get_feature           (SoupSession *session,
                                                             GType feature_type);

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

`session` : | a SoupSession
`feature_type` : | the GType of the feature to get
Returns : | a SoupSessionFeature, or `NULL`. The feature is owned by `session`. [transfer none]

Since 2.26

### soup_session_get_feature_for_message ()

    SoupSessionFeature * soup_session_get_feature_for_message
                                                            (SoupSession *session,
                                                             GType feature_type,
                                                             SoupMessage *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.

`session` : | a SoupSession
`feature_type` : | the GType of the feature to get
`msg` : | a SoupMessage
Returns : | a SoupSessionFeature, or `NULL`. The feature is owned by `session`. [transfer none]

Since 2.28

### SOUP_SESSION_PROXY_URI

    #define SOUP_SESSION_PROXY_URI              "proxy-uri"

Alias for the "proxy-uri" property. (The HTTP proxy to use for this session.)

### SOUP_SESSION_MAX_CONNS

    #define SOUP_SESSION_MAX_CONNS              "max-conns"

Alias for the "max-conns" property. (The maximum number of connections that the session can open at once.)

### SOUP_SESSION_MAX_CONNS_PER_HOST

    #define SOUP_SESSION_MAX_CONNS_PER_HOST     "max-conns-per-host"

Alias for the "max-conns-per-host" property. (The maximum number of connections that the session can open at once to a given host.)

### SOUP_SESSION_USE_NTLM

    #define SOUP_SESSION_USE_NTLM               "use-ntlm"

Alias for the "use-ntlm" property. (Whether or not to use NTLM authentication.)

### SOUP_SESSION_SSL_CA_FILE

    #define SOUP_SESSION_SSL_CA_FILE            "ssl-ca-file"

Alias for the "ssl-ca-file" property. (File containing SSL CA certificates.)

### SOUP_SESSION_ASYNC_CONTEXT

    #define SOUP_SESSION_ASYNC_CONTEXT          "async-context"

Alias for the "async-context" property. (The session's GMainContext.)

### SOUP_SESSION_TIMEOUT

    #define SOUP_SESSION_TIMEOUT                "timeout"

Alias for the "timeout" property. (The timeout in seconds for blocking socket I/O operations.)

### SOUP_SESSION_IDLE_TIMEOUT

    #define SOUP_SESSION_IDLE_TIMEOUT           "idle-timeout"

Alias for the "idle-timeout" property. (The idle connection lifetime.)

Since 2.4.1

### SOUP_SESSION_USER_AGENT

    #define SOUP_SESSION_USER_AGENT             "user-agent"

Alias for the "user-agent" property, qv.

### SOUP_SESSION_ADD_FEATURE

    #define SOUP_SESSION_ADD_FEATURE            "add-feature"

Alias for the "add-feature" property. (Shortcut for calling `soup_session_add_feature()`.

Since 2.24

### SOUP_SESSION_ADD_FEATURE_BY_TYPE

    #define SOUP_SESSION_ADD_FEATURE_BY_TYPE    "add-feature-by-type"

Alias for the "add-feature-by-type" property. (Shortcut for calling `soup_session_add_feature_by_type()`.

Since 2.24

### SOUP_SESSION_REMOVE_FEATURE_BY_TYPE

    #define SOUP_SESSION_REMOVE_FEATURE_BY_TYPE "remove-feature-by-type"

Alias for the "remove-feature-by-type" property. (Shortcut for calling `soup_session_remove_feature_by_type()`.

Since 2.24

## Property Details

### The `"accept-language"` property

      "accept-language"          gchar*                : Read / Write

If non-`NULL`, the value to use for the "Accept-Language" header on SoupMessages sent from this session.

Setting this will disable "accept-language-auto".

Default value: NULL

Since 2.30

### The `"accept-language-auto"` property

      "accept-language-auto"     gboolean              : Read / Write

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

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

Default value: FALSE

Since 2.30

### The `"add-feature"` property

      "add-feature"              SoupSessionFeature*   : Read / Write

Add a feature object to the session. (Shortcut for calling `soup_session_add_feature()`.)

Since 2.24

### The `"add-feature-by-type"` property

      "add-feature-by-type"      GType*                : Read / Write

Add a feature object of the given type to the session. (Shortcut for calling `soup_session_add_feature_by_type()`.)

Allowed values: SoupSessionFeature

Since 2.24

### The `"async-context"` property

      "async-context"            gpointer              : Read / Write / Construct Only

The GMainContext to dispatch async I/O in.

### The `"idle-timeout"` property

      "idle-timeout"             guint                 : Read / Write

Connection lifetime when idle

Default value: 0

Since 2.4.1

### The `"max-conns"` property

      "max-conns"                gint                  : Read / Write

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

Allowed values: >= 1

Default value: 10

### The `"max-conns-per-host"` property

      "max-conns-per-host"       gint                  : Read / Write

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

Allowed values: >= 1

Default value: 2

### The `"proxy-uri"` property

      "proxy-uri"                SoupURI*              : Read / Write

The HTTP Proxy to use for this session.

### The `"remove-feature-by-type"` property

      "remove-feature-by-type"   GType*                : Read / Write

Remove feature objects from the session. (Shortcut for calling `soup_session_remove_feature_by_type()`.)

Allowed values: SoupSessionFeature

Since 2.24

### The `"ssl-ca-file"` property

      "ssl-ca-file"              gchar*                : Read / Write

File containing SSL CA certificates.

Default value: NULL

### The `"ssl-strict"` property

      "ssl-strict"               gboolean              : Read / Write

Whether certificate errors should be considered a connection error.

Default value: TRUE

### The `"timeout"` property

      "timeout"                  guint                 : Read / Write

Value in seconds to timeout a blocking I/O.

Default value: 0

### The `"use-ntlm"` property

      "use-ntlm"                 gboolean              : Read / Write

### Warning

`SoupSession:use-ntlm` is deprecated and should not be used in newly-written code. use `soup_session_add_feature_by_type()` with SOUP_TYPE_AUTH_NTLM.

Whether or not to use NTLM authentication.

Default value: FALSE

### The `"user-agent"` property

      "user-agent"               gchar*                : Read / Write

If non-`NULL`, the value to use for the "User-Agent" header on SoupMessages 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.

Default value: NULL

## Signal Details

### The `"authenticate"` signal

    void                user_function                      (SoupSession *session,
                                                            SoupMessage *msg,
                                                            SoupAuth    *auth,
                                                            gboolean     retrying,
                                                            gpointer     user_data)      : Run First

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

Note that this may be emitted before `msg`'s body has been fully read.

If you call `soup_session_pause_message()` on `msg` before returning, then you can authenticate `auth` asynchronously (as long as you `g_object_ref()` it to make sure it doesn't get destroyed), and then unpause `msg` when you are ready for it to continue.

`session` : | the session
`msg` : | the SoupMessage being sent
`auth` : | the SoupAuth to authenticate
`retrying` : | `TRUE` if this is the second (or later) attempt
`user_data` : | user data set when the signal handler was connected.

### The `"connection-created"` signal

    void                user_function                      (SoupSession *soupsession,
                                                            GObject     *arg1,
                                                            gpointer     user_data)        : Run First

`soupsession` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The `"request-queued"` signal

    void                user_function                      (SoupSession *session,
                                                            SoupMessage *msg,
                                                            gpointer     user_data)      : Run First

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

When sending a request, first "request_queued" is emitted, indicating that the session has become aware of the request.

Once a connection is available to send the request on, the session emits "request_started". Then, various SoupMessage signals are emitted as the message is processed. If the message is requeued, it will emit "restarted", which will then be followed by another "request_started" and another set of SoupMessage 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 (or equivalently, from the `soup_session_queue_message()` callback). In that case, the process will loop back to "request_started".

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 "request_started" and "finished" (and all of the other SoupMessage signals) may be invoked multiple times for a given message.

`session` : | the session
`msg` : | the request that was queued
`user_data` : | user data set when the signal handler was connected.

Since 2.4.1

### The `"request-started"` signal

    void                user_function                      (SoupSession *session,
                                                            SoupMessage *msg,
                                                            SoupSocket  *socket,
                                                            gpointer     user_data)      : Run First

Emitted just before a request is sent. See "request_queued" for a detailed description of the message lifecycle within a session.

`session` : | the session
`msg` : | the request being sent
`socket` : | the socket the request is being sent on
`user_data` : | user data set when the signal handler was connected.

### The `"request-unqueued"` signal

    void                user_function                      (SoupSession *session,
                                                            SoupMessage *msg,
                                                            gpointer     user_data)      : Run First

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.

`session` : | the session
`msg` : | the request that was unqueued
`user_data` : | user data set when the signal handler was connected.

Since 2.4.1

### The `"tunneling"` signal

    void                user_function                      (SoupSession *soupsession,
                                                            GObject     *arg1,
                                                            gpointer     user_data)        : Run First

`soupsession` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.