struct SoupSession

struct SoupSession;

SoupSessionCallback ()

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

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

soup_session_queue_message ()

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

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

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

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.

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.

soup_session_cancel_message ()

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

Causes session to immediately finish processing msg, with a final status_code of status_code. Depending on when you cancel it, the response state may be incomplete or inconsistent.

soup_session_abort ()

void                soup_session_abort                  (SoupSession *session);

Cancels all pending requests in session.

soup_session_pause_message ()

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

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

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

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.

struct SoupSessionFeature

struct SoupSessionFeature;

The interface implemented by objects that implement features for SoupSession.

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.

soup_session_add_feature_by_type ()

void                soup_session_add_feature_by_type    (SoupSession *session,
                                                         GType feature_type);

Creates a new feature of type feature_type and adds it to session. You can use this instead of soup_session_add_feature() in the case wher you don't need to customize the new feature in any way. You can also add a feature to the session at construct time by using the SOUP_SESSION_ADD_FEATURE_BY_TYPE property.

soup_session_remove_feature ()

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

Removes feature's functionality from session.

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.

SOUP_SESSION_PROXY_URI

#define SOUP_SESSION_PROXY_URI          "proxy-uri"

SOUP_SESSION_MAX_CONNS

#define SOUP_SESSION_MAX_CONNS          "max-conns"

SOUP_SESSION_MAX_CONNS_PER_HOST

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

SOUP_SESSION_USE_NTLM

#define SOUP_SESSION_USE_NTLM           "use-ntlm"

SOUP_SESSION_SSL_CA_FILE

#define SOUP_SESSION_SSL_CA_FILE        "ssl-ca-file"

SOUP_SESSION_ASYNC_CONTEXT

#define SOUP_SESSION_ASYNC_CONTEXT      "async-context"

SOUP_SESSION_TIMEOUT

#define SOUP_SESSION_TIMEOUT            "timeout"

SOUP_SESSION_IDLE_TIMEOUT

#define SOUP_SESSION_IDLE_TIMEOUT       "idle-timeout"

SOUP_SESSION_USER_AGENT

#define SOUP_SESSION_USER_AGENT         "user-agent"

SOUP_SESSION_ADD_FEATURE

#define SOUP_SESSION_ADD_FEATURE            "add-feature"

SOUP_SESSION_ADD_FEATURE_BY_TYPE

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

SOUP_SESSION_REMOVE_FEATURE_BY_TYPE

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

The "add-feature" property

  "add-feature"              SoupSessionFeature*   : Read / Write

Add a feature object to the session.

The "add-feature-by-type" property

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

Add a feature object of the given type to the session.

The "async-context" property

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

The GMainContext to dispatch async I/O in.

The "idle-timeout" property

  "idle-timeout"             guint                 : Read / Write

Connection lifetime when idle.

Default value: 0

The "max-conns" property

  "max-conns"                gint                  : Read / Write

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

Allowed values: >= 1

Default value: 10

The "max-conns-per-host" property

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

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

Allowed values: >= 1

Default value: 2

The "proxy-uri" property

  "proxy-uri"                SoupURI*              : Read / Write

The HTTP Proxy to use for this session.

The "remove-feature-by-type" property

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

Remove features of the given type from the session.

The "ssl-ca-file" property

  "ssl-ca-file"              gchar*                : 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

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

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.

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.

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.

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.