If non-%NULL, the value to use for the "Accept-Language" header on #SoupMessages sent from this session.
Setting this will disable #SoupSession:accept-language-auto.
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 #SoupSession:accept-language.
The #GMainContext that miscellaneous session-related asynchronous callbacks are invoked on. (Eg, setting #SoupSession:idle-timeout will add a timeout source on this context.)
For a plain #SoupSession, this property is always set to the #GMainContext that is the thread-default at the time the session was created, and cannot be overridden. For the deprecated #SoupSession subclasses, the default value is %NULL, meaning to use the global default #GMainContext.
If #SoupSession:use-thread-context is %FALSE, this context will also be used for asynchronous HTTP I/O.
A %NULL-terminated array of URI schemes that should be
considered to be aliases for "http". Eg, if this included
In a plain #SoupSession, the default value is %NULL,
meaning that only "http" is recognized as meaning "http".
In #SoupSessionAsync and #SoupSessionSync, for backward
compatibility, the default value is an array containing the
single element
See also #SoupSession:https-aliases.
A comma-delimited list of URI schemes that should be considered to be aliases for "https". See #SoupSession:http-aliases for more information.
The default value is %NULL, meaning that no URI schemes are considered aliases for "https".
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.
Note that the default value of 60 seconds only applies to plain #SoupSessions. If you are using #SoupSessionAsync or #SoupSessionSync, the default value is 0 (meaning idle connections will never time out).
Sets the #SoupAddress 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.
A #GProxyResolver to use with this session. Setting this
will clear the #SoupSession:proxy-uri property, and remove
any
By default, in a plain #SoupSession, this is set to the default #GProxyResolver, but 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.
A proxy to use for all http and https requests in this
session. Setting this will clear the
#SoupSession:proxy-resolver property, and remove any
Note that #SoupSession will normally handle looking up the user's proxy settings for you; you should only use #SoupSession:proxy-uri if you need to override the user's normal proxy settings.
Also note that this proxy will be used for
File containing SSL CA certificates.
If the specified file does not exist or cannot be read, then libsoup will print a warning, and then behave as though it had read in a empty CA file, meaning that all SSL certificates will be considered invalid.
Normally, if #SoupSession:tls-database is set (including if it was set via #SoupSession:ssl-use-system-ca-file or #SoupSession:ssl-ca-file), then libsoup will reject any certificate that is invalid (ie, expired) or that is not signed by one of the given CA certificates, and the #SoupMessage will fail with the status %SOUP_STATUS_SSL_FAILED.
If you set #SoupSession:ssl-strict to %FALSE, then all certificates will be accepted, and you will need to call soup_message_get_https_status() to distinguish valid from invalid certificates. (This can be used, eg, if you want to accept invalid certificates after giving some sort of warning.)
For a plain #SoupSession, if the session has no CA file or TLS database, and this property is %TRUE, then all certificates will be rejected. However, beware that the deprecated #SoupSession subclasses (#SoupSessionAsync and #SoupSessionSync) have the opposite behavior: if there is no CA file or TLS database, then all certificates are always accepted, and this property has no effect.
Setting this to %TRUE is equivalent to setting #SoupSession:tls-database to the default system CA database. (and likewise, setting #SoupSession:tls-database to the default database by hand will cause this property to become %TRUE).
Setting this to %FALSE (when it was previously %TRUE) will clear the #SoupSession:tls-database field.
See #SoupSession:ssl-strict for more information on how https certificate validation is handled.
If you are using #SoupSessionAsync or #SoupSessionSync, on libsoup older than 2.74.0, the default value is %FALSE, for backward compatibility.
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.
Note that the default value of 60 seconds only applies to plain #SoupSessions. If you are using #SoupSessionAsync or #SoupSessionSync, the default value is 0 (meaning socket I/O will not time out).
Not to be confused with #SoupSession:idle-timeout (which is the length of time that idle persistent connections will be kept open).
Sets the #GTlsDatabase to use for validating SSL/TLS certificates.
Note that setting the #SoupSession:ssl-ca-file or #SoupSession:ssl-use-system-ca-file property will cause this property to be set to a #GTlsDatabase corresponding to the indicated file or system default.
See #SoupSession:ssl-strict for more information on how https certificate validation is handled.
If you are using a plain #SoupSession then #SoupSession:ssl-use-system-ca-file will be %TRUE by default, and so this property will be a copy of the system CA database. If you are using #SoupSessionAsync or #SoupSessionSync, on libsoup older than 2.74.0, this property will be %NULL by default.
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.)
Whether or not to use NTLM authentication.
If %TRUE (which it always is on a plain #SoupSession), asynchronous HTTP requests in this session will run in whatever the thread-default #GMainContext is at the time they are started, rather than always occurring in #SoupSession:async-context.
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 #SoupSession:user_agent property that has trailing
whitespace, #SoupSession will append its own product token
(eg, "
Cancels all pending requests in session and closes all idle
persistent connections.
The message cancellation has the same semantics as with soup_session_cancel_message(); asynchronous requests on a #SoupSessionAsync will have their callback called before soup_session_abort() returns. Requests on a plain #SoupSession will not.
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.
See the main #SoupSession documentation for information on what features are present in sessions by default.
an object that implements #SoupSessionFeature
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.
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 or
#SoupRequest types, for instance.
You can also add a feature to the session at construct time by using the %SOUP_SESSION_ADD_FEATURE_BY_TYPE property.
See the main #SoupSession documentation for information on what features are present in sessions by default.
a #GType
Creates a binding between source_property on source and target_property
on target.
Whenever the source_property is changed the target_property is
updated using the same value. For instance:
g_object_bind_property (action, "active", widget, "sensitive", 0);
Will result in the "sensitive" property of the widget #GObject instance to be updated with the same value of the "active" property of the action #GObject instance.
If flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual:
if target_property on target changes then the source_property on source
will be updated as well.
The binding will automatically be removed when either the source or the
target instances are finalized. To remove the binding without affecting the
source and the target you can just call g_object_unref() on the returned
#GBinding instance.
Removing the binding by calling g_object_unref() on it must only be done if
the binding, source and target are only used from a single thread and it
is clear that both source and target outlive the binding. Especially it
is not safe to rely on this if the binding, source or target can be
finalized from different threads. Keep another reference to the binding and
use g_binding_unbind() instead to be on the safe side.
A #GObject can have multiple bindings.
the property on source to bind
the target #GObject
the property on target to bind
flags to pass to #GBinding
Creates a binding between source_property on source and target_property
on target, allowing you to set the transformation functions to be used by
the binding.
This function is the language bindings friendly version of g_object_bind_property_full(), using #GClosures instead of function pointers.
the property on source to bind
the target #GObject
the property on target to bind
flags to pass to #GBinding
a #GClosure wrapping the transformation function from the source to the target, or %NULL to use the default
a #GClosure wrapping the transformation function from the target to the source, or %NULL to use the default
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 requests that have side effects (eg,
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.
Beware that with the deprecated #SoupSessionAsync, messages queued with soup_session_queue_message() will have their callbacks invoked before soup_session_cancel_message() returns. The plain #SoupSession does not have this behavior; cancelling an asynchronous message will merely queue its callback to be run after returning to the main loop.
the message to cancel
status code to set on msg (generally %SOUP_STATUS_CANCELLED)
Start a connection to uri. The operation can be monitored by providing a progress_callback
and finishes when the connection is done or an error ocurred.
Call soup_session_connect_finish() to get the #GIOStream to communicate with the server.
a #SoupURI to connect to
a #GCancellable
a #SoupSessionConnectProgressCallback which will be called for every network event that occurs during the connection.
the callback to invoke when the operation finishes
Gets the #GIOStream created for the connection to communicate with the server.
the #GAsyncResult passed to your callback
This function is intended for #GObject implementations to re-enforce a [floating][floating-ref] object reference. Doing this is seldom required: all #GInitiallyUnowneds are created with a floating reference which usually just needs to be sunken by calling g_object_ref_sink().
Increases the freeze count on object. If the freeze count is
non-zero, the emission of "notify" signals on object is
stopped. The signals are queued until the freeze count is decreased
to zero. Duplicate notifications are squashed so that at most one
#GObject::notify signal is emitted for each property modified while the
object is frozen.
This is necessary for accessors that modify multiple properties to prevent premature notification while the object is still being modified.
Gets session's #SoupSession: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.
For a modern #SoupSession, this will always just return the thread-default #GMainContext, and so is not especially useful.
Gets a named field from the objects table of associations (see g_object_set_data()).
name of the key for that association
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().
the #GType of the feature to get
Gets the first feature in session of type feature_type, provided
that it is not disabled for msg. As with
soup_session_get_feature(), this should only be used for features
where feature_type is only expected to match a single feature. In
particular, if there are two matching features, and the first is
disabled on msg, and the second is not, then this will return
%NULL, not the second feature.
Generates a list of session's features of type feature_type. (If
you want to see all features, you can pass %SOUP_TYPE_SESSION_FEATURE
for feature_type.)
the #GType of the class of features to get
Gets a property of an object.
The value can be:
In general, a copy is made of the property contents and the caller is responsible for freeing the memory by calling g_value_unset().
Note that g_object_get_property() is really intended for language bindings, g_object_get() is much more convenient for C programming.
the name of the property to get
return location for the property value
This function gets back user data pointers stored via g_object_set_qdata().
A #GQuark, naming the user data pointer
Gets n_properties properties for an object.
Obtained properties will be set to values. All properties must be valid.
Warnings will be emitted and undefined behaviour may result if invalid
properties are passed in.
the names of each property to get
the values of each property to get
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 or
#SoupRequest).
the #GType of the class of features to check for
Checks whether object has a [floating][floating-ref] reference.
Emits a "notify" signal for the property property_name on object.
When possible, eg. when signaling a property change from within the class that registered the property, you should use g_object_notify_by_pspec() instead.
Note that emission of the notify signal may be blocked with g_object_freeze_notify(). In this case, the signal emissions are queued and will be emitted (in reverse order) when g_object_thaw_notify() is called.
the name of a property installed on the class of object.
Emits a "notify" signal for the property specified by pspec on object.
This function omits the property name lookup, hence it is faster than g_object_notify().
One way to avoid using g_object_notify() from within the class that registered the properties, and using g_object_notify_by_pspec() instead, is to store the GParamSpec used with g_object_class_install_property() inside a static array, e.g.:
enum
{
PROP_0,
PROP_FOO,
PROP_LAST
};
static GParamSpec *properties[PROP_LAST];
static void
my_object_class_init (MyObjectClass *klass)
{
properties[PROP_FOO] = g_param_spec_int ("foo", "Foo", "The foo",
0, 100,
50,
G_PARAM_READWRITE);
g_object_class_install_property (gobject_class,
PROP_FOO,
properties[PROP_FOO]);
}
and then notify a change on the "foo" property with:
g_object_notify_by_pspec (self, properties[PROP_FOO]);
the #GParamSpec of a property installed on the class of object.
Tells session that an URI from the given hostname may be requested
shortly, and so the session can try to prepare by resolving the
domain name in advance, in order to work more quickly once the URI
is actually requested.
If cancellable is non-%NULL, it can be used to cancel the
resolution. callback will still be invoked in this case, with a
status of %SOUP_STATUS_CANCELLED.
a hostname to be resolved
a #GCancellable object, or %NULL
callback to call with the result, or %NULL
Queues the message msg for asynchronously sending the request and
receiving a response in the current thread-default #GMainContext.
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. If after returning from this callback the message has not
been requeued, msg will be unreffed.
(The behavior above applies to a plain #SoupSession; if you are using #SoupSessionAsync or #SoupSessionSync, then the #GMainContext that is used depends on the settings of #SoupSession:async-context and #SoupSession:use-thread-context, and for #SoupSessionSync, the message will actually be sent and processed in another thread, with only the final callback occurring in the indicated #GMainContext.)
Contrast this method with soup_session_send_async(), which also asynchronously sends a message, but returns before reading the response body, and allows you to read the response via a #GInputStream.
the message to queue
a #SoupSessionCallback which will be called after the message completes or when an unrecoverable error occurs.
Updates msg's URI according to its status code and "Location"
header, and requeues it on session. Use this when you have set
%SOUP_MESSAGE_NO_REDIRECT on a message, but have decided to allow a
particular redirection to occur, or if you want to allow a
redirection that #SoupSession will not perform automatically (eg,
redirecting a non-safe method such as DELETE).
If msg's status code indicates that it should be retried as a GET
request, then msg will be modified accordingly.
If msg has already been redirected too many times, this will
cause it to fail with %SOUP_STATUS_TOO_MANY_REDIRECTS.
Increase the reference count of object, and possibly remove the
[floating][floating-ref] reference, if object has a floating reference.
In other words, if the object is floating, then this call "assumes ownership" of the floating reference, converting it to a normal reference by clearing the floating flag while leaving the reference count unchanged. If the object is not floating, then this call adds a new normal reference increasing the reference count by one.
Since GLib 2.56, the type of object will be propagated to the return type
under the same conditions as for g_object_ref().
Removes feature's functionality from session.
a feature that has previously been added to session
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.
a #GType
Creates a #SoupRequest for retrieving uri_string.
a URI, in string form
Creates a #SoupRequest for retrieving uri_string, which must be an
"http" or "https" URI (or another protocol listed in session's
#SoupSession:http-aliases or #SoupSession:https-aliases).
an HTTP method
a URI, in string form
Creates a #SoupRequest for retrieving uri, which must be an
"http" or "https" URI (or another protocol listed in session's
#SoupSession:http-aliases or #SoupSession:https-aliases).
Releases all references to other objects. This can be used to break reference cycles.
This function should only be called from object system implementations.
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,
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.
Contrast this method with soup_session_send_message(), which also synchronously sends a #SoupMessage, but doesn't return until the response has been completely read.
(Note that this method cannot be called on the deprecated #SoupSessionAsync subclass.)
a #SoupMessage
a #GCancellable
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.
Contrast this method with soup_session_queue_message(), which also asynchronously sends a #SoupMessage, but doesn't invoke its callback until the response has been completely read.
(Note that this method cannot be called on the deprecated #SoupSessionSync subclass, and can only be called on #SoupSessionAsync if you have set the #SoupSession:use-thread-context property.)
a #SoupMessage
a #GCancellable
the callback to invoke
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.
the #GAsyncResult passed to your callback
Synchronously send msg. This call will not return until the
transfer is finished successfully or there is an unrecoverable
error.
Unlike with soup_session_queue_message(), msg is not freed upon
return.
(Note that if you call this method on a #SoupSessionAsync, it will still use asynchronous I/O internally, running the glib main loop to process the message, which may also cause other events to be processed.)
Contrast this method with soup_session_send(), which also synchronously sends a message, but returns before reading the response body, and allows you to read the response via a #GInputStream.
Each object carries around a table of associations from strings to pointers. This function lets you set an association.
If the object already had an association with that name, the old association will be destroyed.
Internally, the key is converted to a #GQuark using g_quark_from_string().
This means a copy of key is kept permanently (even after object has been
finalized) — so it is recommended to only use a small, bounded set of values
for key in your program, to avoid the #GQuark storage growing unbounded.
name of the key
data to associate with that key
Sets a property on an object.
the name of the property to set
the value
"Steals" the HTTP connection associated with msg from session.
This happens immediately, regardless of the current state of the
connection, and msg's callback will not be called. You can steal
the connection from a #SoupMessage signal handler if you need to
wait for part or all of the response to be received first.
Calling this function may cause msg to be freed if you are not
holding any other reference to it.
Remove a specified datum from the object's data associations, without invoking the association's destroy handler.
name of the key
This function gets back user data pointers stored via
g_object_set_qdata() and removes the data from object
without invoking its destroy() function (if any was
set).
Usually, calling this function is only required to update
user data pointers with a destroy notifier, for example:
void
object_add_to_user_list (GObject *object,
const gchar *new_string)
{
// the quark, naming the object data
GQuark quark_string_list = g_quark_from_static_string ("my-string-list");
// retrieve the old string list
GList *list = g_object_steal_qdata (object, quark_string_list);
// prepend new string
list = g_list_prepend (list, g_strdup (new_string));
// this changed 'list', so we need to set it again
g_object_set_qdata_full (object, quark_string_list, list, free_string_list);
}
static void
free_string_list (gpointer data)
{
GList *node, *list = data;
for (node = list; node; node = node->next)
g_free (node->data);
g_list_free (list);
}
Using g_object_get_qdata() in the above example, instead of g_object_steal_qdata() would have left the destroy function set, and thus the partial string list would have been freed upon g_object_set_qdata_full().
A #GQuark, naming the user data pointer
Reverts the effect of a previous call to
g_object_freeze_notify(). The freeze count is decreased on object
and when it reaches zero, queued "notify" signals are emitted.
Duplicate notifications for each property are squashed so that at most one #GObject::notify signal is emitted for each property, in the reverse order in which they have been queued.
It is an error to call this function when the freeze count is zero.
Resumes HTTP I/O on msg. Use this to resume after calling
soup_session_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.
This may only be called for asynchronous messages (those sent on a #SoupSessionAsync or using soup_session_queue_message()).
Decreases the reference count of object. When its reference count
drops to 0, the object is finalized (i.e. its memory is freed).
If the pointer to the #GObject may be reused in future (for example, if it is an instance variable of another object), it is recommended to clear the pointer to %NULL rather than retain a dangling pointer to a potentially invalid #GObject instance. Use g_clear_object() for this.
This function essentially limits the life time of the closure to
the life time of the object. That is, when the object is finalized,
the closure is invalidated by calling g_closure_invalidate() on
it, in order to prevent invocations of the closure with a finalized
(nonexisting) object. Also, g_object_ref() and g_object_unref() are
added as marshal guards to the closure, to ensure that an extra
reference count is held on object during invocation of the
closure. Usually, this function will be called on closures that
use this object as closure data.
#GClosure to watch
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.
#SoupMessage indicating the WebSocket server to connect to
origin of the connection
a %NULL-terminated array of protocols supported
a #GCancellable
the callback to invoke
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.
the #GAsyncResult passed to your callback
Find the #GParamSpec with the given name for an
interface. Generally, the interface vtable passed in as g_iface
will be the default vtable from g_type_default_interface_ref(), or,
if you know the interface has already been loaded,
g_type_default_interface_peek().
any interface vtable for the interface, or the default vtable for the interface
name of a property to look up.
Add a property to an interface; this is only useful for interfaces that are added to GObject-derived types. Adding a property to an interface forces all objects classes with that interface to have a compatible property. The compatible property could be a newly created #GParamSpec, but normally g_object_class_override_property() will be used so that the object class only needs to provide an implementation and inherits the property description, default value, bounds, and so forth from the interface property.
This function is meant to be called from the interface's default
vtable initialization function (the class_init member of
#GTypeInfo.) It must not be called after after class_init has
been called for any object types implementing this interface.
If pspec is a floating reference, it will be consumed.
any interface vtable for the interface, or the default vtable for the interface.
the #GParamSpec for the new property
Lists the properties of an interface.Generally, the interface
vtable passed in as g_iface will be the default vtable from
g_type_default_interface_ref(), or, if you know the interface has
already been loaded, g_type_default_interface_peek().
any interface vtable for the interface, or the default vtable for the interface
Creates an synchronous #SoupSession with the default options.
Creates a new instance of a #GObject subtype and sets its properties.
Construction parameters (see %G_PARAM_CONSTRUCT, %G_PARAM_CONSTRUCT_ONLY) which are not explicitly specified are set to their default values.
the type id of the #GObject subtype to instantiate
an array of #GParameter
Creates an synchronous #SoupSession with the default options.