diff options
Diffstat (limited to 'docs/reference')
| -rw-r--r-- | docs/reference/libsoup-2.4-docs.sgml | 1 | ||||
| -rw-r--r-- | docs/reference/libsoup-2.4-sections.txt | 45 | ||||
| -rw-r--r-- | docs/reference/server-howto.xml | 96 |
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> |