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. Normally this call will not return until the transfer is finished successfully or there is an unrecoverable error. However, if you set the SOUP_MESSAGE_PULL_BODY flag, soup_session_send_message() will return after reading only the response headers, and you will need to use soup_message_io_read() (qv) to read the response body. (Currently this only works with SoupSessionSync, not SoupSessionAsync.)

In contrast to soup_session_queue_message(), msg is neither reffed nor unreffed.

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.