1<?xml version="1.0"?> 2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> 4<refentry id="libsoup-session-porting"> 5<refmeta> 6<refentrytitle>Porting to the new SoupSession</refentrytitle> 7<manvolnum>3</manvolnum> 8<refmiscinfo>LIBSOUP Library</refmiscinfo> 9</refmeta> 10 11<refnamediv> 12<refname>Porting to the new SoupSession</refname><refpurpose>Notes on 13porting from SoupSessionAsync and SoupSessionSync to SoupSession</refpurpose> 14</refnamediv> 15 16<refsect2 id="intro"> 17<title>Introduction</title> 18 19<para> 20As of libsoup 2.42, <link 21linkend="SoupSession"><type>SoupSession</type></link> is no longer an 22abstract class, and the base <type>SoupSession</type> class is now 23preferred over its traditional subclasses, <link 24linkend="SoupSessionAsync"><type>SoupSessionAsync</type></link> and 25<link linkend="SoupSessionSync"><type>SoupSessionSync</type></link>. 26</para> 27 28<para> 29There are several changes in behavior between the old and new sessions 30to be aware of. 31</para> 32 33</refsect2> 34 35<refsect2 id="defaults"> 36<title>Different defaults</title> 37 38<para> 39The new <link linkend="SoupSession"><type>SoupSession</type></link> 40has different (and hopefully better) defaults than <link 41linkend="SoupSessionAsync"><type>SoupSessionAsync</type></link> and 42<link linkend="SoupSessionSync"><type>SoupSessionSync</type></link>: 43</para> 44 45<itemizedlist> 46 <listitem> 47 <para> 48 The system TLS/SSL certificate database is used by default to 49 validate https certificates, and sites with invalid certificates 50 will refuse to load with a 51 <link linkend="SOUP-STATUS-SSL-FAILED:CAPS"><literal>SOUP_STATUS_SSL_FAILED</literal></link> 52 error. 53 </para> 54 <para> 55 You can still override the CA database as before, by setting the 56 <link linkend="SoupSession--ssl-ca-file"><type>"ssl-ca-file"</type></link> 57 property, although the 58 <link linkend="SoupSession--tls-database"><type>"tls-database"</type></link> 59 property is preferred, since it allows you to do proper error 60 handling. 61 </para> 62 <para> 63 If you want to accept all certificates, set 64 <link linkend="SoupSession--ssl-strict"><type>"ssl-strict"</type></link> to 65 <literal>FALSE</literal>. Note that libsoup will still check 66 certificates, it will just continue with the HTTP request even 67 if the certificate fails to validate. You can use 68 <link linkend="soup-message-get-https-status"><function>soup_message_get_https_status()</function></link> 69 to look at the certificate after the fact. 70 </para> 71 </listitem> 72 <listitem> 73 <para> 74 The 75 <link linkend="SoupSession--timeout"><type>"timeout"</type></link> 76 and 77 <link linkend="SoupSession--idle-timeout"><type>"idle-timeout"</type></link> 78 properties both default to 60 seconds. 79 </para> 80 </listitem> 81 <listitem> 82 <para> 83 The 84 <link linkend="SoupSession--http-aliases"><type>"http-aliases"</type></link> 85 property defaults to <literal>NULL</literal>, meaning that URI 86 schemes like "<literal>webcal</literal>" and 87 "<literal>dav</literal>" (and "<literal>ftp</literal>") are not 88 considered to be aliases for "<literal>http</literal>", and so 89 libsoup will not accept requests for such URIs, and will not 90 follow redirects to such URIs. 91 </para> 92 </listitem> 93 <listitem> 94 <para> 95 The new 96 <link linkend="SoupSession--proxy-resolver"><type>"proxy-resolver"</type></link> 97 property is now initialized to the default 98 <link linkend="GProxyResolver"><type>GProxyResolver</type></link>, 99 meaning that it will automatically use the user's system proxy 100 configuration. This replaces the use of the 101 <link linkend="SoupProxyResolverDefault"><type>SoupProxyResolverDefault</type></link>, 102 session feature in earlier releases. You can set this property to 103 <literal>NULL</literal> if you don't want to use proxies, and the 104 <link linkend="SoupSession--proxy-uri"><type>"proxy-uri"</type></link> 105 property still works if you want to use a single proxy for all requests. 106 </para> 107 </listitem> 108 <listitem> 109 <para> 110 Every session gets a 111 <link linkend="SoupContentDecoder"><type>SoupContentDecoder</type></link> 112 attached to it by default, meaning that it will automatically 113 handle (and request) "gzip"- and "deflate"-encoded response 114 bodies. 115 </para> 116 </listitem> 117</itemizedlist> 118 119</refsect2> 120 121<refsect2 id="behavior"> 122<title>Differences in feature behavior</title> 123 124<para> 125If you are using NTLM authentication, the new <type>SoupSession</type> 126behaves slightly differently from the old session types. 127</para> 128 129<para> 130First, the deprecated <link 131linkend="SOUP-SESSION-USE-NTLM:CAPS"><literal>SOUP_SESSION_USE_NTLM</literal></link> 132property is no longer supported. If you want to add support for NTLM 133to a session, call <link 134linkend="soup-session-add-feature-by-type"><function>soup_session_add_feature_by_type()</function></link>, 135passing <link 136linkend="SOUP-TYPE-AUTH-NTLM:CAPS"><literal>SOUP_TYPE_AUTH_NTLM</literal></link>. 137</para> 138 139<para> 140Second, with the old session types, enabling NTLM would cause all 141(otherwise-unauthenticated) requests to be sent with an NTLM request 142in the <literal>Authorization</literal> header. That is, libsoup would 143assume that all servers supported NTLM, and would attempt to begin 144negotiating NTLM authentication before the server ever returned a 401 145response. With the plain <type>SoupSession</type>, this no longer 146happens. If you want the old behavior, you need to call <link 147linkend="soup-auth-manager-use-auth"><function>soup_auth_manager_use_auth()</function></link> 148for each host to "preload" the NTLM authentication: 149</para> 150 151<informalexample><programlisting> 152 SoupAuthManager *auth_manager; 153 SoupAuth *auth; 154 SoupURI *uri; 155 156 auth_manager = SOUP_AUTH_MANAGER (soup_session_get_feature (session, SOUP_TYPE_AUTH_MANAGER)); 157 auth = g_object_new (SOUP_TYPE_AUTH_NTLM, NULL); 158 uri = soup_uri_new ("http://ntlm-using-host.example.com/"); 159 soup_auth_manager_use_auth (auth_manager, uri, auth); 160 g_object_unref (auth); 161 soup_uri_free (auth); 162</programlisting></informalexample> 163 164</refsect2> 165 166<refsect2 id="apis"> 167<title>Differences in SoupMessage-sending APIs</title> 168 169<para> 170<type>SoupSessionAsync</type> always uses asynchronous I/O, and 171<type>SoupSessionSync</type> always uses blocking I/O, regardless of 172the operation. In the new <type>SoupSession</type>, <link 173linkend="soup-session-queue-message"><function>soup_session_queue_message()</function></link> 174uses asynchronous I/O (like <type>SoupSessionAsync</type>), and <link 175linkend="soup-session-send-message"><function>soup_session_send_message()</function></link> 176uses blocking I/O (like <type>SoupSessionSync</type>). There is no API 177on the plain <type>SoupSession</type> that simulates the effect of 178calling <function>soup_session_send_message()</function> on a 179<type>SoupSessionAsync</type> (ie, running the main loop internally), 180or of calling <function>soup_session_queue_message()</function> on a 181<type>SoupSessionSync</type> (ie, automatically sending the request in 182another thread). 183</para> 184 185</refsect2> 186 187<refsect2 id="async"> 188<title>Differences in Asynchronous I/O</title> 189 190<para> 191As compared to <link 192linkend="SoupSessionAsync"><type>SoupSessionAsync</type></link>, <link 193linkend="SoupSession"><type>SoupSession</type></link> behaves more 194like gio with respect to asynchronous I/O. 195</para> 196 197<para> 198In particular, the <link 199linkend="SoupSession--async-context"><type>"async-context"</type></link> 200and <link 201linkend="SoupSession--use-thread-context"><type>"use-thread-context"</type></link> 202properties are now effectively unused, and the session always queues 203asynchronous requests in the <link 204linkend="GMainContext"><type>GMainContext</type></link> that was is 205the thread default when the asynchronous operation is started. Session 206bookkeeping tasks (like closing idle connections) happen in the 207context that was thread default when the session was created. 208</para> 209 210<para> 211Additionally, <link 212linkend="soup-session-cancel-message"><function>soup_session_cancel_message()</function></link> 213now acts asynchronously when you cancel an asynchronous request; 214rather than having the request's callback be called from inside 215<function>soup_session_cancel_message()</function>, it just gets called 216when you need return to the main loop. 217</para> 218 219</refsect2> 220 221</refentry> 222