Merge tag '2.46.0' into baserock/morphbaserock/morph

2.46.0

8 files changed, 852 insertions, 375 deletions

diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
index f21e710e..d47693a1 100644
--- a/docs/reference/Makefile.am
+++ b/docs/reference/Makefile.am
@@ -13,7 +13,7 @@ DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml
 DOC_SOURCE_DIR=../../libsoup
 
 # Extra options to supply to gtkdoc-scan.
-SCAN_OPTIONS=--deprecated-guards=LIBSOUP_DISABLE_DEPRECATED --rebuild-types
+SCAN_OPTIONS=--deprecated-guards=SOUP_DISABLE_DEPRECATED --rebuild-types --ignore-decorators='SOUP_DEPRECATED\w*\s*\([^)]*\)|SOUP_DEPRECATED\w*|SOUP_AVAILABLE\w*'
 
 # Extra options to supply to gtkdoc-scangobj.
 SCANGOBJ_OPTIONS=
@@ -29,16 +29,23 @@ HFILE_GLOB=
 CFILE_GLOB=
 
 # Header files to ignore when scanning.
-IGNORE_HFILES= soup.h soup-marshal.h soup-enum-types.h \
+IGNORE_HFILES= soup.h soup-enum-types.h \
 	soup-message-private.h soup-session-private.h \
 	soup-auth-basic.h soup-auth-digest.h soup-auth-ntlm.h \
-	soup-connection.h soup-connection-ntlm.h \
-	soup-dns.h soup-auth-manager.h soup-auth-manager-ntlm.h \
-	soup-message-queue.h soup-path-map.h soup-ssl.h \
+	soup-connection.h soup-connection-auth.h \
+	soup-message-queue.h soup-path-map.h soup-gnome-features.h \
 	soup-proxy-resolver.h soup-proxy-resolver-gnome.h \
 	soup-proxy-resolver-static.h soup-directory-input-stream.h \
 	soup-http-input-stream.h soup-password-manager.h \
-	soup-password-manager-gnome.h
+	soup-password-manager-gnome.h soup-converter-wrapper.h \
+	soup-body-input-stream.h soup-body-output-stream.h \
+	soup-client-input-stream.h soup-content-processor.h \
+	soup-content-sniffer-stream.h soup-io-stream.h \
+	soup-cache-input-stream.h soup-filter-input-stream.h \
+	soup-cookie-jar-sqlite.h soup-requester.h soup-tld-private.h \
+	soup-misc-private.h soup-proxy-uri-resolver.h \
+	soup-proxy-resolver-wrapper.h soup-proxy-uri-resolver.h \
+	soup-cache-private.h
 
 # Images to copy into HTML directory.
 HTML_IMAGES = 
@@ -47,7 +54,9 @@ HTML_IMAGES =
 content_files =				\
 	build-howto.xml			\
 	client-howto.xml		\
-	server-howto.xml
+	request-howto.xml		\
+	server-howto.xml		\
+	session-porting.xml
 
 # Other files to distribute.
 extra_files =
@@ -64,7 +73,6 @@ GTKDOC_CFLAGS =				\
 
 GTKDOC_LIBS =						\
 	$(top_builddir)/libsoup/libsoup-2.4.la		\
-	$(top_builddir)/libsoup/libsoup-gnome-2.4.la	\
 	$(GLIB_LIBS)
 
 # include common portion ...
diff --git a/docs/reference/build-howto.xml b/docs/reference/build-howto.xml
index 975dfd55..bec9a454 100644
--- a/docs/reference/build-howto.xml
+++ b/docs/reference/build-howto.xml
@@ -35,41 +35,52 @@ that first appeared in version 2.4") and is essentially just part of
 the package name.
 </para>
 
+</refsect2>
+
+<refsect2>
+<title>API Availability and Deprecation Warnings</title>
+
 <para>
-If you are using any of the GNOME-specific features of
-<application>libsoup</application> (such as automatic proxy
-configuration), you must require
-"<literal>libsoup-gnome-2.4</literal>" instead:
+If you want to restrict your program to a particular
+<application>libsoup</application> version or range of versions, you
+can define <link
+linkend="SOUP-VERSION-MIN-REQUIRED:CAPS"><literal>SOUP_VERSION_MIN_REQUIRED</literal></link>
+and/or <link
+linkend="SOUP-VERSION-MAX-ALLOWED:CAPS"><literal>SOUP_VERSION_MAX_ALLOWED</literal></link>.
+Eg:
 </para>
 
 <informalexample><programlisting>
-PKG_CHECK_MODULES(LIBSOUP, [libsoup-gnome-2.4 >= 2.26])
-AC_SUBST(LIBSOUP_CFLAGS)
-AC_SUBST(LIBSOUP_LIBS)
+LIBSOUP_CFLAGS="$LIBSOUP_CFLAGS -DSOUP_VERSION_MIN_REQUIRED=SOUP_VERSION_2_36"
+LIBSOUP_CFLAGS="$LIBSOUP_CFLAGS -DSOUP_VERSION_MAX_ALLOWED=SOUP_VERSION_2_40"
 </programlisting></informalexample>
 
 <para>
-You can also make <application>libsoup-gnome</application> an optional
-dependency:
+The <literal>SOUP_VERSION_MIN_REQUIRED</literal> declaration states
+that the code is not expected to compile on versions of
+<application>libsoup</application> older than the indicated version
+(here, 2.36), and so the compiler should print warnings if the code
+uses functions that were deprecated as of that release.
 </para>
 
-<informalexample><programlisting>
-PKG_CHECK_MODULES(LIBSOUP_GNOME,
-		  [libsoup-gnome-2.4 >= 2.26],
-		  [LIBSOUP_CFLAGS="$LIBSOUP_GNOME_CFLAGS"
-		   LIBSOUP_LIBS="$LIBSOUP_GNOME_LIBS"
-		   AC_DEFINE(HAVE_LIBSOUP_GNOME, 1, [Have libsoup-gnome])],
-		  [PKG_CHECK_MODULES(LIBSOUP, [libsoup-2.4 >= 2.26])])
-AC_SUBST(LIBSOUP_CFLAGS)
-AC_SUBST(LIBSOUP_LIBS)
-</programlisting></informalexample>
+<para>
+The <literal>SOUP_VERSION_MAX_ALLOWED</literal> declaration states
+that the code <emphasis>is</emphasis> expected to compile on versions
+of <application>libsoup</application> up to the indicated version
+(here, 2.40), and so, when compiling the program against a newer
+version than that, the compiler should print warnings if the code uses
+functions that did not yet exist in the max-allowed release.
+</para>
 
 <para>
-This will allow the application to be built with either plain
-<application>libsoup</application> or with
-<application>libsoup-gnome</application>, and it will define the C
-preprocessor symbol <literal>HAVE_LIBSOUP_GNOME</literal> if
-<application>libsoup-gnome</application> features are available.
+You can use <link
+linkend="SOUP-CHECK-VERSION:CAPS"><literal>SOUP_CHECK_VERSION</literal></link>
+to check the version of libsoup at compile time, to compile different
+code for different <application>libsoup</application> versions. (If
+you are setting <literal>SOUP_VERSION_MIN_REQUIRED</literal> and
+<literal>SOUP_VERSION_MAX_ALLOWED</literal> to different versions, as
+in the example above, then you almost certainly need to be doing
+this.)
 </para>
 
 </refsect2>
@@ -86,18 +97,8 @@ Code using <application>libsoup</application> should do:
 </programlisting></informalexample>
 
 <para>
-or, for <application>libsoup-gnome</application>:
-</para>
-
-<informalexample><programlisting>
-#include &lt;libsoup/soup-gnome.h&gt;
-</programlisting></informalexample>
-
-<para>
-Including individual headers besides the two main header files is not
-recommended. You may include both <literal>soup.h</literal> and
-<literal>soup-gnome.h</literal> (though this is not required; the
-latter automatically includes the former).
+Including individual headers rather than <literal>soup.h</literal> is not
+recommended.
 </para>
 
 </refsect2>
diff --git a/docs/reference/client-howto.xml b/docs/reference/client-howto.xml
index a53f2ac3..e694cb72 100644
--- a/docs/reference/client-howto.xml
+++ b/docs/reference/client-howto.xml
@@ -3,16 +3,26 @@
                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
 <refentry id="libsoup-client-howto">
 <refmeta>
-<refentrytitle>Soup Client Basics</refentrytitle>
+<refentrytitle>libsoup Client Basics</refentrytitle>
 <manvolnum>3</manvolnum>
 <refmiscinfo>LIBSOUP Library</refmiscinfo>
 </refmeta>
 
 <refnamediv>
-<refname>Soup Client Basics</refname><refpurpose>Client-side tutorial</refpurpose>
+<refname>libsoup Client Basics</refname><refpurpose>Client-side tutorial</refpurpose>
 </refnamediv>
 
 <refsect2>
+<para>
+This section explains how to use <application>libsoup</application> as
+an HTTP client using several new APIs introduced in version 2.42. If
+you want to be compatible with older versions of
+<application>libsoup</application>, consult the documentation for that
+version.
+</para>
+</refsect2>
+
+<refsect2>
 <title>Creating a <type>SoupSession</type></title>
 
 <para>
@@ -24,35 +34,8 @@ authentication information, etc.
 </para>
 
 <para>
-There are two subclasses of <link
-linkend="SoupSession"><type>SoupSession</type></link> that you can use, with
-slightly different behavior:
-</para>
-
-<itemizedlist>
-    <listitem><para>
-	<link linkend="SoupSessionAsync"><type>SoupSessionAsync</type></link>,
-	which uses callbacks and the glib main loop to provide
-	asynchronous I/O.
-    </para></listitem>
-
-    <listitem><para>
-	<link linkend="SoupSessionSync"><type>SoupSessionSync</type></link>,
-	which uses blocking I/O rather than callbacks, making it more
-	suitable for threaded applications.
-    </para></listitem>
-</itemizedlist>
-
-<para>
-If you want to do a mix of mainloop-based and blocking I/O, you will
-need to create two different session objects.
-</para>
-
-<para>
-When you create the session (with <link
-linkend="soup-session-async-new-with-options"><function>soup_session_async_new_with_options</function></link>
-or <link
-linkend="soup-session-sync-new-with-options"><function>soup_session_sync_new_with_options</function></link>),
+When you create the session with <link
+linkend="soup-session-new-with-options"><function>soup_session_new_with_options</function></link>,
 you can specify various additional options:
 </para>
 
@@ -64,7 +47,7 @@ you can specify various additional options:
 	    the session will have open at one time. (Once it reaches
 	    this limit, it will either close idle connections, or
 	    wait for existing connections to free up before starting
-	    new requests.)
+	    new requests.) The default value is 10.
 	</para></listitem>
     </varlistentry>
     <varlistentry>
@@ -72,44 +55,61 @@ you can specify various additional options:
 	<listitem><para>
 	    Allows you to set the maximum total number of connections
 	    the session will have open <emphasis>to a single
-	    host</emphasis> at one time.
+	    host</emphasis> at one time. The default value is 2.
 	</para></listitem>
     </varlistentry>
     <varlistentry>
-	<term><link linkend="SOUP-SESSION-USE-NTLM:CAPS"><literal>SOUP_SESSION_USE_NTLM</literal></link></term>
+	<term><link linkend="SOUP-SESSION-USER-AGENT:CAPS"><literal>SOUP_SESSION_USER_AGENT</literal></link></term>
 	<listitem><para>
-	    If <literal>TRUE</literal>, then Microsoft NTLM
-	    authentication will be used if available (and will be
-	    preferred to HTTP Basic or Digest authentication).
-	    If <literal>FALSE</literal>, NTLM authentication won't be
-	    used, even if it's the only authentication type available.
-	    (NTLM works differently from the standard HTTP
-	    authentication types, so it needs to be handled
-	    specially.)
+	    Allows you to set a User-Agent string that will be sent
+	    on all outgoing requests.
 	</para></listitem>
     </varlistentry>
     <varlistentry>
-	<term><link linkend="SOUP-SESSION-SSL-CA-FILE:CAPS"><literal>SOUP_SESSION_SSL_CA_FILE</literal></link></term>
+	<term><link linkend="SOUP-SESSION-ACCEPT-LANGUAGE:CAPS"><literal>SOUP_SESSION_ACCEPT_LANGUAGE</literal></link>
+	and <link linkend="SOUP-SESSION-ACCEPT-LANGUAGE-AUTO:CAPS"><literal>SOUP_SESSION_ACCEPT_LANGUAGE_AUTO</literal></link></term>
 	<listitem><para>
-	    Points to a file containing certificates for recognized
-	    SSL Certificate Authorities. If this is set, then HTTPS
-	    connections will be checked against these authorities, and
-	    rejected if they can't be verified. (Otherwise all SSL
-	    certificates will be accepted automatically.)
+	    Allow you to set an Accept-Language header on all outgoing
+	    requests. <literal>SOUP_SESSION_ACCEPT_LANGUAGE</literal>
+	    takes a list of language tags to use, while
+	    <literal>SOUP_SESSION_ACCEPT_LANGUAGE_AUTO</literal>
+	    automatically generates the list from the user's locale
+	    settings.
 	</para></listitem>
     </varlistentry>
     <varlistentry>
-	<term><link linkend="SOUP-SESSION-ASYNC-CONTEXT:CAPS"><literal>SOUP_SESSION_ASYNC_CONTEXT</literal></link></term>
+	<term><link linkend="SOUP-SESSION-HTTP-ALIASES:CAPS"><literal>SOUP_SESSION_HTTP_ALIASES</literal></link>
+	and <link linkend="SOUP-SESSION-HTTPS-ALIASES:CAPS"><literal>SOUP_SESSION_HTTPS_ALIASES</literal></link></term>
 	<listitem><para>
-	    A <link
-	    linkend="GMainContext"><type>GMainContext</type></link>
-	    which the session will use for asynchronous operations.
-	    This can be set if you want to use a
-	    <type>SoupSessionAsync</type> in a thread other than the
-	    main thread.
+	    Allow you to tell the session to recognize additional URI
+	    schemes as aliases for "<literal>http</literal>" or
+	    <literal>https</literal>. You can set this if you are
+	    using URIs with schemes like "<literal>dav</literal>" or
+	    "<literal>webcal</literal>" (and in particular, you need
+	    to set this if the server you are talking to might return
+	    redirects with such a scheme).
 	</para></listitem>
     </varlistentry>
     <varlistentry>
+	<term><link linkend="SOUP-SESSION-PROXY-RESOLVER:CAPS"><literal>SOUP_SESSION_PROXY_RESOLVER</literal></link> and <link linkend="SOUP-SESSION-PROXY-URI:CAPS"><literal>SOUP_SESSION_PROXY_URI</literal></link></term>
+	<listitem>
+	    <para>
+		<link linkend="SOUP-SESSION-PROXY-RESOLVER:CAPS"><literal>SOUP_SESSION_PROXY_RESOLVER</literal></link>
+		specifies a <link
+		linkend="GProxyResolver"><type>GProxyResolver</type></link>
+		to use to determine the HTTP proxies to use. By default,
+		this is set to the resolver returned by <link
+		linkend="g-proxy-resolver-get-default"><function>g_proxy_resolver_get_default</function></link>,
+		so you do not need to set it yourself.
+	    </para>
+	    <para>
+		Alternatively, if you want all requests to go through a
+		single proxy, you can set <link
+		linkend="SOUP-SESSION-PROXY-URI:CAPS"><literal>SOUP_SESSION_PROXY_URI</literal></link>.
+	    </para>
+	</listitem>
+    </varlistentry>
+    <varlistentry>
 	<term><link linkend="SOUP-SESSION-ADD-FEATURE:CAPS"><literal>SOUP_SESSION_ADD_FEATURE</literal></link> and <link linkend="SOUP-SESSION-ADD-FEATURE-BY-TYPE:CAPS"><literal>SOUP_SESSION_ADD_FEATURE_BY_TYPE</literal></link></term>
 	<listitem><para>
 	    These allow you to specify <link
@@ -121,10 +121,15 @@ you can specify various additional options:
 </variablelist>
 
 <para>
+Other properties are also available; see the <link
+linkend="SoupSession"><type>SoupSession</type></link> documentation for
+more details.
+</para>
+
+<para>
 If you don't need to specify any options, you can just use <link
-linkend="soup-session-async-new"><function>soup_session_async_new</function></link> or
-<link linkend="soup-session-sync-new"><function>soup_session_sync_new</function></link>,
-which take no arguments.
+linkend="soup-session-new"><function>soup_session_new</function></link>,
+which takes no arguments.
 </para>
 
 </refsect2>
@@ -143,8 +148,19 @@ options at session-construction-time, or afterward via the <link
 linkend="soup-session-add-feature"><function>soup_session_add_feature</function></link>
 and <link
 linkend="soup-session-add-feature-by-type"><function>soup_session_add_feature_by_type</function></link>
-functions. Some of the features available in
-<application>libsoup</application> are:
+functions.
+</para>
+
+<para>
+A <link
+linkend="SoupContentDecoder"><type>SoupContentDecoder</type></link> is
+added for you automatically. This advertises to servers that the
+client supports compression, and automatically decompresses compressed
+responses.
+</para>
+
+<para>
+Some other available features that you can add include:
 </para>
 
 <variablelist>
@@ -156,33 +172,27 @@ functions. Some of the features available in
 	</para></listitem>
     </varlistentry>
     <varlistentry>
-	<term><link linkend="SoupCookieJar"><type>SoupCookieJar</type></link> and <link linkend="SoupCookieJarText"><type>SoupCookieJarText</type></link></term>
+	<term>
+	    <link linkend="SoupCookieJar"><type>SoupCookieJar</type></link>,
+	    <link linkend="SoupCookieJarText"><type>SoupCookieJarText</type></link>,
+	    and <link linkend="SoupCookieJarDB"><type>SoupCookieJarDB</type></link>
+	</term>
 	<listitem><para>
 	    Support for HTTP cookies. <type>SoupCookieJar</type>
 	    provides non-persistent cookie storage, while
 	    <type>SoupCookieJarText</type> uses a text file to keep
-	    track of cookies between sessions.
-	</para></listitem>
-    </varlistentry>
-</variablelist>
-
-<para>
-And in <application>libsoup-gnome</application>:
-</para>
-
-<variablelist>
-    <varlistentry>
-	<term><link linkend="SOUP-TYPE-PROXY-RESOLVER-GNOME:CAPS"><type>SoupProxyResolverGNOME</type></link></term>
-	<listitem><para>
-	    A feature that automatically determines the correct HTTP
-	    proxy to use for requests.
+	    track of cookies between sessions, and
+	    <type>SoupCookieJarDB</type> uses a
+	    <application>SQLite</application> database.
 	</para></listitem>
     </varlistentry>
     <varlistentry>
-	<term><link linkend="SoupCookieJarSqlite"><type>SoupCookieJarSqlite</type></link></term>
+	<term><link linkend="SoupContentSniffer"><type>SoupContentSniffer</type></link></term>
 	<listitem><para>
-	    Support for HTTP cookies stored in an
-	    <application>SQLite</application> database.
+	    Uses the HTML5 sniffing rules to attempt to
+	    determine the Content-Type of a response when the
+	    server does not identify the Content-Type, or appears to
+	    have provided an incorrect one. 
 	</para></listitem>
     </varlistentry>
 </variablelist>
@@ -190,7 +200,7 @@ And in <application>libsoup-gnome</application>:
 <para>
 Use the "add_feature_by_type" property/function to add features that
 don't require any configuration (such as <link
-linkend="SOUP-TYPE-PROXY-RESOLVER-GNOME:CAPS"><type>SoupProxyResolverGNOME</type></link>),
+linkend="SoupContentSniffer"><type>SoupContentSniffer</type></link>),
 and the "add_feature" property/function to add features that must be
 constructed first (such as <link
 linkend="SoupLogger"><type>SoupLogger</type></link>). For example, an
@@ -198,11 +208,10 @@ application might do something like the following:
 </para>
 
 <informalexample><programlisting>
-	session = soup_session_async_new_with_options (
-#ifdef HAVE_LIBSOUP_GNOME
-		SOUP_SESSION_ADD_FEATURE_BY_TYPE, SOUP_TYPE_PROXY_RESOLVER_GNOME,
-#endif
+	session = soup_session_new_with_options (
+		SOUP_SESSION_ADD_FEATURE_BY_TYPE, SOUP_TYPE_CONTENT_SNIFFER,
 		NULL);
+
 	if (debug_level) {
 		SoupLogger *logger;
 
@@ -218,7 +227,7 @@ application might do something like the following:
 <title>Creating and Sending SoupMessages</title>
 
 <para>
-Once you have a session, you do HTTP traffic using <link
+Once you have a session, you send HTTP requests using <link
 linkend="SoupMessage"><type>SoupMessage</type></link>. In the simplest
 case, you only need to create the message and it's ready to send:
 </para>
@@ -242,7 +251,7 @@ request headers and body of the message:
 
 	msg = soup_message_new ("POST", "http://example.com/form.cgi");
 	soup_message_set_request (msg, "application/x-www-form-urlencoded",
-				  SOUP_MEMORY_COPY, formdata, strlen (formdata));
+	                          SOUP_MEMORY_COPY, formdata, strlen (formdata));
 	soup_message_headers_append (msg->request_headers, "Referer", referring_url);
 </programlisting></informalexample>
 
@@ -269,28 +278,56 @@ flag.
 
 <para>
 To send a message and wait for the response, use <link
-linkend="soup-session-send-message"><function>soup_session_send_message</function></link>:
+linkend="soup-session-send"><function>soup_session_send</function></link>:
 </para>
 
 <informalexample><programlisting>
-	guint status;
+	GInputStream *stream;
+	GError *error = NULL;
 
-	status = soup_session_send_message (session, msg);
+	stream = soup_session_send (session, msg, cancellable, &amp;error);
 </programlisting></informalexample>
 
 <para>
-(If you use <function>soup_session_send_message</function> with a
-<link linkend="SoupSessionAsync"><type>SoupSessionAsync</type></link>,
-it will run the main loop itself until the message is complete.)
+At the point when <function>soup_session_send</function> returns, the
+request will have been sent, and the response headers read back in;
+you can examine the message's <structfield>status_code</structfield>,
+<structfield>reason_phrase</structfield>, and
+<structfield>response_headers</structfield> fields to see the response
+metadata. To get the response body, read from the returned <link
+linkend="GInputStream"><type>GInputStream</type></link>, and close it
+when you are done.
 </para>
 
 <para>
-The return value from <function>soup_session_send_message</function>
-is a <link linkend="libsoup-2.4-soup-status">libsoup status code</link>,
-indicating either a transport error that prevented the message from
-being sent, or the HTTP status that was returned by the server in
-response to the message. (The status is also available as
-<literal>msg->status_code</literal>.)
+Note that <function>soup_session_send</function> only returns an error
+if a transport-level problem occurs (eg, it could not connect to the
+host, or the request was cancelled). Use the message's
+<structfield>status_code</structfield> field to determine whether the
+request was successful or not at the HTTP level (ie, "<literal>200
+OK</literal>" vs "<literal>401 Bad Request</literal>").
+</para>
+
+<para>
+If you would prefer to have <application>libsoup</application> gather
+the response body for you and then return it all at once, you can use
+the older
+<link linkend="soup-session-send-message"><function>soup_session_send_message</function></link>
+API:
+</para>
+
+<informalexample><programlisting>
+	guint status;
+
+	status = soup_session_send_message (session, msg);
+</programlisting></informalexample>
+
+<para>
+In this case, the response body will be available in the message's
+<structfield>response_body</structfield> field, and transport-level
+errors will be indicated in the <structfield>status_code</structfield>
+field via special pseudo-HTTP-status codes like <link
+linkend="SOUP-STATUS-CANT-CONNECT:CAPS"><literal>SOUP_STATUS_CANT_CONNECT</literal></link>.
 </para>
 
 </refsect3>
@@ -300,51 +337,63 @@ response to the message. (The status is also available as
 
 <para>
 To send a message asynchronously, use <link
-linkend="soup-session-queue-message"><function>soup_session_queue_message</function></link>:
+linkend="soup-session-send-async"><function>soup_session_send_async</function></link>:
 </para>
 
 <informalexample><programlisting>
+{
 	...
-	soup_session_queue_message (session, msg, my_callback, my_callback_data);
+	soup_session_send_async (session, msg, cancellable, my_callback, my_callback_data);
 	...
 }
 
 static void
-my_callback (SoupSession *session, SoupMessage *msg, gpointer user_data)
+my_callback (GObject *object, GAsyncResult *result, gpointer user_data)
 {
-	/* Handle the response here */
+	GInputStream *stream;
+	GError *error = NULL;
+
+	stream = soup_session_send_finish (SOUP_SESSION (object), result, &amp;error);
+	...
 }
 </programlisting></informalexample>
 
 <para>
 The message will be added to the session's queue, and eventually (when
 control is returned back to the main loop), it will be sent and the
-response be will be read. When the message is complete,
-<literal>callback</literal> will be invoked, along with the data you
-passed to <function>soup_session_queue_message</function>.
+response be will be read. When the message has been sent, and its
+headers received, the callback will be invoked, in the standard
+<link linkend="GAsyncReadyCallback"><type>GAsyncReadyCallback</type></link>
+style.
 </para>
 
 <para>
-<link
-linkend="soup-session-queue-message"><function>soup_session_queue_message</function></link>
-steals a reference to the message object, and unrefs it after the last
-callback is invoked on it. So in the usual case, messages sent
-asynchronously will be automatically freed for you without you needing
-to do anything. (Of course, this wouldn't work when using the synchronous
-API, since you will usually need continue working with the message
-after calling <link
-linkend="soup-session-send-message"><function>soup_session_send_message</function></link>,
-so in that case, you must unref it explicitly when you are done with
-it.)
+As with synchronous sending, there is also an alternate API, <link
+linkend="soup-session-queue-message"><function>soup_session_queue_message</function></link>,
+in which your callback is not invoked until the response has been
+completely read:
 </para>
 
+<informalexample><programlisting>
+{
+	...
+	soup_session_queue_message (session, msg, my_callback, my_callback_data);
+	...
+}
+
+static void
+my_callback (SoupSession *session, SoupMessage *msg, gpointer user_data)
+{
+	/* msg->response_body contains the response */
+}
+</programlisting></informalexample>
+
 <para>
-(If you use <link
+<link
 linkend="soup-session-queue-message"><function>soup_session_queue_message</function></link>
-with a <link
-linkend="SoupSessionSync"><type>SoupSessionSync</type></link>, the
-message will be sent in another thread, with the callback eventually
-being invoked in the session's <link linkend="SOUP-SESSION-ASYNC-CONTEXT:CAPS"><literal>SOUP_SESSION_ASYNC_CONTEXT</literal></link>.)
+is slightly unusual in that it steals a reference to the message
+object, and unrefs it after the last callback is invoked on it. So
+when using this API, you should not unref the message yourself.
 </para>
 
 </refsect3>
@@ -355,19 +404,17 @@ being invoked in the session's <link linkend="SOUP-SESSION-ASYNC-CONTEXT:CAPS"><
 <title>Processing the Response</title>
 
 <para>
-Once you have received the response from the server, synchronously or
-asynchronously, you can look at the response fields in the
-<literal>SoupMessage</literal> to decide what to do next. The
-<structfield>status_code</structfield> and
+Once you have received the initial response from the server,
+synchronously or asynchronously, streaming or not, you can look at the
+response fields in the <literal>SoupMessage</literal> to decide what
+to do next. The <structfield>status_code</structfield> and
 <structfield>reason_phrase</structfield> fields contain the numeric
 status and textual status response from the server.
 <structfield>response_headers</structfield> contains the response
 headers, which you can investigate using <link
-linkend="soup-message-headers-get"><function>soup_message_headers_get</function></link> and
-<link
-    linkend="soup-message-headers-foreach"><function>soup_message_headers_foreach</function></link>.
-The response body (if any) is in the
-<structfield>response_body</structfield> field.
+linkend="soup-message-headers-get"><function>soup_message_headers_get</function></link>
+and <link
+linkend="soup-message-headers-foreach"><function>soup_message_headers_foreach</function></link>.
 </para>
 
 <para>
@@ -390,41 +437,6 @@ headers much better than functions like
 </refsect2>
 
 <refsect2>
-<title>Intermediate/Automatic Processing</title>
-
-<para>
-You can also connect to various <type>SoupMessage</type> signals to do
-processing at intermediate stages of HTTP I/O. Eg, the <link
-linkend="SoupMessage-got-chunk"><literal>got-chunk</literal></link>
-signal is emitted as each piece of the response body is read (allowing
-you to provide progress information when receiving a large response,
-for example). <type>SoupMessage</type> also provides two convenience
-methods, <link
-linkend="soup-message-add-header-handler"><function>soup_message_add_header_handler</function></link>,
-and <link
-linkend="soup-message-add-status-code-handler"><function>soup_message_add_status_code_handler</function></link>,
-which allow you to set up a signal handler that will only be invoked
-for messages with certain response headers or status codes.
-<type>SoupSession</type> uses this internally to handle authentication
-and redirection.
-</para>
-
-<para>
-When using the synchronous API, the callbacks and signal handlers will
-be invoked during the call to <link
-linkend="soup-session-send-message"><function>soup_session_send_message</function></link>.
-</para>
-
-<para>
-To automatically set up handlers on all messages sent via a session,
-you can connect to the session's <link
-linkend="SoupSession-request-started"><literal>request_started</literal></link>
-signal, and add handlers to each message from there.
-</para>
-
-</refsect2>
-
-<refsect2>
 <title>Handling Authentication</title>
 
 <para>
@@ -474,38 +486,39 @@ linkend="soup-session-unpause-message"><function>soup_session_unpause_message</f
 to resume the paused message.
 </para>
 
+<para>
+By default, NTLM authentication is not enabled. To add NTLM support to
+a session, call:
+</para>
+
+<informalexample><programlisting>
+	soup_session_add_feature_by_type (session, SOUP_TYPE_AUTH_NTLM);
+</programlisting></informalexample>
+
+<para>
+(You can also disable Basic or Digest authentication by calling <link
+linkend="soup-session-remove-feature-by-type"><function>soup_session_remove_feature_by_type</function></link>
+on <link linkend="SOUP-TYPE-AUTH-BASIC:CAPS"><literal>SOUP_TYPE_AUTH_BASIC</literal></link>
+or <link linkend="SOUP-TYPE-AUTH-DIGEST:CAPS"><literal>SOUP_TYPE_AUTH_DIGEST</literal></link>.)
+</para>
+
 </refsect2>
 
 <refsect2>
 <title>Multi-threaded usage</title>
 
 <para>
-The only explicitly thread-safe operations in
-<application>libsoup</application> are <link
-linkend="SoupSessionSync"><type>SoupSessionSync</type></link>'s
-implementations of the <link
-linkend="SoupSession"><type>SoupSession</type></link> methods. So
-after creating a <type>SoupSessionSync</type>, you can call <link
-linkend="soup-session-send-message"><function>soup_session_send_message</function></link>
-and <link
-linkend="soup-session-cancel-message"><function>soup_session_cancel_message</function></link>
-on it from any thread. But, eg, while the session is processing a
-message, you should not call any <link
-linkend="SoupMessage"><type>SoupMessage</type></link> methods on it
-from any thread other than the one in which it is being sent. (That
-is, you should not call any <type>SoupMessage</type> methods on it
-except from a message or session callback or signal handler.)
+A <link linkend="SoupSession"><type>SoupSession</type></link> can be
+used from multiple threads. However, if you are using the async APIs,
+then each thread you use the session from must have its own
+thread-default <link linkend="GMainContext"><type>GMainContext</type></link>.
 </para>
 
 <para>
-All other objects (including <link
-linkend="SoupSessionAsync"><type>SoupSessionAsync</type></link>)
-should only be used from a single thread, with objects that are also
-only be used from that thread. (And in particular, if you set a
-non-default <link
-linkend="GMainContext"><type>GMainContext</type></link> on a session,
-socket, etc, then you can only use that object from the thread in
-which that <type>GMainContext</type> is running.)
+<link linkend="SoupMessage"><type>SoupMessage</type></link> is
+<emphasis>not</emphasis> thread-safe, so once you send a message on
+the session, you must not interact with it from any thread other than
+the one where it was sent.
 </para>
 
 </refsect2>
@@ -515,7 +528,8 @@ which that <type>GMainContext</type> is running.)
 
 <para>
 A few sample programs are available in the
-<application>libsoup</application> sources:
+<application>libsoup</application> sources, in the
+<literal>examples</literal> directory:
 </para>
 
 <itemizedlist>
@@ -525,21 +539,6 @@ A few sample programs are available in the
     </para></listitem>
 
     <listitem><para>
-	<emphasis role="bold"><literal>getbug</literal></emphasis> is a trivial
-	demonstration of the <link
-	linkend="libsoup-2.4-XMLRPC-Support">XMLRPC</link> interface.
-	(<emphasis
-	role="bold"><literal>xmlrpc-test</literal></emphasis> provides
-	a slightly more complicated example.)
-    </para></listitem>
-
-    <listitem><para>
-	<emphasis role="bold"><literal>auth-test</literal></emphasis> shows how to use
-	authentication handlers and status-code handlers, although in
-	a fairly unusual way.
-    </para></listitem>
-
-    <listitem><para>
 	<emphasis role="bold"><literal>simple-proxy</literal></emphasis> uses both the
 	client and server APIs to create a simple (and not very
 	RFC-compliant) proxy server. It shows how to use the <link
@@ -551,11 +550,7 @@ A few sample programs are available in the
 </itemizedlist>
 
 <para>
-More complicated examples are available in GNOME CVS. The <ulink
-url="http://live.gnome.org/LibSoup"><application>libsoup</application>
-pages</ulink> on the GNOME wiki include a <ulink
-url="http://live.gnome.org/LibSoup/Users">list of applications using
-<application>libsoup</application></ulink>.
+More complicated examples are available in GNOME git.
 </para>
 
 </refsect2>
diff --git a/docs/reference/libsoup-2.4-docs.sgml b/docs/reference/libsoup-2.4-docs.sgml
index 21e19ea4..c0c8a05c 100644
--- a/docs/reference/libsoup-2.4-docs.sgml
+++ b/docs/reference/libsoup-2.4-docs.sgml
@@ -10,7 +10,9 @@
     <title>Tutorial</title>
     <xi:include href="build-howto.xml"/>
     <xi:include href="client-howto.xml"/>
+    <xi:include href="request-howto.xml"/>
     <xi:include href="server-howto.xml"/>
+    <xi:include href="session-porting.xml"/>
   </chapter>
 
   <chapter>
@@ -19,6 +21,7 @@
     <xi:include href="xml/soup-auth-domain.xml"/>
     <xi:include href="xml/soup-auth-domain-basic.xml"/>
     <xi:include href="xml/soup-auth-domain-digest.xml"/>
+    <xi:include href="xml/soup-cache.xml"/>
     <xi:include href="xml/soup-cookie.xml"/>
     <xi:include href="xml/soup-message.xml"/>
     <xi:include href="xml/soup-message-headers.xml"/>
@@ -26,6 +29,11 @@
     <xi:include href="xml/soup-method.xml"/>
     <xi:include href="xml/soup-misc.xml"/>
     <xi:include href="xml/soup-multipart.xml"/>
+    <xi:include href="xml/soup-multipart-input-stream.xml"/>
+    <xi:include href="xml/soup-request.xml"/>
+    <xi:include href="xml/soup-request-http.xml"/>
+    <xi:include href="xml/soup-request-file.xml"/>
+    <xi:include href="xml/soup-request-data.xml"/>
     <xi:include href="xml/soup-server.xml"/>
     <xi:include href="xml/soup-session.xml"/>
     <xi:include href="xml/soup-session-async.xml"/>
@@ -33,17 +41,19 @@
     <xi:include href="xml/soup-status.xml"/>
     <xi:include href="xml/soup-tld.xml"/>
     <xi:include href="xml/soup-uri.xml"/>
+    <xi:include href="xml/soup-version.xml"/>
   </chapter>
 
   <chapter>
     <title>Additional Features</title>
     <xi:include href="xml/soup-session-feature.xml"/>
+    <xi:include href="xml/soup-auth-manager.xml"/>
     <xi:include href="xml/soup-content-decoder.xml"/>
     <xi:include href="xml/soup-content-sniffer.xml"/>
     <xi:include href="xml/soup-cookie-jar.xml"/>
     <xi:include href="xml/soup-cookie-jar-text.xml"/>
+    <xi:include href="xml/soup-cookie-jar-db.xml"/>
     <xi:include href="xml/soup-logger.xml"/>
-    <xi:include href="xml/soup-proxy-uri-resolver.xml"/>
     <xi:include href="xml/soup-proxy-resolver-default.xml"/>
   </chapter>
 
@@ -55,27 +65,11 @@
   </chapter>
 
   <chapter>
-    <title>GNOME integration</title>
-    <xi:include href="xml/soup-gnome-features.xml"/>
-    <xi:include href="xml/soup-cookie-jar-sqlite.xml"/>
-  </chapter>
-
-  <chapter>
     <title>Low-level Networking API</title>
     <xi:include href="xml/soup-address.xml"/>
     <xi:include href="xml/soup-socket.xml"/>
   </chapter>
 
-  <chapter>
-    <title>Experimental streaming API</title>
-    <xi:include href="xml/soup-requester.xml"/>
-    <xi:include href="xml/soup-request.xml"/>
-    <xi:include href="xml/soup-request-http.xml"/>
-    <xi:include href="xml/soup-request-file.xml"/>
-    <xi:include href="xml/soup-request-data.xml"/>
-    <xi:include href="xml/soup-cache.xml"/>
-  </chapter>
-
   <index>
     <title>Index</title>
   </index>
diff --git a/docs/reference/libsoup-2.4-sections.txt b/docs/reference/libsoup-2.4-sections.txt
index 39e8288a..03d35d4b 100644
--- a/docs/reference/libsoup-2.4-sections.txt
+++ b/docs/reference/libsoup-2.4-sections.txt
@@ -35,6 +35,11 @@ SoupChunkAllocator
 soup_message_set_chunk_allocator
 <SUBSECTION>
 soup_message_disable_feature
+soup_message_get_soup_request
+<SUBSECTION>
+SoupMessagePriority
+soup_message_get_priority
+soup_message_set_priority
 <SUBSECTION>
 SOUP_MESSAGE_METHOD
 SOUP_MESSAGE_URI
@@ -44,9 +49,12 @@ SOUP_MESSAGE_STATUS_CODE
 SOUP_MESSAGE_REASON_PHRASE
 SOUP_MESSAGE_SERVER_SIDE
 SOUP_MESSAGE_FIRST_PARTY
+SOUP_MESSAGE_PRIORITY
 SOUP_MESSAGE_REQUEST_BODY
+SOUP_MESSAGE_REQUEST_BODY_DATA
 SOUP_MESSAGE_REQUEST_HEADERS
 SOUP_MESSAGE_RESPONSE_BODY
+SOUP_MESSAGE_RESPONSE_BODY_DATA
 SOUP_MESSAGE_RESPONSE_HEADERS
 SOUP_MESSAGE_TLS_CERTIFICATE
 SOUP_MESSAGE_TLS_ERRORS
@@ -193,13 +201,14 @@ SOUP_STATUS_IS_SUCCESSFUL
 SOUP_STATUS_IS_REDIRECTION
 SOUP_STATUS_IS_CLIENT_ERROR
 SOUP_STATUS_IS_SERVER_ERROR
-SoupKnownStatusCode
+SoupStatus
 soup_status_get_phrase
 soup_status_proxify
 <SUBSECTION>
 SOUP_HTTP_ERROR
 <SUBSECTION Private>
 soup_http_error_quark
+SoupKnownStatusCode
 </SECTION>
 
 <SECTION>
@@ -241,6 +250,8 @@ SOUP_SERVER_TLS_CERTIFICATE
 SOUP_SERVER_ASYNC_CONTEXT
 SOUP_SERVER_RAW_PATHS
 SOUP_SERVER_SERVER_HEADER
+SOUP_SERVER_HTTP_ALIASES
+SOUP_SERVER_HTTPS_ALIASES
 <SUBSECTION Standard>
 SOUP_SERVER
 SOUP_IS_SERVER
@@ -370,6 +381,7 @@ SOUP_ADDRESS_NAME
 SOUP_ADDRESS_PHYSICAL
 SOUP_ADDRESS_PORT
 SOUP_ADDRESS_SOCKADDR
+SOUP_ADDRESS_PROTOCOL
 <SUBSECTION Standard>
 SOUP_ADDRESS
 SOUP_IS_ADDRESS
@@ -386,11 +398,26 @@ SoupAddressClass
 <TITLE>SoupSession</TITLE>
 SoupSession
 <SUBSECTION>
+soup_session_new
+soup_session_new_with_options
+<SUBSECTION>
+soup_session_request
+soup_session_request_uri
+soup_session_request_http
+soup_session_request_http_uri
+SoupRequestError
+SOUP_REQUEST_ERROR
+<SUBSECTION>
 SoupSessionCallback
 soup_session_queue_message
 soup_session_requeue_message
 soup_session_send_message
 soup_session_cancel_message
+<SUBSECTION>
+soup_session_send
+soup_session_send_async
+soup_session_send_finish
+<SUBSECTION>
 soup_session_prefetch_dns
 soup_session_prepare_for_uri
 soup_session_abort
@@ -410,15 +437,18 @@ soup_session_remove_feature_by_type
 soup_session_get_features
 soup_session_get_feature
 soup_session_get_feature_for_message
+soup_session_has_feature
 <SUBSECTION>
 SOUP_SESSION_PROXY_URI
+SOUP_SESSION_PROXY_RESOLVER
 SOUP_SESSION_MAX_CONNS
 SOUP_SESSION_MAX_CONNS_PER_HOST
-SOUP_SESSION_USE_NTLM
-SOUP_SESSION_SSL_CA_FILE
-SOUP_SESSION_SSL_USE_SYSTEM_CA_FILE
 SOUP_SESSION_TLS_DATABASE
+SOUP_SESSION_SSL_USE_SYSTEM_CA_FILE
+SOUP_SESSION_SSL_CA_FILE
+SOUP_SESSION_SSL_STRICT
 SOUP_SESSION_ASYNC_CONTEXT
+SOUP_SESSION_USE_THREAD_CONTEXT
 SOUP_SESSION_TIMEOUT
 SOUP_SESSION_IDLE_TIMEOUT
 SOUP_SESSION_USER_AGENT
@@ -427,10 +457,9 @@ SOUP_SESSION_ADD_FEATURE_BY_TYPE
 SOUP_SESSION_REMOVE_FEATURE_BY_TYPE
 SOUP_SESSION_ACCEPT_LANGUAGE
 SOUP_SESSION_ACCEPT_LANGUAGE_AUTO
-SOUP_SESSION_SSL_STRICT
 SOUP_SESSION_HTTP_ALIASES
 SOUP_SESSION_HTTPS_ALIASES
-SOUP_SESSION_USE_THREAD_CONTEXT
+SOUP_SESSION_LOCAL_ADDRESS
 <SUBSECTION Standard>
 SOUP_IS_SESSION
 SOUP_IS_SESSION_CLASS
@@ -440,11 +469,13 @@ SOUP_SESSION_GET_CLASS
 SOUP_TYPE_SESSION
 SoupSessionClass
 soup_session_get_type
+soup_request_error_quark
 <SUBSECTION Private>
 SoupConnection
 SoupConnectionState
 SoupMessageQueue
 SoupMessageQueueItem
+SOUP_SESSION_USE_NTLM
 </SECTION>
 
 <SECTION>
@@ -521,6 +552,7 @@ soup_auth_get_info
 <SUBSECTION>
 soup_auth_authenticate
 soup_auth_is_authenticated
+soup_auth_is_ready
 <SUBSECTION>
 soup_auth_get_authorization
 soup_auth_get_protection_space
@@ -551,6 +583,23 @@ soup_auth_save_password
 </SECTION>
 
 <SECTION>
+<FILE>soup-auth-manager</FILE>
+<TITLE>SoupAuthManager</TITLE>
+SoupAuthManager
+SOUP_TYPE_AUTH_MANAGER
+soup_auth_manager_use_auth
+<SUBSECTION Standard>
+SoupAuthManagerPrivate
+SoupAuthManagerClass
+SOUP_AUTH_MANAGER
+SOUP_IS_AUTH_MANAGER
+SOUP_AUTH_MANAGER_CLASS
+SOUP_IS_AUTH_MANAGER_CLASS
+SOUP_AUTH_MANAGER_GET_CLASS
+soup_auth_manager_get_type
+</SECTION>
+
+<SECTION>
 <FILE>soup-socket</FILE>
 <TITLE>SoupSocket</TITLE>
 SoupSocket
@@ -571,6 +620,7 @@ soup_socket_is_connected
 <SUBSECTION>
 soup_socket_get_local_address
 soup_socket_get_remote_address
+soup_socket_get_fd
 <SUBSECTION>
 SoupSocketIOStatus
 soup_socket_read
@@ -599,12 +649,6 @@ SOUP_SOCKET_CLASS
 SOUP_IS_SOCKET_CLASS
 SOUP_SOCKET_GET_CLASS
 SoupSocketClass
-<SUBSECTION Private>
-soup_socket_get_fd
-soup_socket_handshake_async
-soup_socket_handshake_sync
-soup_socket_get_gsocket
-soup_socket_get_iostream
 </SECTION>
 
 <SECTION>
@@ -631,6 +675,7 @@ SOUP_URI_SCHEME_HTTPS
 SOUP_URI_SCHEME_DATA
 SOUP_URI_SCHEME_FILE
 SOUP_URI_SCHEME_FTP
+SOUP_URI_SCHEME_RESOURCE
 soup_uri_uses_default_port
 SOUP_URI_IS_VALID
 SOUP_URI_VALID_FOR_HTTP
@@ -656,8 +701,6 @@ soup_uri_get_fragment
 <SUBSECTION Standard>
 SOUP_TYPE_URI
 soup_uri_get_type
-<SUBSECTION Private>
-uri_decoded_copy
 </SECTION>
 
 <SECTION>
@@ -705,8 +748,6 @@ soup_add_completion
 soup_add_idle
 soup_add_io_watch
 soup_add_timeout
-<SUBSECTION>
-soup_ssl_supported
 <SUBSECTION Private>
 soup_date_copy
 SOUP_TYPE_DATE
@@ -721,6 +762,7 @@ SOUP_CHAR_HTTP_SEPARATOR
 SOUP_CHAR_URI_GEN_DELIMS
 SOUP_CHAR_URI_PERCENT_ENCODED
 SOUP_CHAR_URI_SUB_DELIMS
+soup_ssl_supported
 </SECTION>
 
 <SECTION>
@@ -927,6 +969,27 @@ soup_multipart_get_type
 </SECTION>
 
 <SECTION>
+<FILE>soup-multipart-input-stream</FILE>
+<TITLE>SoupMultipartInputStream</TITLE>
+SoupMultipartInputStream
+soup_multipart_input_stream_new
+<SUBSECTION>
+soup_multipart_input_stream_get_headers
+soup_multipart_input_stream_next_part
+soup_multipart_input_stream_next_part_async
+soup_multipart_input_stream_next_part_finish
+<SUBSECTION Standard>
+SOUP_IS_MULTIPART_INPUT_STREAM
+SOUP_IS_MULTIPART_INPUT_STREAM_CLASS
+SOUP_MULTIPART_INPUT_STREAM
+SOUP_MULTIPART_INPUT_STREAM_CLASS
+SOUP_MULTIPART_INPUT_STREAM_GET_CLASS
+SOUP_TYPE_MULTIPART_INPUT_STREAM
+soup_multipart_input_stream_get_type
+SoupMultipartInputStreamPrivate
+</SECTION>
+
+<SECTION>
 <FILE>soup-cookie-jar-text</FILE>
 <TITLE>SoupCookieJarText</TITLE>
 SoupCookieJarText
@@ -945,52 +1008,21 @@ soup_cookie_jar_text_get_type
 </SECTION>
 
 <SECTION>
-<INCLUDE>libsoup/soup-gnome.h</INCLUDE>
-<FILE>soup-cookie-jar-sqlite</FILE>
-<TITLE>SoupCookieJarSqlite</TITLE>
-SoupCookieJarSqlite
-soup_cookie_jar_sqlite_new
+<FILE>soup-cookie-jar-db</FILE>
+<TITLE>SoupCookieJarDB</TITLE>
+SoupCookieJarDB
+soup_cookie_jar_db_new
 <SUBSECTION>
-SOUP_COOKIE_JAR_SQLITE_FILENAME
-<SUBSECTION Standard>
-SoupCookieJarSqliteClass
-SOUP_COOKIE_JAR_SQLITE
-SOUP_COOKIE_JAR_SQLITE_CLASS
-SOUP_COOKIE_JAR_SQLITE_GET_CLASS
-SOUP_TYPE_COOKIE_JAR_SQLITE
-SOUP_IS_COOKIE_JAR_SQLITE
-SOUP_IS_COOKIE_JAR_SQLITE_CLASS
-soup_cookie_jar_sqlite_get_type
-</SECTION>
-
-<SECTION>
-<FILE>soup-proxy-uri-resolver</FILE>
-<TITLE>SoupProxyURIResolver</TITLE>
-SoupProxyURIResolver
-SoupProxyURIResolverCallback
-soup_proxy_uri_resolver_get_proxy_uri_async
-soup_proxy_uri_resolver_get_proxy_uri_sync
-<SUBSECTION Standard>
-SoupProxyURIResolverInterface
-SOUP_IS_PROXY_URI_RESOLVER
-SOUP_IS_PROXY_URI_RESOLVER_CLASS
-SOUP_PROXY_URI_RESOLVER
-SOUP_PROXY_URI_RESOLVER_CLASS
-SOUP_PROXY_URI_RESOLVER_GET_CLASS
-SOUP_TYPE_PROXY_URI_RESOLVER
-soup_proxy_uri_resolver_get_type
-</SECTION>
-
-<SECTION>
-<INCLUDE>libsoup/soup-gnome.h</INCLUDE>
-<FILE>soup-gnome-features</FILE>
-SOUP_TYPE_GNOME_FEATURES_2_26
-SOUP_TYPE_PROXY_RESOLVER_GNOME
+SOUP_COOKIE_JAR_DB_FILENAME
 <SUBSECTION Standard>
-soup_proxy_resolver_gnome_get_type
-soup_gnome_features_2_26_get_type
-SOUP_TYPE_PASSWORD_MANAGER_GNOME
-soup_password_manager_gnome_get_type
+SoupCookieJarDBClass
+SOUP_COOKIE_JAR_DB
+SOUP_COOKIE_JAR_DB_CLASS
+SOUP_COOKIE_JAR_DB_GET_CLASS
+SOUP_TYPE_COOKIE_JAR_DB
+SOUP_IS_COOKIE_JAR_DB
+SOUP_IS_COOKIE_JAR_DB_CLASS
+soup_cookie_jar_db_get_type
 </SECTION>
 
 <SECTION>
@@ -999,6 +1031,7 @@ soup_password_manager_gnome_get_type
 SoupContentSniffer
 soup_content_sniffer_new
 soup_content_sniffer_sniff
+soup_content_sniffer_get_buffer_size
 <SUBSECTION Standard>
 SOUP_CONTENT_SNIFFER
 SOUP_CONTENT_SNIFFER_CLASS
@@ -1033,11 +1066,7 @@ SOUP_CACHE_GET_CLASS
 SoupCacheClass
 SoupCachePrivate
 <SUBSECTION Private>
-soup_cache_generate_conditional_request
-soup_cache_get_cacheability
 soup_cache_get_type
-soup_cache_has_response
-soup_cache_send_response
 SoupCacheResponse
 SoupCacheability
 </SECTION>
@@ -1074,30 +1103,6 @@ SOUP_IS_PROXY_RESOLVER_DEFAULT_CLASS
 </SECTION>
 
 <SECTION>
-<FILE>soup-requester</FILE>
-<TITLE>SoupRequester</TITLE>
-SoupRequester
-soup_requester_new
-soup_requester_request
-soup_requester_request_uri
-<SUBSECTION>
-SoupRequesterError
-SOUP_REQUESTER_ERROR
-<SUBSECTION Standard>
-soup_requester_get_type
-SoupRequesterClass
-SoupRequesterPrivate
-SOUP_TYPE_REQUESTER
-SOUP_REQUESTER
-SOUP_REQUESTER_CLASS
-SOUP_REQUESTER_GET_CLASS
-SOUP_IS_REQUESTER
-SOUP_IS_REQUESTER_CLASS
-<SUBSECTION Private>
-soup_requester_error_quark
-</SECTION>
-
-<SECTION>
 <FILE>soup-request</FILE>
 <TITLE>SoupRequest</TITLE>
 SoupRequest
@@ -1186,3 +1191,72 @@ SoupTLDError
 <SUBSECTION Private>
 soup_tld_error_quark
 </SECTION>
+
+<SECTION>
+<FILE>soup-version</FILE>
+<TITLE>Version Information</TITLE>
+soup_get_major_version
+soup_get_minor_version
+soup_get_micro_version
+soup_check_version
+<SUBSECTION>
+SOUP_MAJOR_VERSION
+SOUP_MINOR_VERSION
+SOUP_MICRO_VERSION
+SOUP_CHECK_VERSION
+<SUBSECTION>
+SOUP_VERSION_MIN_REQUIRED
+SOUP_VERSION_MAX_ALLOWED
+SOUP_VERSION_2_24
+SOUP_VERSION_2_26
+SOUP_VERSION_2_28
+SOUP_VERSION_2_30
+SOUP_VERSION_2_32
+SOUP_VERSION_2_34
+SOUP_VERSION_2_36
+SOUP_VERSION_2_38
+SOUP_VERSION_2_40
+SOUP_VERSION_2_42
+SOUP_VERSION_2_44
+SOUP_VERSION_2_46
+<SUBSECTION Private>
+SOUP_AVAILABLE_IN_2_24
+SOUP_AVAILABLE_IN_2_26
+SOUP_AVAILABLE_IN_2_28
+SOUP_AVAILABLE_IN_2_30
+SOUP_AVAILABLE_IN_2_32
+SOUP_AVAILABLE_IN_2_34
+SOUP_AVAILABLE_IN_2_36
+SOUP_AVAILABLE_IN_2_38
+SOUP_AVAILABLE_IN_2_40
+SOUP_AVAILABLE_IN_2_42
+SOUP_AVAILABLE_IN_2_44
+SOUP_AVAILABLE_IN_2_46
+SOUP_DEPRECATED_IN_2_24
+SOUP_DEPRECATED_IN_2_24_FOR
+SOUP_DEPRECATED_IN_2_26
+SOUP_DEPRECATED_IN_2_26_FOR
+SOUP_DEPRECATED_IN_2_28
+SOUP_DEPRECATED_IN_2_28_FOR
+SOUP_DEPRECATED_IN_2_30
+SOUP_DEPRECATED_IN_2_30_FOR
+SOUP_DEPRECATED_IN_2_32
+SOUP_DEPRECATED_IN_2_32_FOR
+SOUP_DEPRECATED_IN_2_34
+SOUP_DEPRECATED_IN_2_34_FOR
+SOUP_DEPRECATED_IN_2_36
+SOUP_DEPRECATED_IN_2_36_FOR
+SOUP_DEPRECATED_IN_2_38
+SOUP_DEPRECATED_IN_2_38_FOR
+SOUP_DEPRECATED_IN_2_40
+SOUP_DEPRECATED_IN_2_40_FOR
+SOUP_DEPRECATED_IN_2_42
+SOUP_DEPRECATED_IN_2_42_FOR
+SOUP_DEPRECATED_IN_2_44
+SOUP_DEPRECATED_IN_2_44_FOR
+SOUP_DEPRECATED_IN_2_46
+SOUP_DEPRECATED_IN_2_46_FOR
+SOUP_ENCODE_VERSION
+SOUP_VERSION_CUR_STABLE
+SOUP_VERSION_PREV_STABLE
+</SECTION>
diff --git a/docs/reference/request-howto.xml b/docs/reference/request-howto.xml
new file mode 100644
index 00000000..55a46431
--- /dev/null
+++ b/docs/reference/request-howto.xml
@@ -0,0 +1,184 @@
+<?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-request-howto">
+<refmeta>
+<refentrytitle>libsoup Client SoupRequest API</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>LIBSOUP Library</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>libsoup Client SoupRequest API</refname><refpurpose>Using
+libsoup with a mix of <literal>http</literal> and non-<literal>http</literal> URIs.</refpurpose>
+</refnamediv>
+
+<refsect2>
+<title><type>SoupRequest</type></title>
+
+<para>
+<link linkend="SoupRequest"><type>SoupRequest</type></link> is an
+abstract type representing a request for a particular URI. The
+<type>SoupRequest</type> API is an alternative to the <link
+linkend="SoupMessage"><type>SoupMessage</type></link>-based <link
+linkend="SoupSession"><type>SoupSession</type></link> APIs which may be
+useful to programs that want to deal with multiple kinds of URIs.
+</para>
+
+<para>
+<type>SoupRequest</type> officially became part of the
+<application>libsoup</application> API in 2.42 with the addition of
+<link
+linkend="soup-session-request"><function>soup_session_request</function></link>
+and the related functions. However, parts of it are also available as
+far back as <application>libsoup</application> 2.34 via the
+(now-deprecated) <type>SoupRequester</type> session feature, if you
+define <literal>LIBSOUP_USE_UNSTABLE_REQUEST_API</literal> before
+including the <application>libsoup</application> headers.
+</para>
+
+<para>
+Additionally, before <application>libsoup</application> 2.42, the
+<type>SoupRequest</type> API was the only way to stream an HTTP
+response body via <link
+linkend="GInputStream"><type>GInputStream</type></link>. As of 2.42,
+there are streaming APIs based on <type>SoupMessage</type> (<link
+linkend="soup-session-send"><function>soup_session_send</function></link>
+and <link
+linkend="soup-session-send-async"><function>soup_session_send_async</function></link>),
+so applications that are using <type>SoupRequest</type> with only
+<literal>http</literal> and <literal>https</literal> URIs can be
+ported to those APIs now.
+</para>
+
+</refsect2>
+
+<refsect2>
+<title>Creating a SoupRequest</title>
+
+<para>
+There are four <type>SoupSession</type> methods for creating
+<type>SoupRequest</type>s:
+</para>
+
+<itemizedlist>
+    <listitem>
+	<para>
+	    <link linkend="soup-session-request"><function>soup_session_request</function></link>
+	    takes an arbitrary URI as a string, and returns a <link
+	    linkend="SoupRequest"><type>SoupRequest</type></link>.
+	</para>
+    </listitem>
+    <listitem>
+	<para>
+	    <link linkend="soup-session-request-uri"><function>soup_session_request_uri</function></link>
+	    takes an arbitrary URI as a <link linkend="SoupURI"><type>SoupURI</type></link>,
+	    and returns a <link linkend="SoupRequest"><type>SoupRequest</type></link>.
+	</para>
+    </listitem>
+    <listitem>
+	<para>
+	    <link linkend="soup-session-request-http"><function>soup_session_request_http</function></link>
+	    takes an HTTP method and an <literal>http</literal> or <literal>https</literal> URI as a string, and returns a <link
+	    linkend="SoupRequestHTTP"><type>SoupRequestHTTP</type></link>.
+	</para>
+    </listitem>
+    <listitem>
+	<para>
+	    <link linkend="soup-session-request-http-uri"><function>soup_session_request_http_uri</function></link>
+	    takes an HTTP method and an <literal>http</literal> or <literal>https</literal> URI as a <link linkend="SoupURI"><type>SoupURI</type></link>,
+	    and returns a <link linkend="SoupRequestHTTP"><type>SoupRequestHTTP</type></link>.
+	</para>
+    </listitem>
+</itemizedlist>
+
+</refsect2>
+
+<refsect2>
+<title>Sending a SoupRequest</title>
+
+<para>
+Once you have created a <type>SoupRequest</type>, you can send it with
+either <link
+linkend="soup-request-send"><function>soup_request_send</function></link>
+or <link
+linkend="soup-request-send-async"><function>soup_request_send_async</function></link>.
+This will provide you with a <link
+linkend="GInputStream"><type>GInputStream</type></link> which you can
+read to get the response body.
+</para>
+
+<para>
+After sending, you can use <link
+linkend="soup-request-get-content-length"><function>soup_request_get_content_length</function></link>
+and <link
+linkend="soup-request-get-content-type"><function>soup_request_get_content_type</function></link>
+to get information about the response body.
+</para>
+
+<para>
+As with the streaming <type>SoupMessage</type>-based APIs,
+<function>soup_request_send</function> and
+<function>soup_request_send_async</function> only return errors if a
+transport-level problem occurs (eg, it could not connect to the host,
+or the request was cancelled). In the case of an HTTP request, use the
+message's <structfield>status_code</structfield> field to determine
+whether the request was successful or not at the HTTP level (ie, "<literal>200
+OK</literal>" vs "<literal>401 Bad Request</literal>"). (You can call <link
+linkend="soup-request-http-get-message"><function>soup_request_http_get_message</function></link>
+to get the request's corresponding <link
+linkend="SoupMessage"><type>SoupMessage</type></link>, to look at the
+status code or other HTTP metadata.)
+</para>
+
+</refsect2>
+
+<refsect2>
+<title>Supported URI types, and adding your own</title>
+
+<para>
+Different URI types are implemented by different subclasses of
+<type>SoupRequest</type>. <application>libsoup</application> currently
+implements three <type>SoupRequest</type> classes:
+</para>
+
+<variablelist>
+    <varlistentry>
+	<term><link linkend="SoupRequestHTTP"><type>SoupRequestHTTP</type></link></term>
+	<listitem><para>
+	    Handles <literal>http</literal> and
+	    <literal>https</literal> URI.
+	</para></listitem>
+    </varlistentry>
+    <varlistentry>
+	<term><link linkend="SoupRequestData"><type>SoupRequestData</type></link></term>
+	<listitem><para>
+	    Handles <literal>data</literal> URIs containing inline data.
+	</para></listitem>
+    </varlistentry>
+    <varlistentry>
+	<term><link linkend="SoupRequestFile"><type>SoupRequestFile</type></link></term>
+	<listitem><para>
+	    Handles <literal>file</literal> and
+	    <link linkend="GResource"><literal>resource</literal></link> URIs.
+	    If you request a URI corresponding to a directory, this
+	    will generate an HTML listing of the directory.
+	</para></listitem>
+    </varlistentry>
+</variablelist>
+
+<para>
+You can add additional URI types by implementing your own
+<type>SoupRequest</type> subclass; set the
+<type>SoupRequestClass</type>'s <structfield>schemes</structfield>
+field to point to a <literal>NULL</literal>-terminated array of scheme
+names, implement the various <type>SoupRequest</type> methods, and
+then register the type with your <type>SoupSession</type> by calling
+<link linkend="soup-session-add-feature-by-type"><function>soup_session_add_feature_by_type</function></link>
+and passing the <link linkend="GType"><type>GType</type></link> of
+your request class.
+</para>
+
+</refsect2>
+
+</refentry>
diff --git a/docs/reference/server-howto.xml b/docs/reference/server-howto.xml
index 76c19182..05fb0c05 100644
--- a/docs/reference/server-howto.xml
+++ b/docs/reference/server-howto.xml
@@ -100,7 +100,7 @@ to set a callback to handle certain URI paths.
 
 <informalexample><programlisting>
 	soup_server_add_handler (server, "/foo", server_callback,
-				 data, destroy_notify);
+	                         data, destroy_notify);
 </programlisting></informalexample>
 
 <para>
@@ -131,11 +131,11 @@ A handler callback looks something like this:
 <informalexample><programlisting>
 static void
 server_callback (SoupServer        *server,
-		 SoupMessage       *msg, 
-		 const char        *path,
-		 GHashTable        *query,
-		 SoupClientContext *client,
-		 gpointer           user_data)
+                 SoupMessage       *msg, 
+                 const char        *path,
+                 GHashTable        *query,
+                 SoupClientContext *client,
+                 gpointer           user_data)
 {
 	...
 }
@@ -192,11 +192,11 @@ data available at once.
 <informalexample><programlisting>
 static void
 server_callback (SoupServer        *server,
-		 SoupMessage       *msg, 
-		 const char        *path,
-		 GHashTable        *query,
-		 SoupClientContext *client,
-		 gpointer           user_data)
+                 SoupMessage       *msg, 
+                 const char        *path,
+                 GHashTable        *query,
+                 SoupClientContext *client,
+                 gpointer           user_data)
 {
 	MyServerData *server_data = user_data;
 	const char *mime_type;
@@ -219,7 +219,7 @@ server_callback (SoupServer        *server,
 
 	soup_message_set_status (msg, SOUP_STATUS_OK);
 	soup_message_set_response (msg, mime_type, SOUP_MEMORY_COPY,
-				   body->data, body->len);
+	                           body->data, body->len);
 }
 </programlisting></informalexample>
 
@@ -264,7 +264,7 @@ is emitted indicating that the previous one was written successfully.)
 
 <para>
 The <emphasis role="bold"><literal>simple-proxy</literal></emphasis>
-example in the <literal>tests/</literal> directory gives an example of
+example in the <literal>examples/</literal> directory gives an example of
 using <literal>chunked</literal> encoding.
 </para>
 
@@ -308,8 +308,8 @@ passed to the <literal>server_callback</literal>:
 <informalexample><programlisting>
 static gboolean
 auth_callback (SoupAuthDomain *domain, SoupMessage *msg,
-	       const char *username, const char *password,
-	       gpointer user_data)
+               const char *username, const char *password,
+               gpointer user_data)
 {
 	MyServerData *server_data = user_data;
 	MyUserData *user;
@@ -360,8 +360,8 @@ domains.
 <para>
 If you want to require authentication for some requests under a
 certain path, but not all of them (eg, you want to authenticate
-<literal>PUT</literal>s, but not <literal>GET</literal>s), use a 
-<link
+<literal>PUT</literal> requests, but not <literal>GET</literal>
+requests), use a <link
 linkend="SoupAuthDomainFilter"><type>SoupAuthDomainFilter</type></link>.
 </para>
 
diff --git a/docs/reference/session-porting.xml b/docs/reference/session-porting.xml
new file mode 100644
index 00000000..67a433a1
--- /dev/null
+++ b/docs/reference/session-porting.xml
@@ -0,0 +1,221 @@
+<?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>
+      The new
+      <link linkend="SoupSession--proxy-resolver"><type>"proxy-resolver"</type></link>
+      property is now initialized to the default
+      <link linkend="GProxyResolver"><type>GProxyResolver</type></link>,
+      meaning that it will automatically use the user's system proxy
+      configuration. This replaces the use of the
+      <link linkend="SoupProxyResolverDefault"><type>SoupProxyResolverDefault</type></link>,
+      session feature in earlier releases. You can set this property to
+      <literal>NULL</literal> if you don't want to use proxies, and the
+      <link linkend="SoupSession--proxy-uri"><type>"proxy-uri"</type></link>
+      property still works if you want to use a single proxy for all requests.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+      Every session gets a
+      <link linkend="SoupContentDecoder"><type>SoupContentDecoder</type></link>
+      attached to it by default, meaning that it will automatically
+      handle (and request) "gzip"- and "deflate"-encoded response
+      bodies.
+    </para>
+  </listitem>
+</itemizedlist>
+
+</refsect2>
+
+<refsect2 id="behavior">
+<title>Differences in feature behavior</title>
+
+<para>
+If you are using NTLM authentication, the new <type>SoupSession</type>
+behaves slightly differently from the old session types.
+</para>
+
+<para>
+First, the deprecated <link
+linkend="SOUP-SESSION-USE-NTLM:CAPS"><literal>SOUP_SESSION_USE_NTLM</literal></link>
+property is no longer supported. If you want to add support for NTLM
+to a session, call <link
+linkend="soup-session-add-feature-by-type"><function>soup_session_add_feature_by_type()</function></link>,
+passing <link
+linkend="SOUP-TYPE-AUTH-NTLM:CAPS"><literal>SOUP_TYPE_AUTH_NTLM</literal></link>.
+</para>
+
+<para>
+Second, with the old session types, enabling NTLM would cause all
+(otherwise-unauthenticated) requests to be sent with an NTLM request
+in the <literal>Authorization</literal> 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 <type>SoupSession</type>, this no longer
+happens. If you want the old behavior, you need to call <link
+linkend="soup-auth-manager-use-auth"><function>soup_auth_manager_use_auth()</function></link>
+for each host to "preload" the NTLM authentication:
+</para>
+
+<informalexample><programlisting>
+	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);
+</programlisting></informalexample>
+
+</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>