![]() |
![]() |
![]() |
libsoup Reference Manual | ![]() |
---|---|---|---|---|
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
"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
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.
|
a SoupSession |
|
the message to queue |
|
a SoupMessageCallbackFn which will be called after the message completes or when an unrecoverable error occurs. |
|
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.
|
a SoupSession |
|
the message to requeue |
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.
|
a SoupSession |
|
the message to send |
Returns : |
the HTTP status code of the response |
void soup_session_abort (SoupSession *session);
Cancels all pending requests in session
.
|
the session |
void soup_session_add_filter (SoupSession *session, SoupMessageFilter *filter);
Adds filter
to session
's list of message filters to be applied to
all messages.
|
a SoupSession |
|
an object implementing the SoupMessageFilter interface |
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.
|
a SoupSession |
|
the message to cancel |
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
.)
|
a SoupSession |
|
a SoupMessage |
|
on return, whether or not to try pruning a connection |
|
on return, TRUE if the returned connection is new and not
yet connected
|
Returns : |
a SoupConnection, or NULL
|
void soup_session_remove_filter (SoupSession *session, SoupMessageFilter *filter);
Removes filter
from session
's list of message filters
|
a SoupSession |
|
an object implementing the SoupMessageFilter interface |
gboolean soup_session_try_prune_connection (SoupSession *session);
Finds the least-recently-used idle connection in session
and closes
it.
|
a SoupSession |
Returns : |
TRUE if a connection was closed, FALSE if there are
no idle connections.
|
#define SOUP_SESSION_PROXY_URI "proxy-uri"
An alias for the "proxy-uri" property.
#define SOUP_SESSION_MAX_CONNS "max-conns"
An alias for the "max-conns" property.
#define SOUP_SESSION_MAX_CONNS_PER_HOST "max-conns-per-host"
An alias for the "max-conns-per-host" property.
#define SOUP_SESSION_USE_NTLM "use-ntlm"
An alias for the "use-ntlm" property.
#define SOUP_SESSION_SSL_CA_FILE "ssl-ca-file"
An alias for the "ssl-ca-file" property.
#define SOUP_SESSION_ASYNC_CONTEXT "async-context"
An alias for the "async-context" property.
async-context
" property"async-context" gpointer : Read / Write / Construct Only
The GMainContext to dispatch async I/O in.
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
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
proxy-uri
" property"proxy-uri" gpointer : Read / Write
The HTTP Proxy to use for this session.
ssl-ca-file
" property"ssl-ca-file" gchararray : Read / Write
File containing SSL CA certificates.
Default value: NULL
timeout
" property"timeout" guint : Read / Write
Value in seconds to timeout a blocking I/O.
Default value: 0
use-ntlm
" property"use-ntlm" gboolean : Read / Write
Whether or not to use NTLM authentication.
Default value: FALSE
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.
|
the session |
|
the SoupMessage being sent |
|
the authentication type |
|
the realm being authenticated to |
|
the signal handler should set this to point to the provided username |
|
the signal handler should set this to point to the provided password |
|
user data set when the signal handler was connected. |
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.
|
the session |
|
the SoupMessage being sent |
|
the authentication type |
|
the realm being authenticated to |
|
the signal handler should set this to point to the provided username |
|
the signal handler should set this to point to the provided password |
|
user data set when the signal handler was connected. |