## SoupSession

SoupSession — Soup session state object

## Synopsis

    struct              SoupSession;
    void                soup_session_queue_message          (SoupSession *session,
                                                             SoupMessage *msg,
                                                             SoupMessageCallbackFn 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_abort                  (SoupSession *session);
    void                soup_session_add_filter             (SoupSession *session,
                                                             SoupMessageFilter *filter);
    void                soup_session_cancel_message         (SoupSession *session,
                                                             SoupMessage *msg);
    SoupConnection*     soup_session_get_connection         (SoupSession *session,
                                                             SoupMessage *msg,
                                                             gboolean *try_pruning,
                                                             gboolean *is_new);
    void                soup_session_remove_filter          (SoupSession *session,
                                                             SoupMessageFilter *filter);
    gboolean            soup_session_try_prune_connection   (SoupSession *session);
    #define             SOUP_SESSION_PROXY_URI
    #define             SOUP_SESSION_MAX_CONNS
    #define             SOUP_SESSION_MAX_CONNS_PER_HOST
    #define             SOUP_SESSION_USE_NTLM
    #define             SOUP_SESSION_SSL_CA_FILE
    #define             SOUP_SESSION_ASYNC_CONTEXT
    #define             SOUP_SESSION_TIMEOUT

## Object Hierarchy

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

## Implemented Interfaces

SoupSession implements SoupMessageFilter.

## Properties

      "async-context"            gpointer              : Read / Write / Construct Only
      "max-conns"                gint                  : Read / Write
      "max-conns-per-host"       gint                  : Read / Write
      "proxy-uri"                gpointer              : Read / Write
      "ssl-ca-file"              gchararray            : Read / Write
      "timeout"                  guint                 : Read / Write
      "use-ntlm"                 gboolean              : Read / Write

## Signals

      "authenticate"                                   : Run First
      "reauthenticate"                                 : Run First

## Description

## Details

### struct SoupSession

    struct SoupSession;

### soup_session_queue_message ()

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

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

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

`session` : | a SoupSession
`msg` : | the message to queue
`callback` : | a SoupMessageCallbackFn which will be called after the message completes or when an unrecoverable error occurs.
`user_data` : | a pointer passed to `callback`.

### soup_session_requeue_message ()

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

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

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

### soup_session_send_message ()

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

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

`msg` is not freed upon return.

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

### soup_session_abort ()

    void                soup_session_abort                  (SoupSession *session);

Cancels all pending requests in `session`.

`session` : | the session

### soup_session_add_filter ()

    void                soup_session_add_filter             (SoupSession *session,
                                                             SoupMessageFilter *filter);

Adds `filter` to `session`'s list of message filters to be applied to all messages.

`session` : | a SoupSession
`filter` : | an object implementing the SoupMessageFilter interface

### soup_session_cancel_message ()

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

Causes `session` to immediately finish processing `msg`. You should set a status code on `msg` with `soup_message_set_status()` before calling this function.

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

### soup_session_get_connection ()

    SoupConnection*     soup_session_get_connection         (SoupSession *session,
                                                             SoupMessage *msg,
                                                             gboolean *try_pruning,
                                                             gboolean *is_new);

Tries to find or create a connection for `msg`; this is an internal method for SoupSession subclasses.

If there is an idle connection to the relevant host available, then that connection will be returned (with *`is_new` set to `FALSE`). The connection will be marked "reserved", so the caller must call `soup_connection_release()` if it ends up not using the connection right away.

If there is no idle connection available, but it is possible to create a new connection, then one will be created and returned, with *`is_new` set to `TRUE`. The caller MUST then call `soup_connection_connect_sync()` or `soup_connection_connect_async()` to connect it. If the connection attempt succeeds, the connection will be marked "reserved" and added to `session`'s connection pool once it connects. If the connection attempt fails, the connection will be unreffed.

If no connection is available and a new connection cannot be made, `soup_session_get_connection()` will return `NULL`. If `session` has the maximum number of open connections open, but does not have the maximum number of per-host connections open to the relevant host, then *`try_pruning` will be set to `TRUE`. In this case, the caller can call `soup_session_try_prune_connection()` to close an idle connection, and then try `soup_session_get_connection()` again. (If calling `soup_session_try_prune_connection()` wouldn't help, then *`try_pruning` is left untouched; it is NOT set to `FALSE`.)

`session` : | a SoupSession
`msg` : | a SoupMessage
`try_pruning` : | on return, whether or not to try pruning a connection
`is_new` : | on return, `TRUE` if the returned connection is new and not yet connected
Returns : | a SoupConnection, or `NULL`

### soup_session_remove_filter ()

    void                soup_session_remove_filter          (SoupSession *session,
                                                             SoupMessageFilter *filter);

Removes `filter` from `session`'s list of message filters

`session` : | a SoupSession
`filter` : | an object implementing the SoupMessageFilter interface

### soup_session_try_prune_connection ()

    gboolean            soup_session_try_prune_connection   (SoupSession *session);

Finds the least-recently-used idle connection in `session` and closes it.

`session` : | a SoupSession
Returns : | `TRUE` if a connection was closed, `FALSE` if there are no idle connections.

### SOUP_SESSION_PROXY_URI

    #define SOUP_SESSION_PROXY_URI          "proxy-uri"

An alias for the "proxy-uri" property.

### SOUP_SESSION_MAX_CONNS

    #define SOUP_SESSION_MAX_CONNS          "max-conns"

An alias for the "max-conns" property.

### SOUP_SESSION_MAX_CONNS_PER_HOST

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

An alias for the "max-conns-per-host" property.

### SOUP_SESSION_USE_NTLM

    #define SOUP_SESSION_USE_NTLM           "use-ntlm"

An alias for the "use-ntlm" property.

### SOUP_SESSION_SSL_CA_FILE

    #define SOUP_SESSION_SSL_CA_FILE        "ssl-ca-file"

An alias for the "ssl-ca-file" property.

### SOUP_SESSION_ASYNC_CONTEXT

    #define SOUP_SESSION_ASYNC_CONTEXT      "async-context"

An alias for the "async-context" property.

### SOUP_SESSION_TIMEOUT

    #define SOUP_SESSION_TIMEOUT		"timeout"

An alias for the "timeout" property.

## Property Details

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

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

The GMainContext to dispatch async I/O in.

### 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: 4

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

      "proxy-uri"                gpointer              : Read / Write

The HTTP Proxy to use for this session.

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

      "ssl-ca-file"              gchararray            : Read / Write

File containing SSL CA certificates.

Default value: NULL

### The "`timeout`" property

      "timeout"                  guint                 : Read / Write

Value in seconds to timeout a blocking I/O.

Default value: 0

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

      "use-ntlm"                 gboolean              : Read / Write

Whether or not to use NTLM authentication.

Default value: FALSE

## Signal Details

### The "authenticate" signal

    void                user_function                      (SoupSession *session,
                                                            SoupMessage *msg,
                                                            gchar       *auth_type,
                                                            gchar       *auth_realm,
                                                            gpointer     username,
                                                            gpointer     password,
                                                            gpointer     user_data)       : Run First

Emitted when the session requires authentication. The credentials may come from the user, or from cached information. If no credentials are available, leave `username` and `password` unchanged.

If the provided credentials fail, the reauthenticate signal will be emitted.

`session` : | the session
`msg` : | the SoupMessage being sent
`auth_type` : | the authentication type
`auth_realm` : | the realm being authenticated to
`username` : | the signal handler should set this to point to the provided username
`password` : | the signal handler should set this to point to the provided password
`user_data` : | user data set when the signal handler was connected.

### The "reauthenticate" signal

    void                user_function                      (SoupSession *session,
                                                            SoupMessage *msg,
                                                            gchar       *auth_type,
                                                            gchar       *auth_realm,
                                                            gpointer     username,
                                                            gpointer     password,
                                                            gpointer     user_data)       : Run First

Emitted when the credentials provided by the application to the authenticate signal have failed. This gives the application a second chance to provide authentication credentials. If the new credentials also fail, SoupSession will emit reauthenticate again, and will continue doing so until the provided credentials work, or a reauthenticate signal emission "fails" (because the handler left `username` and `password` unchanged). At that point, the 401 or 407 error status will be returned to the caller.

If your application only uses cached passwords, it should only connect to authenticate, and not reauthenticate.

If your application always prompts the user for a password, and never uses cached information, then you can connect the same handler to authenticate and reauthenticate.

To get standard web-browser behavior, return either cached information or a user-provided password (whichever is available) from the authenticate handler, but return only user-provided information from the reauthenticate handler.

`session` : | the session
`msg` : | the SoupMessage being sent
`auth_type` : | the authentication type
`auth_realm` : | the realm being authenticated to
`username` : | the signal handler should set this to point to the provided username
`password` : | the signal handler should set this to point to the provided password
`user_data` : | user data set when the signal handler was connected.