![]() |
![]() |
![]() |
libsoup Reference Manual | ![]() |
---|---|---|---|---|
SoupSession; 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); void soup_session_abort (SoupSession *session); 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); SoupSessionFeature* soup_session_get_feature (SoupSession *session, GType feature_type); GSList* soup_session_get_features (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_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
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.
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.)
SoupSession itself is an abstract class, with two subclasses. If you are using the glib main loop, you will generally want to use SoupSessionAsync, which uses non-blocking I/O and callbacks. On the other hand, if your application is threaded and you want to do synchronous I/O in a separate thread from the UI, use SoupSessionSync.
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 |
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.
session : |
a SoupSession |
msg : |
the message to queue |
callback : |
a SoupSessionCallback which will be called after the message completes or when an unrecoverable error occurs. |
user_data : |
a pointer passed to callback .
|
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 |
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 |
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 non-idempotent requests (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.
For messages queued with soup_session_queue_message()
(and
cancelled from the same thread), the callback will be invoked
before soup_session_cancel_message()
returns.
session : |
a SoupSession |
msg : |
the message to cancel |
status_code : |
status code to set on msg (generally
SOUP_STATUS_CANCELLED )
|
void soup_session_abort (SoupSession *session);
Cancels all pending requests in session
.
session : |
the session |
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
|
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.
session : |
a SoupSession |
msg : |
a SoupMessage currently running on session
|
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.
session : |
a SoupSession |
Returns : | session 's GMainContext, which may be NULL
|
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.
session : |
a SoupSession |
feature : |
an object that implements SoupSessionFeature |
Since 2.24
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.
session : |
a SoupSession |
feature_type : |
the GType of a class that implements SoupSessionFeature |
Since 2.24
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
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 : |
the GType of a class that implements SoupSessionFeature |
Since 2.24
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 .
|
Since 2.26
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 G_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 |
Since 2.26
#define SOUP_SESSION_PROXY_URI "proxy-uri"
Alias for the "proxy-uri" property. (The HTTP proxy to use for this session.)
#define SOUP_SESSION_MAX_CONNS "max-conns"
Alias for the "max-conns" property. (The maximum number of connections that the session can open at once.)
#define SOUP_SESSION_MAX_CONNS_PER_HOST "max-conns-per-host"
Alias for the "max-conns-per-host" property. (The maximum number of connections that the session can open at once to a given host.)
#define SOUP_SESSION_USE_NTLM "use-ntlm"
Alias for the "use-ntlm" property. (Whether or not to use NTLM authentication.)
#define SOUP_SESSION_SSL_CA_FILE "ssl-ca-file"
Alias for the "ssl-ca-file" property. (File containing SSL CA certificates.)
#define SOUP_SESSION_ASYNC_CONTEXT "async-context"
Alias for the "async-context" property. (The session's GMainContext.)
#define SOUP_SESSION_TIMEOUT "timeout"
Alias for the "timeout" property. (The timeout in seconds for blocking socket I/O operations.)
#define SOUP_SESSION_IDLE_TIMEOUT "idle-timeout"
Alias for the "idle-timeout" property. (The idle connection lifetime.)
Since 2.4.1
#define SOUP_SESSION_USER_AGENT "user-agent"
Alias for the "user-agent" property, qv.
#define SOUP_SESSION_ADD_FEATURE "add-feature"
Alias for the "add-feature" property. (Shortcut
for calling soup_session_add_feature()
.
Since 2.24
#define SOUP_SESSION_ADD_FEATURE_BY_TYPE "add-feature-by-type"
Alias for the "add-feature-by-type" property.
(Shortcut for calling soup_session_add_feature_by_type()
.
Since 2.24
#define SOUP_SESSION_REMOVE_FEATURE_BY_TYPE "remove-feature-by-type"
Alias for the "remove-feature-by-type"
property. (Shortcut for calling
soup_session_remove_feature_by_type()
.
Since 2.24