SoupSession

SoupSession — Soup session state object

Synopsis

#include <libsoup/soup.h>

                    SoupSession;

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

SoupRequest *       soup_session_request                (SoupSession *session,
                                                         const char *uri_string,
                                                         GError **error);
SoupRequest *       soup_session_request_uri            (SoupSession *session,
                                                         SoupURI *uri,
                                                         GError **error);
SoupRequestHTTP *   soup_session_request_http           (SoupSession *session,
                                                         const char *method,
                                                         const char *uri_string,
                                                         GError **error);
SoupRequestHTTP *   soup_session_request_http_uri       (SoupSession *session,
                                                         const char *method,
                                                         SoupURI *uri,
                                                         GError **error);
enum                SoupRequestError;
#define             SOUP_REQUEST_ERROR

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

GInputStream *      soup_session_send                   (SoupSession *session,
                                                         SoupMessage *msg,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                soup_session_send_async             (SoupSession *session,
                                                         SoupMessage *msg,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
GInputStream *      soup_session_send_finish            (SoupSession *session,
                                                         GAsyncResult *result,
                                                         GError **error);

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

gboolean            soup_session_would_redirect         (SoupSession *session,
                                                         SoupMessage *msg);
gboolean            soup_session_redirect_message       (SoupSession *session,
                                                         SoupMessage *msg);

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);
gboolean            soup_session_has_feature            (SoupSession *session,
                                                         GType feature_type);

#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_SSL_USE_SYSTEM_CA_FILE
#define             SOUP_SESSION_TLS_DATABASE
#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
#define             SOUP_SESSION_ACCEPT_LANGUAGE
#define             SOUP_SESSION_ACCEPT_LANGUAGE_AUTO
#define             SOUP_SESSION_SSL_STRICT
#define             SOUP_SESSION_HTTP_ALIASES
#define             SOUP_SESSION_HTTPS_ALIASES
#define             SOUP_SESSION_USE_THREAD_CONTEXT

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
  "http-aliases"             GStrv                 : Read / Write
  "https-aliases"            GStrv                 : Read / Write
  "idle-timeout"             guint                 : Read / Write
  "local-address"            SoupAddress*          : Read / Write / Construct Only
  "max-conns"                gint                  : Read / Write
  "max-conns-per-host"       gint                  : Read / Write
  "proxy-resolver"           GProxyResolver*       : 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
  "ssl-use-system-ca-file"   gboolean              : Read / Write
  "timeout"                  guint                 : Read / Write
  "tls-database"             GTlsDatabase*         : Read / Write
  "use-ntlm"                 gboolean              : Read / Write
  "use-thread-context"       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. 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.)

Details

SoupSession

typedef struct _SoupSession SoupSession;


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.

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.

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.

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

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

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


enum SoupRequestError

typedef enum {
	SOUP_REQUEST_ERROR_BAD_URI,
	SOUP_REQUEST_ERROR_UNSUPPORTED_URI_SCHEME,
	SOUP_REQUEST_ERROR_PARSING,
	SOUP_REQUEST_ERROR_ENCODING
} SoupRequestError;

A SoupRequest error.

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


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

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.

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.

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.

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

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.

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

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.

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.

Since 2.42


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.

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_prepare_for_uri ()

void                soup_session_prepare_for_uri        (SoupSession *session,
                                                         SoupURI *uri);

Warning

soup_session_prepare_for_uri has been deprecated since version 2.38 and should not be used in newly-written code. use soup_session_prefetch_dns() instead

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.

session :

a SoupSession

uri :

a SoupURI which may be required

Since 2.30


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.

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

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.

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.

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.

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

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.

Note that a SoupProxyResolverDefault and a SoupContentDecoder are added to the session by default (unless you are using one of the deprecated session subclasses).

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.

Note that a SoupProxyResolverDefault and a SoupContentDecoder are added to the session by default (unless you are using one of the deprecated session subclasses).

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 SOUP_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][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().

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

session :

a SoupSession

feature_type :

the GType of the class of features to check for

Returns :

TRUE or FALSE

Since 2.42


SOUP_SESSION_PROXY_URI

#define SOUP_SESSION_PROXY_URI              "proxy-uri"

Alias for the "proxy-uri" 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_USE_NTLM

#define SOUP_SESSION_USE_NTLM               "use-ntlm"

Alias for the "use-ntlm" property, qv.


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_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_TLS_DATABASE

#define SOUP_SESSION_TLS_DATABASE           "tls-database"

Alias for the "tls-database" property, qv.

Since 2.38


SOUP_SESSION_ASYNC_CONTEXT

#define SOUP_SESSION_ASYNC_CONTEXT          "async-context"

Alias for the "async-context" property, qv.


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_SSL_STRICT

#define SOUP_SESSION_SSL_STRICT             "ssl-strict"

Alias for the "ssl-strict" 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_USE_THREAD_CONTEXT

#define SOUP_SESSION_USE_THREAD_CONTEXT     "use-thread-context"

Alias for the "use-thread-context" property, qv.

Since 2.38

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: GObject

Since 2.24


The "async-context" property

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

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.


The "http-aliases" property

  "http-aliases"             GStrv                 : Read / Write

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

Since 2.38


The "https-aliases" property

  "https-aliases"            GStrv                 : Read / Write

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

Since 2.38


The "idle-timeout" property

  "idle-timeout"             guint                 : Read / Write

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

Default value: 60

Since 2.24


The "local-address" property

  "local-address"            SoupAddress*          : Read / Write / Construct Only

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.

Since 2.42


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-resolver" property

  "proxy-resolver"           GProxyResolver*       : Read / Write

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.

You only need to set this if you want to manually control proxy resolution (and need to do something more complicated than "proxy-uri" allows). If you just want to use the system proxy settings, SoupProxyResolverDefault will do that for you, and that is automatically part of the session if you are using a plain SoupSession.

Since 2.42


The "proxy-uri" property

  "proxy-uri"                SoupURI*              : Read / Write

An http proxy to use for all http and https requests in this session. Setting this will remove any SoupProxyURIResolver features that have been added to the session. Setting this property will also cancel all currently pending messages.

Note that SoupProxyResolverDefault will 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.


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: GObject

Since 2.24


The "ssl-ca-file" property

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

Warning

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

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.

Default value: NULL


The "ssl-strict" property

  "ssl-strict"               gboolean              : Read / Write

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.

Default value: TRUE

Since 2.30


The "ssl-use-system-ca-file" property

  "ssl-use-system-ca-file"   gboolean              : Read / Write

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.

Default value: TRUE

Since 2.38


The "timeout" property

  "timeout"                  guint                 : Read / Write

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

Default value: 0


The "tls-database" property

  "tls-database"             GTlsDatabase*         : Read / Write

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.

Since 2.38


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 "use-thread-context" property

  "use-thread-context"       gboolean              : Read / Write

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

Default value: FALSE

Since 2.38


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 *session,
                                                        GObject     *connection,
                                                        gpointer     user_data)       : Run First

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.

session :

the SoupSession

connection :

the connection

user_data :

user data set when the signal handler was connected.

Since 2.30


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


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


The "tunneling" signal

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

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.

session :

the SoupSession

connection :

the connection

user_data :

user data set when the signal handler was connected.

Since 2.30