Top | ![]() |
![]() |
![]() |
![]() |
char * | accept-language | Read / Write |
gboolean | accept-language-auto | Read / Write |
guint | idle-timeout | Read / Write |
GInetSocketAddress * | local-address | Read / Write / Construct Only |
int | max-conns | Read / Write / Construct Only |
int | max-conns-per-host | Read / Write / Construct Only |
GProxyResolver * | proxy-resolver | Read / Write |
GSocketConnectable * | remote-connectable | Read / Write / Construct Only |
guint | timeout | Read / Write |
GTlsDatabase * | tls-database | Read / Write |
GTlsInteraction * | tls-interaction | Read / Write |
char * | user-agent | Read / Write |
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. It also keeps track of various global options and features that you are using.
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.)
Additional SoupSession functionality is provided by
SoupSessionFeature objects, which can be added to a session with
soup_session_add_feature()
or soup_session_add_feature_by_type()
For example, SoupLogger provides support for
logging HTTP traffic, SoupContentDecoder provides support for
compressed response handling, and SoupContentSniffer provides
support for HTML5-style response body content sniffing.
Additionally, subtypes of SoupAuth can be added
as features, to add support for additional authentication types.
All SoupSessions are created with a SoupAuthManager, and support
for SOUP_TYPE_AUTH_BASIC
and SOUP_TYPE_AUTH_DIGEST
. Additionally,
sessions using the plain SoupSession class (rather than one of its deprecated
subtypes) have a SoupContentDecoder by default.
Note that all async methods will invoke their callbacks on the thread-default context at the time of the function call.
SoupSession *
soup_session_new (void
);
Creates a SoupSession with the default options.
SoupSession * soup_session_new_with_options (const char *optname1
,...
);
Creates a SoupSession with the specified options.
GInetSocketAddress *
soup_session_get_local_address (SoupSession *session
);
Get the GInetSocketAddress to use for the client side of connections in session
.
guint
soup_session_get_max_conns (SoupSession *session
);
Get the maximum number of connections that session
can open at once.
guint
soup_session_get_max_conns_per_host (SoupSession *session
);
Get the maximum number of connections that session
can open at once to a given host.
void soup_session_set_proxy_resolver (SoupSession *session
,GProxyResolver *proxy_resolver
);
Set a GProxyResolver to be used by session
on new connections. If proxy_resolver
is NULL
then no proxies will be used. See “proxy-resolver” for more information.
GProxyResolver *
soup_session_get_proxy_resolver (SoupSession *session
);
Get the GProxyResolver currently used by session
.
void soup_session_set_tls_database (SoupSession *session
,GTlsDatabase *tls_database
);
Set a GTlsDatabase to be used by session
on new connections. If tls_database
is NULL
then certificate validation will always fail. See “tls-database”
for more information.
GTlsDatabase *
soup_session_get_tls_database (SoupSession *session
);
Get the GTlsDatabase currently used by session
.
void soup_session_set_tls_interaction (SoupSession *session
,GTlsInteraction *tls_interaction
);
Set a GTlsInteraction to be used by session
on new connections. If tls_interaction
is NULL
then client certificate validation will always fail. See “tls-interaction”
for more information.
GTlsInteraction *
soup_session_get_tls_interaction (SoupSession *session
);
Get the GTlsInteraction currently used by session
.
void soup_session_set_timeout (SoupSession *session
,guint timeout
);
Set a timeout in seconds for socket I/O operations to be used by session
on new connections. See “timeout” for more information.
guint
soup_session_get_timeout (SoupSession *session
);
Get the timeout in seconds for socket I/O operations currently used by session
.
void soup_session_set_idle_timeout (SoupSession *session
,guint timeout
);
Set a timeout in seconds for idle connection lifetime to be used by session
on new connections. See “idle-timeout” for more information.
guint
soup_session_get_idle_timeout (SoupSession *session
);
Get the timeout in seconds for idle connection lifetime currently used by session
.
void soup_session_set_user_agent (SoupSession *session
,const char *user_agent
);
Set the value to use for the "User-Agent" header on SoupMessages sent from session
.
If user_agent
has trailing whitespace, session
will append its own product token
(eg, "libsoup/3.0.0
") to the end of the header for you.
If user_agent
is NULL
then no "User-Agent" will be included in requests. See “user-agent”
for more information.
const char *
soup_session_get_user_agent (SoupSession *session
);
Get the value used by session
for the "User-Agent" header on new requests.
void soup_session_set_accept_language (SoupSession *session
,const char *accept_language
);
Set the value to use for the "Accept-Language" header on SoupMessages sent from session
.
If accept_language
is NULL
then no "Accept-Language" will be included in requests. See “accept-language”
for more information.
const char *
soup_session_get_accept_language (SoupSession *session
);
Get the value used by session
for the "Accept-Language" header on new requests.
void soup_session_set_accept_language_auto (SoupSession *session
,gboolean accept_language_auto
);
Set whether session
will automatically set the "Accept-Language" header on requests using
a value generated from system languages based on g_get_language_names()
. See “accept-language-auto”
for more information.
gboolean
soup_session_get_accept_language_auto (SoupSession *session
);
Get whether session
automatically sets the "Accept-Language" header on new requests.
SoupMessage * soup_session_get_async_result_message (SoupSession *session
,GAsyncResult *result
);
Gets the SoupMessage of the result
asynchronous operation
This is useful to get the SoupMessage of an asynchronous
operation started by session
from its GAsyncReadyCallback.
a SoupMessage or
NULL
if result
is not a valid session
async operation result.
[transfer none][nullable]
GSocketConnectable *
soup_session_get_remote_connectable (SoupSession *session
);
Get the remote connectable if one set.
GInputStream * soup_session_send (SoupSession *session
,SoupMessage *msg
,GCancellable *cancellable
,GError **error
);
Synchronously sends msg
and waits for the beginning of a response.
On success, a GInputStream will be returned which you can use to
read the response body. ("Success" here means only that an HTTP
response was received and understood; it does not necessarily mean
that a 2xx class status code was received.)
If non-NULL
, cancellable
can be used to cancel the request;
soup_session_send()
will return a G_IO_ERROR_CANCELLED
error. Note
that with requests that have side effects (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 msg
is requeued due to a redirect or authentication, the
initial (3xx/401/407) response body will be suppressed, and
soup_session_send()
will only return once a final response has been
received.
void soup_session_send_async (SoupSession *session
,SoupMessage *msg
,int io_priority
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
);
Asynchronously sends msg
and waits for the beginning of a
response. When callback
is called, then either msg
has been sent,
and its response headers received, or else an error has occurred.
Call soup_session_send_finish()
to get a GInputStream for reading
the response body.
See soup_session_send()
for more details on the general semantics.
session |
||
msg |
a SoupMessage. |
[transfer none] |
io_priority |
the I/O priority of the request |
|
cancellable |
a GCancellable. |
[nullable] |
callback |
the callback to invoke. |
[scope async] |
user_data |
data for |
GInputStream * soup_session_send_finish (SoupSession *session
,GAsyncResult *result
,GError **error
);
Gets the response to a soup_session_send_async()
call and (if
successful), returns a GInputStream that can be used to read the
response body.
GBytes * soup_session_send_and_read (SoupSession *session
,SoupMessage *msg
,GCancellable *cancellable
,GError **error
);
Synchronously sends msg
and reads the response body.
On success, a GBytes will be returned with the response body.
This function should only be used when the resource to be retrieved
is not too long and can be stored in memory.
See soup_session_send()
for more details on the general semantics.
void soup_session_send_and_read_async (SoupSession *session
,SoupMessage *msg
,int io_priority
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
);
Asynchronously sends msg
and reads the response body.
When callback
is called, then either msg
has been sent, and its response
body read, or else an error has occurred.
This function should only be used when the resource to be retrieved
is not too long and can be stored in memory.
Call soup_session_send_and_read_finish()
to get a GBytes with the
response body.
See soup_session_send()
for more details on the general semantics.
session |
||
msg |
a SoupMessage. |
[transfer none] |
io_priority |
the I/O priority of the request |
|
cancellable |
a GCancellable. |
[nullable] |
callback |
the callback to invoke. |
[scope async] |
user_data |
data for |
GBytes * soup_session_send_and_read_finish (SoupSession *session
,GAsyncResult *result
,GError **error
);
Gets the response to a soup_session_send_and_read_async()
call and (if
successful), returns a GBytes with the response body.
void soup_session_websocket_connect_async (SoupSession *session
,SoupMessage *msg
,const char *origin
,char **protocols
,int io_priority
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
);
Asynchronously creates a SoupWebsocketConnection to communicate with a remote server.
All necessary WebSocket-related headers will be added to msg
, and
it will then be sent and asynchronously processed normally
(including handling of redirection and HTTP authentication).
If the server returns "101 Switching Protocols", then msg
's status
code and response headers will be updated, and then the WebSocket
handshake will be completed. On success,
soup_session_websocket_connect_finish()
will return a new
SoupWebsocketConnection. On failure it will return a GError.
If the server returns a status other than "101 Switching
Protocols", then msg
will contain the complete response headers
and body from the server's response, and
soup_session_websocket_connect_finish()
will return
SOUP_WEBSOCKET_ERROR_NOT_WEBSOCKET
.
session |
||
msg |
SoupMessage indicating the WebSocket server to connect to |
|
origin |
origin of the connection. |
[nullable] |
protocols |
a
|
[nullable][array zero-terminated=1] |
io_priority |
the I/O priority of the request |
|
cancellable |
a GCancellable. |
[nullable] |
callback |
the callback to invoke. |
[scope async] |
user_data |
data for |
SoupWebsocketConnection * soup_session_websocket_connect_finish (SoupSession *session
,GAsyncResult *result
,GError **error
);
Gets the SoupWebsocketConnection response to a
soup_session_websocket_connect_async()
call and (if successful),
returns a SoupWebsocketConnection that can be used to communicate
with the server.
void
soup_session_abort (SoupSession *session
);
Cancels all pending requests in session
and closes all idle
persistent connections.
void soup_session_add_feature (SoupSession *session
,SoupSessionFeature *feature
);
Adds feature
's functionality to session
. You cannot add multiple
features of the same GType to a session.
See the main SoupSession documentation for information on what features are present in sessions by default.
void soup_session_add_feature_by_type (SoupSession *session
,GType feature_type
);
If feature_type
is the type of a class that implements
SoupSessionFeature, this creates a new feature of that type and
adds it to session
as with soup_session_add_feature()
. You can use
this when you don't need to customize the new feature in any way.
Adding multiple features of the same feature_type
is not allowed.
If feature_type
is not a SoupSessionFeature type, this gives each
existing feature on session
the chance to accept feature_type
as
a "subfeature". This can be used to add new SoupAuth types, for instance.
See the main SoupSession documentation for information on what features are present in sessions by default.
void soup_session_remove_feature (SoupSession *session
,SoupSessionFeature *feature
);
Removes feature
's functionality from session
.
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
SoupSession:remove-feature-by-type property.
SoupSessionFeature * soup_session_get_feature (SoupSession *session
,GType feature_type
);
Gets the feature in session
of type feature_type
.
SoupSessionFeature * soup_session_get_feature_for_message (SoupSession *session
,GType feature_type
,SoupMessage *msg
);
Gets the feature in session
of type feature_type
, provided
that it is not disabled for msg
.
gboolean soup_session_has_feature (SoupSession *session
,GType feature_type
);
Tests if session
has at a feature of type feature_type
(which can
be the type of either a SoupSessionFeature, or else a subtype of
some class managed by another feature, such as SoupAuth).
void soup_session_preconnect_async (SoupSession *session
,SoupMessage *msg
,int io_priority
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
);
Start a preconnection to msg
. Once the connection is done, it will remain in idle state so that
it can be reused by future requests. If there's already an idle connection for the given msg
host, the operation finishes successfully without creating a new connection. If a new request
for the given msg
host is made while the preconnect is still ongoing, the request will take
the ownership of the connection and the preconnect operation will finish successfully (if
there's a connection error it will be handled by the request).
The operation finishes when the connection is done or an error occurred.
session |
||
msg |
||
io_priority |
the I/O priority of the request |
|
cancellable |
a GCancellable. |
[nullable] |
callback |
the callback to invoke when the operation finishes. |
[nullable][scope async] |
user_data |
data for |
gboolean soup_session_preconnect_finish (SoupSession *session
,GAsyncResult *result
,GError **error
);
Complete a preconnect async operation started with soup_session_preconnect_async()
.
typedef struct _SoupSession SoupSession;
Class managing options and state for SoupMessages.
A SoupSession error.
the server's response could not be parsed |
||
the server's response was in an unsupported format |
||
the message has been redirected too many times |
||
the message has been restarted too many times |
||
failed to redirect message because Location header was missing or empty in response |
||
failed to redirect message because Location header contains an invalid URI |
||
the message is already in the session queue. Messages can only be reused after unqueued. |
“accept-language”
property “accept-language” char *
If non-NULL
, the value to use for the "Accept-Language" header
on SoupMessages sent from this session.
Setting this will disable “accept-language-auto”.
Owner: SoupSession
Flags: Read / Write
Default value: NULL
“accept-language-auto”
property“accept-language-auto” gboolean
If TRUE
, SoupSession will automatically set the string
for the "Accept-Language" header on every SoupMessage
sent, based on the return value of g_get_language_names()
.
Setting this will override any previous value of “accept-language”.
Owner: SoupSession
Flags: Read / Write
Default value: FALSE
“idle-timeout”
property“idle-timeout” guint
Connection lifetime (in seconds) when idle. Any connection left idle longer than this will be closed.
Although you can change this property at any time, it will
only affect newly-created connections, not currently-open
ones. You can call soup_session_abort()
after setting this
if you want to ensure that all future connections will have
this timeout value.
Owner: SoupSession
Flags: Read / Write
Default value: 60
“local-address”
property“local-address” GInetSocketAddress *
Sets the GInetSocketAddress to use for the client side of the connection.
Use this property if you want for instance to bind the local socket to a specific IP address.
Owner: SoupSession
Flags: Read / Write / Construct Only
“max-conns”
property “max-conns” int
The maximum number of connections that the session can open at once.
Owner: SoupSession
Flags: Read / Write / Construct Only
Allowed values: >= 1
Default value: 10
“max-conns-per-host”
property “max-conns-per-host” int
The maximum number of connections that the session can open at once to a given host.
Owner: SoupSession
Flags: Read / Write / Construct Only
Allowed values: >= 1
Default value: 2
“proxy-resolver”
property“proxy-resolver” GProxyResolver *
A GProxyResolver to use with this session.
If no proxy resolver is set, then the default proxy resolver
will be used. See g_proxy_resolver_get_default()
.
You can set it to NULL
if you don't want to use proxies, or
set it to your own GProxyResolver if you want to control
what proxies get used.
Owner: SoupSession
Flags: Read / Write
“remote-connectable”
property“remote-connectable” GSocketConnectable *
Sets a socket to make outgoing connections on. This will override the default behaviour of opening TCP/IP sockets to the hosts specified in the URIs.
This function is not required for common HTTP usage, but only when connecting to a HTTP service that is not using standard TCP/IP sockets. An example of this is a local service that uses HTTP over UNIX-domain sockets, in that case a GUnixSocketAddress can be passed to this function.
Owner: SoupSession
Flags: Read / Write / Construct Only
“timeout”
property“timeout” guint
The timeout (in seconds) for socket I/O operations (including connecting to a server, and waiting for a reply to an HTTP request).
Although you can change this property at any time, it will
only affect newly-created connections, not currently-open
ones. You can call soup_session_abort()
after setting this
if you want to ensure that all future connections will have
this timeout value.
Not to be confused with “idle-timeout” (which is the length of time that idle persistent connections will be kept open).
Owner: SoupSession
Flags: Read / Write
Default value: 0
“tls-database”
property“tls-database” GTlsDatabase *
Sets the GTlsDatabase to use for validating SSL/TLS certificates.
If no certificate database is set, then the default database will be
used. See g_tls_backend_get_default_database()
.
Owner: SoupSession
Flags: Read / Write
“tls-interaction”
property“tls-interaction” GTlsInteraction *
A GTlsInteraction object that will be passed on to any GTlsConnections created by the session. (This can be used to provide client-side certificates, for example.)
Owner: SoupSession
Flags: Read / Write
“user-agent”
property “user-agent” char *
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.
Owner: SoupSession
Flags: Read / Write
Default value: NULL
“request-queued”
signalvoid user_function (SoupSession *session, SoupMessage *msg, gpointer user_data)
Emitted when a request is queued on session
.
When sending a request, first “request_queued” is emitted, indicating that the session has become aware of the request.
After a connection is available to send the request 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 other 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. In that case the process will loop back.
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 “finished” (and all of the other SoupMessage signals) may be invoked multiple times for a given message.
session |
the session |
|
msg |
the request that was queued |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
“request-unqueued”
signalvoid user_function (SoupSession *session, SoupMessage *msg, gpointer user_data)
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.
session |
the session |
|
msg |
the request that was unqueued |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last