SoupSession: libsoup Reference Manual

## SoupSession SoupSession — Soup session state object |

## Functions

SoupSession * | soup_session_new ()
SoupSession * | soup_session_new_with_options ()
SoupRequest * | soup_session_request ()
SoupRequest * | soup_session_request_uri ()
SoupRequestHTTP * | soup_session_request_http ()
SoupRequestHTTP * | soup_session_request_http_uri ()
void | (*SoupSessionCallback) ()
void | soup_session_queue_message ()
void | soup_session_requeue_message ()
guint | soup_session_send_message ()
void | soup_session_cancel_message ()
GInputStream * | soup_session_send ()
void | soup_session_send_async ()
GInputStream * | soup_session_send_finish ()
void | soup_session_websocket_connect_async ()
SoupWebsocketConnection * | soup_session_websocket_connect_finish ()
void | soup_session_prefetch_dns ()
void | soup_session_abort ()
gboolean | soup_session_would_redirect ()
gboolean | soup_session_redirect_message ()
void | soup_session_pause_message ()
void | soup_session_unpause_message ()
GMainContext * | soup_session_get_async_context ()
void | soup_session_add_feature ()
void | soup_session_add_feature_by_type ()
void | soup_session_remove_feature ()
void | soup_session_remove_feature_by_type ()
GSList * | soup_session_get_features ()
SoupSessionFeature * | soup_session_get_feature ()
SoupSessionFeature * | soup_session_get_feature_for_message ()
gboolean | soup_session_has_feature ()
GIOStream * | soup_session_steal_connection ()
void | (*SoupSessionConnectProgressCallback) ()
void | soup_session_connect_async ()
GIOStream * | soup_session_connect_finish ()

## Properties

char * | accept-language | Read / Write
gboolean | accept-language-auto | Read / Write
SoupSessionFeature * | add-feature | Read / Write
GType * | add-feature-by-type | Read / Write
gpointer | async-context | Read / Write / Construct Only
GStrv | http-aliases | Read / Write
GStrv | https-aliases | Read / Write
guint | idle-timeout | Read / Write
SoupAddress * | local-address | Read / Write / Construct Only
int | max-conns | Read / Write
int | max-conns-per-host | Read / Write
GProxyResolver * | proxy-resolver | Read / Write
SoupURI * | proxy-uri | Read / Write
GType * | remove-feature-by-type | Read / Write
char * | ssl-ca-file | Read / Write
gboolean | ssl-strict | Read / Write
gboolean | ssl-use-system-ca-file | Read / Write
guint | timeout | Read / Write
GTlsDatabase * | tls-database | Read / Write
GTlsInteraction * | tls-interaction | Read / Write
gboolean | use-ntlm | Read / Write
gboolean | use-thread-context | Read / Write
char * | user-agent | Read / Write

## Signals

void | authenticate | Run First
void | connection-created | Run First
void | request-queued | Run First
void | request-started | Run First
void | request-unqueued | Run First
void | tunneling | Run First

## Types and Values

| SoupSession
enum | SoupRequestError
#define | SOUP_REQUEST_ERROR
#define | SOUP_SESSION_PROXY_URI
#define | SOUP_SESSION_PROXY_RESOLVER
#define | SOUP_SESSION_MAX_CONNS
#define | SOUP_SESSION_MAX_CONNS_PER_HOST
#define | SOUP_SESSION_TLS_DATABASE
#define | SOUP_SESSION_SSL_USE_SYSTEM_CA_FILE
#define | SOUP_SESSION_SSL_CA_FILE
#define | SOUP_SESSION_SSL_STRICT
#define | SOUP_SESSION_TLS_INTERACTION
#define | SOUP_SESSION_ASYNC_CONTEXT
#define | SOUP_SESSION_USE_THREAD_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
#define | SOUP_SESSION_ACCEPT_LANGUAGE
#define | SOUP_SESSION_ACCEPT_LANGUAGE_AUTO
#define | SOUP_SESSION_HTTP_ALIASES
#define | SOUP_SESSION_HTTPS_ALIASES
#define | SOUP_SESSION_LOCAL_ADDRESS

## Object Hierarchy

        GObject
        ╰── SoupSession
            ├── SoupSessionAsync
            ╰── SoupSessionSync

## Includes

    #include <libsoup/soup.h>

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

## Functions

### soup_session_new ()

    SoupSession *
    soup_session_new (void);

Creates a SoupSession with the default options.

#### Returns

the new session.

Since: 2.42

### soup_session_new_with_options ()

    SoupSession *
    soup_session_new_with_options (const char *optname1,
                                   ...);

Creates a SoupSession with the specified options.

#### Parameters

optname1 | name of first property to set |
... | value of `optname1` , followed by additional property/value pairs |

#### Returns

the new session.

Since: 2.42

### soup_session_request ()

    SoupRequest *
    soup_session_request (SoupSession *session,
                          const char *uri_string,
                          GError **error);

Creates a SoupRequest for retrieving `uri_string` .

#### Parameters

session | a SoupSession |
uri_string | a URI, in string form |
error | return location for a GError, or `NULL` |

#### Returns

a new SoupRequest, or `NULL` on error.

[transfer full]

Since: 2.42

### soup_session_request_uri ()

    SoupRequest *
    soup_session_request_uri (SoupSession *session,
                              SoupURI *uri,
                              GError **error);

Creates a SoupRequest for retrieving `uri` .

#### Parameters

session | a SoupSession |
uri | a SoupURI representing the URI to retrieve |
error | return location for a GError, or `NULL` |

#### Returns

a new SoupRequest, or `NULL` on error.

[transfer full]

Since: 2.42

### soup_session_request_http ()

    SoupRequestHTTP *
    soup_session_request_http (SoupSession *session,
                               const char *method,
                               const char *uri_string,
                               GError **error);

Creates a SoupRequest for retrieving `uri_string` , which must be an "http" or "https" URI (or another protocol listed in `session` 's “http-aliases” or “https-aliases”).

#### Parameters

session | a SoupSession |
method | an HTTP method |
uri_string | a URI, in string form |
error | return location for a GError, or `NULL` |

#### Returns

a new SoupRequestHTTP, or `NULL` on error.

[transfer full]

Since: 2.42

### soup_session_request_http_uri ()

    SoupRequestHTTP *
    soup_session_request_http_uri (SoupSession *session,
                                   const char *method,
                                   SoupURI *uri,
                                   GError **error);

Creates a SoupRequest for retrieving `uri` , which must be an "http" or "https" URI (or another protocol listed in `session` 's “http-aliases” or “https-aliases”).

#### Parameters

session | a SoupSession |
method | an HTTP method |
uri | a SoupURI representing the URI to retrieve |
error | return location for a GError, or `NULL` |

#### Returns

a new SoupRequestHTTP, or `NULL` on error.

[transfer full]

Since: 2.42

### SoupSessionCallback ()

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

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

#### Parameters

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

Upon message completion, the callback specified in `callback` will be invoked. If after returning from this callback the message has not been requeued, `msg` will be unreffed.

(The behavior above applies to a plain SoupSession; if you are using SoupSessionAsync or SoupSessionSync, then the GMainContext that is used depends on the settings of “async-context” and “use-thread-context”, and for SoupSessionSync, the message will actually be sent and processed in another thread, with only the final callback occurring in the indicated GMainContext.)

Contrast this method with `soup_session_send_async()`, which also asynchronously sends a message, but returns before reading the response body, and allows you to read the response via a GInputStream.

#### Parameters

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.

#### Parameters

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.

Unlike with `soup_session_queue_message()`, `msg` is not freed upon return.

(Note that if you call this method on a SoupSessionAsync, it will still use asynchronous I/O internally, running the glib main loop to process the message, which may also cause other events to be processed.)

Contrast this method with `soup_session_send()`, which also synchronously sends a message, but returns before reading the response body, and allows you to read the response via a GInputStream.

#### Parameters

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 requests that have side effects (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.

Beware that with the deprecated SoupSessionAsync, messages queued with `soup_session_queue_message()` will have their callbacks invoked before `soup_session_cancel_message()` returns. The plain SoupSession does not have this behavior; cancelling an asynchronous message will merely queue its callback to be run after returning to the main loop.

#### Parameters

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

### soup_session_send ()

    GInputStream *
    soup_session_send (SoupSession *session,
                       SoupMessage *msg,
                       GCancellable *cancellable,
                       GError **error);

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

If non-`NULL`, `cancellable` can be used to cancel the request; `soup_session_send()` will return a `G_IO_ERROR_CANCELLED` error. Note that with requests that have side effects (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 `msg` is requeued due to a redirect or authentication, the initial (3xx/401/407) response body will be suppressed, and `soup_session_send()` will only return once a final response has been received.

Contrast this method with `soup_session_send_message()`, which also synchronously sends a SoupMessage, but doesn't return until the response has been completely read.

(Note that this method cannot be called on the deprecated SoupSessionAsync subclass.)

#### Parameters

session | a SoupSession |
msg | a SoupMessage |
cancellable | a GCancellable |
error | return location for a GError, or `NULL` |

#### Returns

a GInputStream for reading the response body, or `NULL` on error.

[transfer full]

Since: 2.42

### soup_session_send_async ()

    void
    soup_session_send_async (SoupSession *session,
                             SoupMessage *msg,
                             GCancellable *cancellable,
                             GAsyncReadyCallback callback,
                             gpointer user_data);

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.

See `soup_session_send()` for more details on the general semantics.

Contrast this method with `soup_session_queue_message()`, which also asynchronously sends a SoupMessage, but doesn't invoke its callback until the response has been completely read.

(Note that this method cannot be called on the deprecated SoupSessionSync subclass, and can only be called on SoupSessionAsync if you have set the “use-thread-context” property.)

#### Parameters

session | a SoupSession |
msg | a SoupMessage |
cancellable | a GCancellable |
callback | the callback to invoke |
user_data | data for `callback` |

Since: 2.42

### soup_session_send_finish ()

    GInputStream *
    soup_session_send_finish (SoupSession *session,
                              GAsyncResult *result,
                              GError **error);

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.

#### Parameters

session | a SoupSession |
result | the GAsyncResult passed to your callback |
error | return location for a GError, or `NULL` |

#### Returns

a GInputStream for reading the response body, or `NULL` on error.

[transfer full]

Since: 2.42

### soup_session_websocket_connect_async ()

    void
    soup_session_websocket_connect_async (SoupSession *session,
                                          SoupMessage *msg,
                                          const char *origin,
                                          char **protocols,
                                          GCancellable *cancellable,
                                          GAsyncReadyCallback callback,
                                          gpointer user_data);

Asynchronously creates a SoupWebsocketConnection to communicate with a remote server.

All necessary WebSocket-related headers will be added to `msg` , and it will then be sent and asynchronously processed normally (including handling of redirection and HTTP authentication).

If the server returns "101 Switching Protocols", then `msg` 's status code and response headers will be updated, and then the WebSocket handshake will be completed. On success, `soup_session_websocket_connect_finish()` will return a new SoupWebsocketConnection. On failure it will return a GError.

If the server returns a status other than "101 Switching Protocols", then `msg` will contain the complete response headers and body from the server's response, and `soup_session_websocket_connect_finish()` will return `SOUP_WEBSOCKET_ERROR_NOT_WEBSOCKET`.

#### Parameters

session | a SoupSession |
msg | SoupMessage indicating the WebSocket server to connect to |
origin | origin of the connection. | [allow-none]
protocols | a `NULL`-terminated array of protocols supported. | [allow-none][array zero-terminated=1]
cancellable | a GCancellable |
callback | the callback to invoke |
user_data | data for `callback` |

Since: 2.50

### soup_session_websocket_connect_finish ()

    SoupWebsocketConnection *
    soup_session_websocket_connect_finish (SoupSession *session,
                                           GAsyncResult *result,
                                           GError **error);

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.

#### Parameters

session | a SoupSession |
result | the GAsyncResult passed to your callback |
error | return location for a GError, or `NULL` |

#### Returns

a new SoupWebsocketConnection, or `NULL` on error.

[transfer full]

Since: 2.50

### soup_session_prefetch_dns ()

    void
    soup_session_prefetch_dns (SoupSession *session,
                               const char *hostname,
                               GCancellable *cancellable,
                               SoupAddressCallback callback,
                               gpointer user_data);

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.

If `cancellable` is non-`NULL`, it can be used to cancel the resolution. `callback` will still be invoked in this case, with a status of `SOUP_STATUS_CANCELLED`.

#### Parameters

session | a SoupSession |
hostname | a hostname to be resolved |
cancellable | a GCancellable object, or `NULL`. | [allow-none]
callback | callback to call with the result, or `NULL`. | [scope async][allow-none]
user_data | data for `callback` |

Since: 2.38

### soup_session_abort ()

    void
    soup_session_abort (SoupSession *session);

Cancels all pending requests in `session` and closes all idle persistent connections.

The message cancellation has the same semantics as with `soup_session_cancel_message()`; asynchronous requests on a SoupSessionAsync will have their callback called before `soup_session_abort()` returns. Requests on a plain SoupSession will not.

#### Parameters

session | the session |

### soup_session_would_redirect ()

    gboolean
    soup_session_would_redirect (SoupSession *session,
                                 SoupMessage *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).

#### Parameters

session | a SoupSession |
msg | a SoupMessage that has response headers |

#### Returns

whether `msg` would be redirected

Since: 2.38

### soup_session_redirect_message ()

    gboolean
    soup_session_redirect_message (SoupSession *session,
                                   SoupMessage *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).

If `msg` 's status code indicates that it should be retried as a GET request, then `msg` will be modified accordingly.

If `msg` has already been redirected too many times, this will cause it to fail with `SOUP_STATUS_TOO_MANY_REDIRECTS`.

#### Parameters

session | the session |
msg | a SoupMessage that has received a 3xx response |

#### Returns

`TRUE` if a redirection was applied, `FALSE` if not (eg, because there was no Location header, or it could not be parsed).

Since: 2.38

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

This may only be called for asynchronous messages (those sent on a SoupSessionAsync or using `soup_session_queue_message()`).

#### Parameters

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.

This may only be called for asynchronous messages (those sent on a SoupSessionAsync or using `soup_session_queue_message()`).

#### Parameters

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.

For a modern SoupSession, this will always just return the thread-default GMainContext, and so is not especially useful.

#### Parameters

session | a SoupSession |

#### Returns

`session` 's GMainContext, which may be `NULL`.

[nullable][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.

See the main SoupSession documentation for information on what features are present in sessions by default.

#### Parameters

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

See the main SoupSession documentation for information on what features are present in sessions by default.

#### Parameters

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

#### Parameters

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.

#### Parameters

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 `SOUP_TYPE_SESSION_FEATURE` for `feature_type` .)

#### Parameters

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][element-type Soup.SessionFeature]

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

#### Parameters

session | a SoupSession |
feature_type | the GType of the feature to get |

#### Returns

a SoupSessionFeature, or `NULL`. The feature is owned by `session` .

[nullable][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.

#### Parameters

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

[nullable][transfer none]

Since: 2.28

### soup_session_has_feature ()

    gboolean
    soup_session_has_feature (SoupSession *session,
                              GType feature_type);

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

#### Parameters

session | a SoupSession |
feature_type | the GType of the class of features to check for |

#### Returns

`TRUE` or `FALSE`

Since: 2.42

### soup_session_steal_connection ()

    GIOStream *
    soup_session_steal_connection (SoupSession *session,
                                   SoupMessage *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.

Calling this function may cause `msg` to be freed if you are not holding any other reference to it.

#### Parameters

session | a SoupSession |
msg | the message whose connection is to be stolen |

#### Returns

the GIOStream formerly associated with `msg` (or `NULL` if `msg` was no longer associated with a connection). No guarantees are made about what kind of GIOStream is returned.

[transfer full]

Since: 2.50

### SoupSessionConnectProgressCallback ()

    void
    (*SoupSessionConnectProgressCallback) (SoupSession *session,
                                           GSocketClientEvent event,
                                           GIOStream *connection,
                                           gpointer user_data);

Prototype for the progress callback passed to `soup_session_connect_async()`.

#### Parameters

session | the SoupSession |
event | a GSocketClientEvent |
connection | the current state of the network connection |
user_data | the data passed to `soup_session_connect_async()`. |

Since: 2.62

### soup_session_connect_async ()

    void
    soup_session_connect_async (SoupSession *session,
                                SoupURI *uri,
                                GCancellable *cancellable,
                                SoupSessionConnectProgressCallback progress_callback,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

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.

Call `soup_session_connect_finish()` to get the GIOStream to communicate with the server.

#### Parameters

session | a SoupSession |
uri | a SoupURI to connect to |
cancellable | a GCancellable |
progress_callback | a SoupSessionConnectProgressCallback which will be called for every network event that occurs during the connection. | [allow-none][scope async]
callback | the callback to invoke when the operation finishes. | [allow-none][scope async]
user_data | data for `progress_callback` and `callback` |

Since: 2.62

### soup_session_connect_finish ()

    GIOStream *
    soup_session_connect_finish (SoupSession *session,
                                 GAsyncResult *result,
                                 GError **error);

Gets the GIOStream created for the connection to communicate with the server.

#### Parameters

session | a SoupSession |
result | the GAsyncResult passed to your callback |
error | return location for a GError, or `NULL` |

#### Returns

a new GIOStream, or `NULL` on error.

[transfer full]

Since: 2.62

## Types and Values

### SoupSession

    typedef struct _SoupSession SoupSession;

### enum SoupRequestError

A SoupRequest error.

#### Members

SOUP_REQUEST_ERROR_BAD_URI | the URI could not be parsed |
SOUP_REQUEST_ERROR_UNSUPPORTED_URI_SCHEME | the URI scheme is not supported by this SoupSession |
SOUP_REQUEST_ERROR_PARSING | the server's response could not be parsed |
SOUP_REQUEST_ERROR_ENCODING | the server's response was in an unsupported format |

Since: 2.42

### SOUP_REQUEST_ERROR

    #define SOUP_REQUEST_ERROR soup_request_error_quark ()

A GError domain for SoupRequest-related errors. Used with SoupRequestError.

Since: 2.42

### SOUP_SESSION_PROXY_URI

    #define SOUP_SESSION_PROXY_URI              "proxy-uri"

Alias for the “proxy-uri” property, qv.

### SOUP_SESSION_PROXY_RESOLVER

    #define SOUP_SESSION_PROXY_RESOLVER         "proxy-resolver"

Alias for the “proxy-resolver” property, qv.

### SOUP_SESSION_MAX_CONNS

    #define SOUP_SESSION_MAX_CONNS              "max-conns"

Alias for the “max-conns” property, qv.

### 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, qv.

### SOUP_SESSION_TLS_DATABASE

    #define SOUP_SESSION_TLS_DATABASE           "tls-database"

Alias for the “tls-database” property, qv.

Since: 2.38

### SOUP_SESSION_SSL_USE_SYSTEM_CA_FILE

    #define SOUP_SESSION_SSL_USE_SYSTEM_CA_FILE "ssl-use-system-ca-file"

Alias for the “ssl-use-system-ca-file” property, qv.

Since: 2.38

### SOUP_SESSION_SSL_CA_FILE

    #define SOUP_SESSION_SSL_CA_FILE            "ssl-ca-file"

Alias for the “ssl-ca-file” property, qv.

### SOUP_SESSION_SSL_STRICT

    #define SOUP_SESSION_SSL_STRICT             "ssl-strict"

Alias for the “ssl-strict” property, qv.

Since: 2.30

### SOUP_SESSION_TLS_INTERACTION

    #define SOUP_SESSION_TLS_INTERACTION        "tls-interaction"

Alias for the “tls-interaction” property, qv.

Since: 2.48

### SOUP_SESSION_ASYNC_CONTEXT

    #define SOUP_SESSION_ASYNC_CONTEXT          "async-context"

Alias for the “async-context” property, qv.

### SOUP_SESSION_USE_THREAD_CONTEXT

    #define SOUP_SESSION_USE_THREAD_CONTEXT     "use-thread-context"

Alias for the “use-thread-context” property, qv.

Since: 2.38

### SOUP_SESSION_TIMEOUT

    #define SOUP_SESSION_TIMEOUT                "timeout"

Alias for the “timeout” property, qv.

### SOUP_SESSION_IDLE_TIMEOUT

    #define SOUP_SESSION_IDLE_TIMEOUT           "idle-timeout"

Alias for the “idle-timeout” property, qv.

Since: 2.24

### 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, qv.

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

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

Since: 2.24

### SOUP_SESSION_ACCEPT_LANGUAGE

    #define SOUP_SESSION_ACCEPT_LANGUAGE        "accept-language"

Alias for the “accept-language” property, qv.

Since: 2.30

### SOUP_SESSION_ACCEPT_LANGUAGE_AUTO

    #define SOUP_SESSION_ACCEPT_LANGUAGE_AUTO   "accept-language-auto"

Alias for the “accept-language-auto” property, qv.

Since: 2.30

### SOUP_SESSION_HTTP_ALIASES

    #define SOUP_SESSION_HTTP_ALIASES       "http-aliases"

Alias for the “http-aliases” property, qv.

Since: 2.38

### SOUP_SESSION_HTTPS_ALIASES

    #define SOUP_SESSION_HTTPS_ALIASES      "https-aliases"

Alias for the “https-aliases” property, qv.

Since: 2.38

### SOUP_SESSION_LOCAL_ADDRESS

    #define SOUP_SESSION_LOCAL_ADDRESS          "local-address"

Alias for the “local-address” property, qv.

Since: 2.42

## Property Details

### The `“accept-language”` property

      “accept-language”          char *

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

Owner: SoupSession

Flags: Read / Write

Default value: NULL

Since: 2.30

### The `“accept-language-auto”` property

      “accept-language-auto”     gboolean

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

Owner: SoupSession

Flags: Read / Write

Default value: FALSE

Since: 2.30

### The `“add-feature”` property

      “add-feature”              SoupSessionFeature *

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

[skip]

Owner: SoupSession

Flags: Read / Write

Since: 2.24

### The `“add-feature-by-type”` property

      “add-feature-by-type”      GType *

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

[skip]

Owner: SoupSession

Flags: Read / Write

Allowed values: GObject

Since: 2.24

### The `“async-context”` property

      “async-context”            gpointer

The GMainContext that miscellaneous session-related asynchronous callbacks are invoked on. (Eg, setting “idle-timeout” will add a timeout source on this context.)

For a plain SoupSession, this property is always set to the GMainContext that is the thread-default at the time the session was created, and cannot be overridden. For the deprecated SoupSession subclasses, the default value is `NULL`, meaning to use the global default GMainContext.

If “use-thread-context” is `FALSE`, this context will also be used for asynchronous HTTP I/O.

Owner: SoupSession

Flags: Read / Write / Construct Only

### The `“http-aliases”` property

      “http-aliases”             GStrv

A `NULL`-terminated array of URI schemes that should be considered to be aliases for "http". Eg, if this included `"dav"`, than a URI of `dav://example.com/path` would be treated identically to `http://example.com/path`.

In a plain SoupSession, the default value is `NULL`, meaning that only "http" is recognized as meaning "http". In SoupSessionAsync and SoupSessionSync, for backward compatibility, the default value is an array containing the single element `"*"`, a special value which means that any scheme except "https" is considered to be an alias for "http".

See also “https-aliases”.

Owner: SoupSession

Flags: Read / Write

Since: 2.38

### The `“https-aliases”` property

      “https-aliases”            GStrv

A comma-delimited list of URI schemes that should be considered to be aliases for "https". See “http-aliases” for more information.

The default value is `NULL`, meaning that no URI schemes are considered aliases for "https".

Owner: SoupSession

Flags: Read / Write

Since: 2.38

### The `“idle-timeout”` property

      “idle-timeout”             guint

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

Note that the default value of 60 seconds only applies to plain SoupSessions. If you are using SoupSessionAsync or SoupSessionSync, the default value is 0 (meaning idle connections will never time out).

Owner: SoupSession

Flags: Read / Write

Default value: 60

Since: 2.24

### The `“local-address”` property

      “local-address”            SoupAddress *

Sets the SoupAddress 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.

Owner: SoupSession

Flags: Read / Write / Construct Only

Since: 2.42

### The `“max-conns”` property

      “max-conns”                int

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

Owner: SoupSession

Flags: Read / Write

Allowed values: >= 1

Default value: 10

### The `“max-conns-per-host”` property

      “max-conns-per-host”       int

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

Owner: SoupSession

Flags: Read / Write

Allowed values: >= 1

Default value: 2

### The `“proxy-resolver”` property

      “proxy-resolver”           GProxyResolver *

A GProxyResolver to use with this session. Setting this will clear the “proxy-uri” property, and remove any SoupProxyURIResolver features that have been added to the session.

By default, in a plain SoupSession, this is set to the default GProxyResolver, but you can set it to `NULL` if you don't want to use proxies, or set it to your own GProxyResolver if you want to control what proxies get used.

Owner: SoupSession

Flags: Read / Write

Since: 2.42

### The `“proxy-uri”` property

      “proxy-uri”                SoupURI *

A proxy to use for all http and https requests in this session. Setting this will clear the “proxy-resolver” property, and remove any

SoupProxyURIResolver features that have been

added to the session. Setting this property will also cancel all currently pending messages.

Note that SoupSession will normally handle looking up the user's proxy settings for you; you should only use “proxy-uri” if you need to override the user's normal proxy settings.

Also note that this proxy will be used for all requests; even requests to `localhost`. If you need more control over proxies, you can create a GSimpleProxyResolver and set the “proxy-resolver” property.

`SoupSession:proxy-uri` has been deprecated since version 2.70 and should not be used in newly-written code.

Use SoupSession:proxy-resolver along with GSimpleProxyResolver.

Owner: SoupSession

Flags: Read / Write

### The `“remove-feature-by-type”` property

      “remove-feature-by-type”   GType *

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

[skip]

Owner: SoupSession

Flags: Read / Write

Allowed values: GObject

Since: 2.24

### The `“ssl-ca-file”` property

      “ssl-ca-file”              char *

File containing SSL CA certificates.

If the specified file does not exist or cannot be read, then libsoup will print a warning, and then behave as though it had read in a empty CA file, meaning that all SSL certificates will be considered invalid.

`SoupSession:ssl-ca-file` is deprecated and should not be used in newly-written code.

use “ssl-use-system-ca-file”, or else “tls-database” with a GTlsFileDatabase (which allows you to do explicit error handling).

Owner: SoupSession

Flags: Read / Write

Default value: NULL

### The `“ssl-strict”` property

      “ssl-strict”               gboolean

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 SoupMessage will fail with the status `SOUP_STATUS_SSL_FAILED`.

If you set “ssl-strict” to `FALSE`, then all certificates will be accepted, and you will need to call `soup_message_get_https_status()` to distinguish valid from invalid certificates. (This can be used, eg, if you want to accept invalid certificates after giving some sort of warning.)

For a plain SoupSession, if the session has no CA file or TLS database, and this property is `TRUE`, then all certificates will be rejected. However, beware that the deprecated SoupSession subclasses (SoupSessionAsync and SoupSessionSync) have the opposite behavior: if there is no CA file or TLS database, then all certificates are always accepted, and this property has no effect.

Owner: SoupSession

Flags: Read / Write

Default value: TRUE

Since: 2.30

### The `“ssl-use-system-ca-file”` property

      “ssl-use-system-ca-file”   gboolean

Setting this to `TRUE` is equivalent to setting “tls-database” to the default system CA database. (and likewise, setting “tls-database” to the default database by hand will cause this property to become `TRUE`).

Setting this to `FALSE` (when it was previously `TRUE`) will clear the “tls-database” field.

See “ssl-strict” for more information on how https certificate validation is handled.

Note that the default value of `TRUE` only applies to plain SoupSessions. If you are using SoupSessionAsync or SoupSessionSync, the default value is `FALSE`, for backward compatibility.

Owner: SoupSession

Flags: Read / Write

Default value: TRUE

Since: 2.38

### The `“timeout”` property

      “timeout”                  guint

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

Note that the default value of 60 seconds only applies to plain SoupSessions. If you are using SoupSessionAsync or SoupSessionSync, the default value is 0 (meaning socket I/O will not time out).

Not to be confused with “idle-timeout” (which is the length of time that idle persistent connections will be kept open).

Owner: SoupSession

Flags: Read / Write

Default value: 0

### The `“tls-database”` property

      “tls-database”             GTlsDatabase *

Sets the GTlsDatabase to use for validating SSL/TLS certificates.

Note that setting the “ssl-ca-file” or “ssl-use-system-ca-file” property will cause this property to be set to a GTlsDatabase corresponding to the indicated file or system default.

See “ssl-strict” for more information on how https certificate validation is handled.

If you are using a plain SoupSession then “ssl-use-system-ca-file” will be `TRUE` by default, and so this property will be a copy of the system CA database. If you are using SoupSessionAsync or SoupSessionSync, this property will be `NULL` by default.

Owner: SoupSession

Flags: Read / Write

Since: 2.38

### The `“tls-interaction”` property

      “tls-interaction”          GTlsInteraction *

A GTlsInteraction object that will be passed on to any GTlsConnections created by the session. (This can be used to provide client-side certificates, for example.)

Owner: SoupSession

Flags: Read / Write

Since: 2.48

### The `“use-ntlm”` property

      “use-ntlm”                 gboolean

Whether or not to use NTLM authentication.

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

Owner: SoupSession

Flags: Read / Write

Default value: FALSE

### The `“use-thread-context”` property

      “use-thread-context”       gboolean

If `TRUE` (which it always is on a plain SoupSession), asynchronous HTTP requests in this session will run in whatever the thread-default GMainContext is at the time they are started, rather than always occurring in “async-context”.

Owner: SoupSession

Flags: Read / Write

Default value: FALSE

Since: 2.38

### The `“user-agent”` property

      “user-agent”               char *

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.

Owner: SoupSession

Flags: Read / Write

Default value: NULL

## Signal Details

### The `“authenticate”` signal

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

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.

#### Parameters

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

Flags: Run First

### The `“connection-created”` signal

    void
    user_function (SoupSession *session,
                   GObject     *connection,
                   gpointer     user_data)

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.

#### Parameters

session | the SoupSession |
connection | the connection |
user_data | user data set when the signal handler was connected. |

Flags: Run First

Since: 2.30

### The `“request-queued”` signal

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

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.

#### Parameters

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

Flags: Run First

Since: 2.24

### The `“request-started”` signal

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

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

`SoupSession::request-started` has been deprecated since version 2.50. and should not be used in newly-written code.

Use “starting” instead.

#### Parameters

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

Flags: Run First

### The `“request-unqueued”` signal

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

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.

#### Parameters

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

Flags: Run First

Since: 2.24

### The `“tunneling”` signal

    void
    user_function (SoupSession *session,
                   GObject     *connection,
                   gpointer     user_data)

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.

#### Parameters

session | the SoupSession |
connection | the connection |
user_data | user data set when the signal handler was connected. |

Flags: Run First

Since: 2.30