SoupServer: add exciting new APIs, deprecate musty old oneswip/server

FIXME: server-howto

3 files changed, 98 insertions, 44 deletions

diff --git a/docs/reference/libsoup-2.4-docs.sgml b/docs/reference/libsoup-2.4-docs.sgml
index ca92b864..1554c0e7 100644
--- a/docs/reference/libsoup-2.4-docs.sgml
+++ b/docs/reference/libsoup-2.4-docs.sgml
@@ -34,6 +34,7 @@
     <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-server-deprecated.xml"/>
     <xi:include href="xml/soup-session.xml"/>
     <xi:include href="xml/soup-session-async.xml"/>
     <xi:include href="xml/soup-session-sync.xml"/>
diff --git a/docs/reference/libsoup-2.4-sections.txt b/docs/reference/libsoup-2.4-sections.txt
index 6b193101..998794de 100644
--- a/docs/reference/libsoup-2.4-sections.txt
+++ b/docs/reference/libsoup-2.4-sections.txt
@@ -214,25 +214,25 @@ SoupKnownStatusCode
 <TITLE>SoupServer</TITLE>
 SoupServer
 soup_server_new
-soup_server_is_https
-soup_server_get_port
-soup_server_get_listener
-soup_server_run
-soup_server_run_async
-soup_server_quit
+<SUBSECTION>
+SoupServerListenOptions
+soup_server_listen
+soup_server_listen_all
+soup_server_listen_local
 soup_server_disconnect
-soup_server_get_async_context
+soup_server_is_https
 <SUBSECTION>
 SoupServerCallback
 soup_server_add_handler
 soup_server_remove_handler
 <SUBSECTION>
 SoupClientContext
-soup_client_context_get_socket
-soup_client_context_get_address
+soup_client_context_get_local_address
+soup_client_context_get_remote_address
 soup_client_context_get_host
 soup_client_context_get_auth_domain
 soup_client_context_get_auth_user
+soup_client_context_get_gsocket
 <SUBSECTION>
 soup_server_add_auth_domain
 soup_server_remove_auth_domain
@@ -240,12 +240,9 @@ soup_server_remove_auth_domain
 soup_server_pause_message
 soup_server_unpause_message
 <SUBSECTION>
-SOUP_SERVER_PORT
-SOUP_SERVER_INTERFACE
-SOUP_SERVER_SSL_CERT_FILE
-SOUP_SERVER_SSL_KEY_FILE
 SOUP_SERVER_TLS_CERTIFICATE
-SOUP_SERVER_ASYNC_CONTEXT
+SOUP_SERVER_TLS_CERT_FILE
+SOUP_SERVER_TLS_KEY_FILE
 SOUP_SERVER_RAW_PATHS
 SOUP_SERVER_SERVER_HEADER
 <SUBSECTION Standard>
@@ -262,6 +259,26 @@ soup_client_context_get_type
 </SECTION>
 
 <SECTION>
+<FILE>soup-server-deprecated</FILE>
+<TITLE>SoupServer deprecated API</TITLE>
+soup_server_get_port
+soup_server_get_listener
+soup_server_run
+soup_server_run_async
+soup_server_quit
+soup_server_get_async_context
+<SUBSECTION>
+soup_client_context_get_socket
+soup_client_context_get_address
+<SUBSECTION>
+SOUP_SERVER_PORT
+SOUP_SERVER_INTERFACE
+SOUP_SERVER_SSL_CERT_FILE
+SOUP_SERVER_SSL_KEY_FILE
+SOUP_SERVER_ASYNC_CONTEXT
+</SECTION>
+
+<SECTION>
 <FILE>soup-auth-domain</FILE>
 <TITLE>SoupAuthDomain</TITLE>
 SoupAuthDomain
diff --git a/docs/reference/server-howto.xml b/docs/reference/server-howto.xml
index 76c19182..79f4c285 100644
--- a/docs/reference/server-howto.xml
+++ b/docs/reference/server-howto.xml
@@ -25,54 +25,35 @@ linkend="SoupServer"><type>SoupServer</type></link>.
 You create the server with <link
 linkend="soup-server-new"><function>soup_server_new</function></link>,
 and as with the <type>SoupSession</type> constructor, you can specify
-various additional options:
+a few additional options:
 </para>
 
 <variablelist>
     <varlistentry>
-	<term><link linkend="SOUP-SERVER-PORT:CAPS"><literal>SOUP_SERVER_PORT</literal></link></term>
+	<term><link linkend="SOUP-SERVER-TLS-CERTIFICATE:CAPS"><literal>SOUP_SERVER_TLS_CERTIFICATE</literal></link></term>
 	<listitem><para>
-	    The TCP port to listen on. If <literal>0</literal> (or
-	    left unspecified), some unused port will be selected for
-	    you. (You can find out what port by calling <link
-	    linkend="soup-server-get-port"><function>soup_server_get_port</function></link>.
+	    A <link
+	    linkend="GTlsCertificate"><type>GTlsCertificate</type></link>
+	    (containing a private key) that will be used when handling
+	    HTTPS requests on the server.
 	</para></listitem>
     </varlistentry>
     <varlistentry>
-	<term><link linkend="SOUP-SERVER-INTERFACE:CAPS"><literal>SOUP_SERVER_INTERFACE</literal></link></term>
+	<term><link linkend="SOUP-SERVER-TLS-CERT-FILE:CAPS"><literal>SOUP_SERVER_TLS_CERT_FILE</literal></link></term>
 	<listitem><para>
-	    A <link linkend="SoupAddress"><type>SoupAddress</type></link>,
-	    specifying the IP address of the network interface to run
-	    the server on. If <literal>NULL</literal> (or left
-	    unspecified), the server will listen on all interfaces.
+	    Points to a file containing a TLS (aka SSL) certificate to
+	    use when handling HTTPS requests.
 	</para></listitem>
     </varlistentry>
     <varlistentry>
-	<term><link linkend="SOUP-SERVER-SSL-CERT-FILE:CAPS"><literal>SOUP_SERVER_SSL_CERT_FILE</literal></link></term>
-	<listitem><para>
-	    Points to a file containing an SSL certificate to use. If
-	    this is set, then the server will speak HTTPS; otherwise
-	    it will speak HTTP.
-	</para></listitem>
-    </varlistentry>
-    <varlistentry>
-	<term><link linkend="SOUP-SERVER-SSL-KEY-FILE:CAPS"><literal>SOUP_SERVER_SSL_KEY_FILE</literal></link></term>
+	<term><link linkend="SOUP-SERVER-TLS-KEY-FILE:CAPS"><literal>SOUP_SERVER_TLS_KEY_FILE</literal></link></term>
 	<listitem><para>
 	    Points to a file containing the private key for the
-	    <literal>SOUP_SERVER_SSL_CERT_FILE</literal>. (It may
+	    <literal>SOUP_SERVER_TLS_CERT_FILE</literal>. (It may
 	    point to the same file.)
 	</para></listitem>
     </varlistentry>
     <varlistentry>
-	<term><link linkend="SOUP-SERVER-ASYNC-CONTEXT:CAPS"><literal>SOUP_SERVER_ASYNC_CONTEXT</literal></link></term>
-	<listitem><para>
-	    A <link linkend="GMainContext"><type>GMainContext</type></link> which
-	    the server will use for asynchronous operations. This can
-	    be set if you want to use a SoupServer in a thread
-	    other than the main thread.
-	</para></listitem>
-    </varlistentry>
-    <varlistentry>
 	<term><link linkend="SOUP-SERVER-RAW-PATHS:CAPS"><literal>SOUP_SERVER_RAW_PATHS</literal></link></term>
 	<listitem><para>
 	    Set this to <literal>TRUE</literal> if you don't want
@@ -84,6 +65,61 @@ various additional options:
     </varlistentry>
 </variablelist>
 
+<para>
+  If you are using <literal>SOUP_SERVER_TLS_CERT_FILE</literal> and
+  <literal>SOUP_SERVER_TLS_KEY_FILE</literal>, you should create the
+  server with <link
+  linkend="g-initable-new"><function>g_initable_new</function></link>
+  rather than <link
+  linkend="soup-server-new"><function>soup_server_new</function></link>,
+  so that you can get back a proper error if the specified files can't
+  be read.
+</para>
+
+</refsect2>
+
+<refsect2>
+<title>Adding Listening Sockets</title>
+
+<para>
+  To tell the server where to listen, call <link
+  linkend="soup-server-listen"><function>soup_server_listen</function></link>
+  (to listen on a specific <link
+  linkend="GSocketAddress"><type>GSocketAddress</type></link>), <link
+  linkend="soup-server-listen-all"><function>soup_server_listen_all</function></link>
+  (to listen on a given port on all network interfaces), or <link
+  linkend="soup-server-listen-local"><function>soup_server_listen_local</function></link>
+  (to listen to a given port on the loopback interface only). You can
+  call any of these functions multiple times, to set up multiple
+  listening sockets.
+</para>
+
+<para>
+  To set up an HTTPS server, you must have set <link
+  linkend="SOUP-SERVER-TLS-CERT-FILE:CAPS"><literal>SOUP_SERVER_TLS_CERT_FILE</literal></link>
+  or <link
+  linkend="SOUP-SERVER-TLS-CERTIFICATE:CAPS"><literal>SOUP_SERVER_TLS_CERTIFICATE</literal></link>,
+  and then you can pass <link
+  linkend="SOUP-SERVER-LISTEN-HTTPS:CAPS"><literal>SOUP_SERVER_LISTEN_HTTPS</literal></link>
+  as an option to <link
+  linkend="soup-server-listen"><function>soup_server_listen</function></link>,
+  etc.
+</para>
+
+<para>
+  By default, servers listen for both IPv4 and IPv6 connections; if
+  you don't want this, use the <link
+  linkend="SOUP-SERVER-LISTEN-IPV4-ONLY:CAPS"><literal>SOUP_SERVER_LISTEN_IPV4_ONLY</literal></link>
+  or <link
+  linkend="SOUP-SERVER-LISTEN-IPV6-ONLY:CAPS"><literal>SOUP_SERVER_LISTEN_IPV6_ONLY</literal></link>
+  options.
+</para>
+
+<para>
+  The server runs asynchronously, in the thread-default
+  <link linkend="GMainContext"><type>GMainContext</type></link> of the
+  thread in which the "listen" calls were made.
+</para>
 </refsect2>
 
 <refsect2>