GNOME.org
 

[libsoup] docs: Update server docs

commit 8fe7e1ad461b375ad97247cc050d0622fa0547bc
Author: Patrick Griffis <pgriffis igalia com>
Date:   Sat Jan 9 14:38:16 2021 -0600

    docs: Update server docs

 docs/reference/migrating-from-libsoup-2.xml |  2 +-
 docs/reference/server-howto.xml             | 39 ++++++++++++-----------------
 libsoup/server/soup-server.c                | 30 +++++++++++-----------
 3 files changed, 31 insertions(+), 40 deletions(-)
---
diff --git a/docs/reference/migrating-from-libsoup-2.xml b/docs/reference/migrating-from-libsoup-2.xml
index 81b060ae..5242742f 100644
--- a/docs/reference/migrating-from-libsoup-2.xml
+++ b/docs/reference/migrating-from-libsoup-2.xml
@@ -55,7 +55,7 @@ linkend="soup-uri-decode-data-uri"><function>soup_uri_decode_data_uri()</functio
                     <para><type>SoupDate</type> has been replaced by <link 
linkend="GDateTime"><type>GDateTime</type></link></para>
                 </listitem>
                 <listitem>
-                    <para><literal>SoupSession:ssl-strict</literal> has been removed in favor of using the 
<link linkend="soup-message--accept-certificate"><literal>SoupMessage:accept-certificate</literal></link> 
signal.</para>
+                    <para><literal>SoupSession:ssl-strict</literal> has been removed in favor of using the 
<link linkend="SoupMessage-accept-certificate"><literal>SoupMessage:accept-certificate</literal></link> 
signal.</para>
                 </listitem>
                 <listitem>
                     <para><literal>soup_session_cancel_message()</literal> has been removed</para>
diff --git a/docs/reference/server-howto.xml b/docs/reference/server-howto.xml
index 712f68c1..0d6545fd 100644
--- a/docs/reference/server-howto.xml
+++ b/docs/reference/server-howto.xml
@@ -3,13 +3,13 @@
                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd";>
 <refentry id="libsoup-server-howto">
 <refmeta>
-<refentrytitle>libsoup Server Basics</refentrytitle>
+<refentrytitle>Server Basics</refentrytitle>
 <manvolnum>3</manvolnum>
 <refmiscinfo>LIBSOUP Library</refmiscinfo>
 </refmeta>
 
 <refnamediv>
-<refname>libsoup Server Basics</refname><refpurpose>Server-side tutorial</refpurpose>
+<refname>libsoup Server Basics</refname>
 </refnamediv>
 
 <refsect2>
@@ -159,10 +159,9 @@ A handler callback looks something like this:
 <informalexample><programlisting>
 static void
 server_callback (SoupServer        *server,
-                 SoupMessage       *msg, 
+                 SoupServerMessage *msg, 
                  const char        *path,
                  GHashTable        *query,
-                 SoupClientContext *client,
                  gpointer           user_data)
 {
        ...
@@ -176,10 +175,7 @@ linkend="soup-server-add-handler"><function>soup_server_add_handler</function></
 <literal>path</literal> is the path (from <literal>msg</literal>'s
 URI), and <literal>query</literal> contains the result of parsing the
 URI query field. (It is <literal>NULL</literal> if there was no
-query.) <literal>client</literal> is a <link
-linkend="SoupClientContext"><type>SoupClientContext</type></link>,
-which contains additional information about the client (including its
-IP address, and whether or not it used HTTP authentication).
+query.)
 </para>
 
 <para>
@@ -193,16 +189,14 @@ on the message before returning from the callback. This will delay
 sending a response until you call <link
 linkend="soup-server-unpause-message"><function>soup_server_unpause_message</function></link>.
 (You must also connect to the <link
-linkend="SoupMessage-finished">finished</link> signal on the message
+linkend="SoupServerMessage-finished">finished</link> signal on the message
 in this case, so that you can break off processing if the client
 unexpectedly disconnects before you start sending the data.)
 </para>
 
 <para>
 To set the response status, call <link
-linkend="soup-message-set-status"><function>soup_message_set_status</function></link>
-or <link
-linkend="soup-message-set-status-full"><function>soup_message_set_status_full</function></link>.
+linkend="soup-server-message-set-status"><function>soup_server_message_set_status</function></link>.
 If the response requires a body, you must decide whether to use
 <literal>Content-Length</literal> encoding (the default), or
 <literal>chunked</literal> encoding.
@@ -220,18 +214,17 @@ data available at once.
 <informalexample><programlisting>
 static void
 server_callback (SoupServer        *server,
-                 SoupMessage       *msg, 
+                 SoupServerMessage *msg, 
                  const char        *path,
                  GHashTable        *query,
-                 SoupClientContext *client,
                  gpointer           user_data)
 {
        MyServerData *server_data = user_data;
        const char *mime_type;
        GByteArray *body;
 
-       if (soup_message_get_method (msg) != SOUP_METHOD_GET) {
-               soup_message_set_status (msg, SOUP_STATUS_NOT_IMPLEMENTED);
+       if (soup_server_message_get_method (msg) != SOUP_METHOD_GET) {
+               soup_server_message_set_status (msg, SOUP_STATUS_NOT_IMPLEMENTED, NULL);
                return;
        }
 
@@ -241,13 +234,13 @@ server_callback (SoupServer        *server,
        body = g_hash_table_lookup (server_data->bodies, path);
        mime_type = g_hash_table_lookup (server_data->mime_types, path);
        if (!body || !mime_type) {
-               soup_message_set_status (msg, SOUP_STATUS_NOT_FOUND);
+               soup_server_message_set_status (msg, SOUP_STATUS_NOT_FOUND, NULL);
                return;
        }
 
-       soup_message_set_status (msg, SOUP_STATUS_OK);
-       soup_message_set_response (msg, mime_type, SOUP_MEMORY_COPY,
-                                  body->data, body->len);
+       soup_server_message_set_status (msg, SOUP_STATUS_OK, NULL);
+       soup_server_message_set_response (msg, mime_type, SOUP_MEMORY_COPY,
+                                         body->data, body->len);
 }
 </programlisting></informalexample>
 
@@ -281,12 +274,12 @@ because I/O is automatically paused when doing a
 
 <para>
 When using chunked encoding, you must also connect to the <link
-linkend="SoupMessage-finished">finished</link> signal on the message,
+linkend="SoupServerMessage-finished">finished</link> signal on the message,
 so that you will be notified if the client disconnects between two
 chunks; <type>SoupServer</type> will unref the message if that
 happens, so you must stop adding new chunks to the response at that
 point. (An alternate possibility is to write each new chunk only when
-the <link linkend="SoupMessage-wrote-chunk">wrote_chunk</link> signal
+the <link linkend="SoupServerMessage-wrote-chunk">wrote_chunk</link> signal
 is emitted indicating that the previous one was written successfully.)
 </para>
 
@@ -335,7 +328,7 @@ passed to the <literal>server_callback</literal>:
 
 <informalexample><programlisting>
 static gboolean
-auth_callback (SoupAuthDomain *domain, SoupMessage *msg,
+auth_callback (SoupAuthDomain *domain, SoupServerMessage *msg,
                const char *username, const char *password,
                gpointer user_data)
 {
diff --git a/libsoup/server/soup-server.c b/libsoup/server/soup-server.c
index 7b415899..555a3bc1 100644
--- a/libsoup/server/soup-server.c
+++ b/libsoup/server/soup-server.c
@@ -49,9 +49,9 @@
  * an existing persistent connection), the #SoupServer will emit
  * #SoupServer::request-started and then begin processing the request
  * as described below, but note that once the message is assigned a
- * #SoupMessage:status-code, then callbacks after that point will be
+ * status-code, then callbacks after that point will be
  * skipped. Note also that it is not defined when the callbacks happen
- * relative to various #SoupMessage signals.
+ * relative to various #SoupServerMessage signals.
  *
  * Once the headers have been read, #SoupServer will check if there is
  * a #SoupAuthDomain (qv) covering the Request-URI; if so, and if the
@@ -506,7 +506,7 @@ soup_server_class_init (SoupServerClass *server_class)
         * SoupServer:server-header:
         *
         * If non-%NULL, the value to use for the "Server" header on
-        * #SoupMessage<!-- -->s processed by this server.
+        * #SoupServerMessage<!-- -->s processed by this server.
         *
         * The Server header is the server equivalent of the
         * User-Agent header, and provides information about the
@@ -1615,13 +1615,11 @@ get_or_create_handler (SoupServer *server, const char *exact_path)
  * For requests under @path (that have not already been assigned a
  * status code by a #SoupAuthDomain, an early server handler, or a
  * signal handler), @callback will be invoked after receiving the
- * request body; the message's #SoupMessage:method,
- * #SoupMessage:request-headers, and #SoupMessage:request-body fields
- * will be filled in.
+ * request body; the #SoupServerMessage<!-- -->'s method, request-headers,
+ * and request-body properties will be set.
  *
  * After determining what to do with the request, the callback must at
- * a minimum call soup_message_set_status() (or
- * soup_message_set_status_full()) on the message to set the response
+ * a minimum call soup_server_message_set_status() on the message to set the response
  * status code. Additionally, it may set response headers and/or fill
  * in the response body.
  *
@@ -1634,7 +1632,7 @@ get_or_create_handler (SoupServer *server, const char *exact_path)
  *
  * To send the response body a bit at a time using "chunked" encoding,
  * first call soup_message_headers_set_encoding() to set
- * %SOUP_ENCODING_CHUNKED on the #SoupMessage:response-headers. Then call
+ * %SOUP_ENCODING_CHUNKED on the response-headers. Then call
  * soup_message_body_append() (or soup_message_body_append_bytes))
  * to append each chunk as it becomes ready, and
  * soup_server_unpause_message() to make sure it's running. (The
@@ -1682,22 +1680,22 @@ soup_server_add_handler (SoupServer            *server,
  * For requests under @path (that have not already been assigned a
  * status code by a #SoupAuthDomain or a signal handler), @callback
  * will be invoked after receiving the request headers, but before
- * receiving the request body; the message's #SoupMessage:method and
- * #SoupMessage:request-headers fields will be filled in.
+ * receiving the request body; the message's method and
+ * request-headers properties will be set.
  *
  * Early handlers are generally used for processing requests with
  * request bodies in a streaming fashion. If you determine that the
  * request will contain a message body, normally you would call
  * soup_message_body_set_accumulate() on the message's
- * #SoupMessage:request-body to turn off request-body accumulation,
- * and connect to the message's #SoupMessage::got-chunk signal to
+ * request-body to turn off request-body accumulation,
+ * and connect to the message's #SoupServerMessage::got-chunk signal to
  * process each chunk as it comes in.
  *
  * To complete the message processing after the full message body has
- * been read, you can either also connect to #SoupMessage::got-body,
+ * been read, you can either also connect to #SoupServerMessage::got-body,
  * or else you can register a non-early handler for @path as well. As
- * long as you have not set the #SoupMessage:status-code by the time
- * #SoupMessage::got-body is emitted, the non-early handler will be
+ * long as you have not set the status-code by the time
+ * #SoupServerMessage::got-body is emitted, the non-early handler will be
  * run as well.
  *
  * Since: 2.50
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]