libsoup Reference Manual: Porting to the new SoupSession

Porting to the new SoupSession

Porting to the new SoupSession — Notes on porting from SoupSessionAsync and SoupSessionSync to SoupSession

Introduction

As of libsoup 2.42, SoupSession is no longer an abstract class, and the base SoupSession class is now preferred over its traditional subclasses, SoupSessionAsync and SoupSessionSync.

There are several changes in behavior between the old and new sessions to be aware of.

Different defaults

The new SoupSession has different (and hopefully better) defaults than SoupSessionAsync and SoupSessionSync:

The system TLS/SSL certificate database is used by default to validate https certificates, and sites with invalid certificates will refuse to load with a SOUP_STATUS_SSL_FAILED error.

You can still override the CA database as before, by setting the "ssl-ca-file" property, although the "tls-database" property is preferred, since it allows you to do proper error handling.

If you want to accept all certificates, set "ssl-strict" to FALSE. Note that libsoup will still check certificates, it will just continue with the HTTP request even if the certificate fails to validate. You can use soup_message_get_https_status() to look at the certificate after the fact.
The "timeout" and "idle-timeout" properties both default to 60 seconds.
The "http-aliases" property defaults to NULL, meaning that URI schemes like "webcal" and "dav" (and "ftp") are not considered to be aliases for "http", and so libsoup will not accept requests for such URIs, and will not follow redirects to such URIs.
The new "proxy-resolver" property is now initialized to the default GProxyResolver, meaning that it will automatically use the user's system proxy configuration. This replaces the use of the SoupProxyResolverDefault, session feature in earlier releases. You can set this property to NULL if you don't want to use proxies, and the "proxy-uri" property still works if you want to use a single proxy for all requests.
Every session gets a SoupContentDecoder attached to it by default, meaning that it will automatically handle (and request) "gzip"- and "deflate"-encoded response bodies.

Differences in feature behavior

If you are using NTLM authentication, the new SoupSession behaves slightly differently from the old session types.

First, the deprecated SOUP_SESSION_USE_NTLM property is no longer supported. If you want to add support for NTLM to a session, call soup_session_add_feature_by_type(), passing SOUP_TYPE_AUTH_NTLM.

Second, with the old session types, enabling NTLM would cause all (otherwise-unauthenticated) requests to be sent with an NTLM request in the Authorization header. That is, libsoup would assume that all servers supported NTLM, and would attempt to begin negotiating NTLM authentication before the server ever returned a 401 response. With the plain SoupSession, this no longer happens. If you want the old behavior, you need to call soup_auth_manager_use_auth() for each host to "preload" the NTLM authentication:

SoupAuthManager *auth_manager;
SoupAuth *auth;
SoupURI *uri;

auth_manager = SOUP_AUTH_MANAGER (soup_session_get_feature (session, SOUP_TYPE_AUTH_MANAGER));
auth = g_object_new (SOUP_TYPE_AUTH_NTLM, NULL);
uri = soup_uri_new ("http://ntlm-using-host.example.com/");
soup_auth_manager_use_auth (auth_manager, uri, auth);
g_object_unref (auth);
soup_uri_free (auth);

Differences in SoupMessage-sending APIs

SoupSessionAsync always uses asynchronous I/O, and SoupSessionSync always uses blocking I/O, regardless of the operation. In the new SoupSession, soup_session_queue_message() uses asynchronous I/O (like SoupSessionAsync), and soup_session_send_message() uses blocking I/O (like SoupSessionSync). There is no API on the plain SoupSession that simulates the effect of calling soup_session_send_message() on a SoupSessionAsync (ie, running the main loop internally), or of calling soup_session_queue_message() on a SoupSessionSync (ie, automatically sending the request in another thread).

Differences in Asynchronous I/O

As compared to SoupSessionAsync, SoupSession behaves more like gio with respect to asynchronous I/O.

In particular, the "async-context" and "use-thread-context" properties are now effectively unused, and the session always queues asynchronous requests in the GMainContext that was is the thread default when the asynchronous operation is started. Session bookkeeping tasks (like closing idle connections) happen in the context that was thread default when the session was created.

Additionally, soup_session_cancel_message() now acts asynchronously when you cancel an asynchronous request; rather than having the request's callback be called from inside soup_session_cancel_message(), it just gets called when you need return to the main loop.