1 files changed, 163 insertions, 0 deletions
diff --git a/docs/reference/session-porting.xml b/docs/reference/session-porting.xml
new file mode 100644
index 00000000..680f75aa
--- /dev/null
+++ b/docs/reference/session-porting.xml
@@ -0,0 +1,163 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
+               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+<refentry id="libsoup-session-porting">
+<refmeta>
+<refentrytitle>Porting to the new SoupSession</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>LIBSOUP Library</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>Porting to the new SoupSession</refname><refpurpose>Notes on
+porting from SoupSessionAsync and SoupSessionSync to SoupSession</refpurpose>
+</refnamediv>
+
+<refsect2 id="intro">
+<title>Introduction</title>
+
+<para>
+As of libsoup 2.42, <link
+linkend="SoupSession"><type>SoupSession</type></link> is no longer an
+abstract class, and the base <type>SoupSession</type> class is now
+preferred over its traditional subclasses, <link
+linkend="SoupSessionAsync"><type>SoupSessionAsync</type></link> and
+<link linkend="SoupSessionSync"><type>SoupSessionSync</type></link>.
+</para>
+
+<para>
+There are several changes in behavior between the old and new sessions
+to be aware of.
+</para>
+
+</refsect2>
+
+<refsect2 id="defaults">
+<title>Different defaults</title>
+
+<para>
+The new <link linkend="SoupSession"><type>SoupSession</type></link>
+has different (and hopefully better) defaults than <link
+linkend="SoupSessionAsync"><type>SoupSessionAsync</type></link> and
+<link linkend="SoupSessionSync"><type>SoupSessionSync</type></link>:
+</para>
+
+<itemizedlist>
+  <listitem>
+    <para>
+      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
+      <link linkend="SOUP-STATUS-SSL-FAILED:CAPS"><literal>SOUP_STATUS_SSL_FAILED</literal></link>
+      error.
+    </para>
+    <para>
+      You can still override the CA database as before, by setting the
+      <link linkend="SoupSession--ssl-ca-file"><type>"ssl-ca-file"</type></link>
+      property, although the
+      <link linkend="SoupSession--tls-database"><type>"tls-database"</type></link>
+      property is preferred, since it allows you to do proper error
+      handling.
+    </para>
+    <para>
+      If you want to accept all certificates, set
+      <link linkend="SoupSession--ssl-strict"><type>"ssl-strict"</type></link> to
+      <literal>FALSE</literal>. 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
+      <link linkend="soup-message-get-https-status"><function>soup_message_get_https_status()</function></link>
+      to look at the certificate after the fact.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+      The
+      <link linkend="SoupSession--timeout"><type>"timeout"</type></link>
+      and
+      <link linkend="SoupSession--idle-timeout"><type>"idle-timeout"</type></link>
+      properties both default to 60 seconds.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+      The
+      <link linkend="SoupSession--http-aliases"><type>"http-aliases"</type></link>
+      property defaults to <literal>NULL</literal>, meaning that URI
+      schemes like "<literal>webcal</literal>" and
+      "<literal>dav</literal>" (and "<literal>ftp</literal>") are not
+      considered to be aliases for "<literal>http</literal>", and so
+      libsoup will not accept requests for such URIs, and will not
+      follow redirects to such URIs.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+      Every session gets a
+      <link linkend="SoupProxyResolverDefault"><type>SoupProxyResolverDefault</type></link>
+      and a
+      <link linkend="SoupContentDecoder"><type>SoupContentDecoder</type></link>
+      attached to it by default, meaning that it will automatically
+      use the user's system proxy configuration, and will handle (and
+      request) "gzip"- and "deflate"-encoded response bodies.
+    </para>
+  </listitem>
+</itemizedlist>
+
+</refsect2>
+
+<refsect2 id="apis">
+<title>Differences in SoupMessage-sending APIs</title>
+
+<para>
+<type>SoupSessionAsync</type> always uses asynchronous I/O, and
+<type>SoupSessionSync</type> always uses blocking I/O, regardless of
+the operation. In the new <type>SoupSession</type>, <link
+linkend="soup-session-queue-message"><function>soup_session_queue_message()</function></link>
+uses asynchronous I/O (like <type>SoupSessionAsync</type>), and <link
+linkend="soup-session-send-message"><function>soup_session_send_message()</function></link>
+uses blocking I/O (like <type>SoupSessionSync</type>). There is no API
+on the plain <type>SoupSession</type> that simulates the effect of
+calling <function>soup_session_send_message()</function> on a
+<type>SoupSessionAsync</type> (ie, running the main loop internally),
+or of calling <function>soup_session_queue_message()</function> on a
+<type>SoupSessionSync</type> (ie, automatically sending the request in
+another thread).
+</para>
+
+</refsect2>
+
+<refsect2 id="async">
+<title>Differences in Asynchronous I/O</title>
+
+<para>
+As compared to <link
+linkend="SoupSessionAsync"><type>SoupSessionAsync</type></link>, <link
+linkend="SoupSession"><type>SoupSession</type></link> behaves more
+like gio with respect to asynchronous I/O.
+</para>
+
+<para>
+In particular, the <link
+linkend="SoupSession--async-context"><type>"async-context"</type></link>
+and <link
+linkend="SoupSession--use-thread-context"><type>"use-thread-context"</type></link>
+properties are now effectively unused, and the session always queues
+asynchronous requests in the <link
+linkend="GMainContext"><type>GMainContext</type></link> 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.
+</para>
+
+<para>
+Additionally, <link
+linkend="soup-session-cancel-message"><function>soup_session_cancel_message()</function></link>
+now acts asynchronously when you cancel an asynchronous request;
+rather than having the request's callback be called from inside
+<function>soup_session_cancel_message()</function>, it just gets called
+when you need return to the main loop.
+</para>
+
+</refsect2>
+
+</refentry>