[libsoup] docs: Add migration chapter
- From: Patrick Griffis <pgriffis src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [libsoup] docs: Add migration chapter
- Date: Mon, 7 Dec 2020 21:20:51 +0000 (UTC)
commit daed59a433c898e6fe06bc0974f9f1aa1ac45cce
Author: Patrick Griffis <pgriffis igalia com>
Date: Mon Dec 7 15:20:10 2020 -0600
docs: Add migration chapter
docs/reference/libsoup-3.0-docs.xml | 150 ++++++++++---------
docs/reference/meson.build | 5 +-
docs/reference/migrating-from-libsoup-2.xml | 214 ++++++++++++++++++++++++++++
3 files changed, 296 insertions(+), 73 deletions(-)
---
diff --git a/docs/reference/libsoup-3.0-docs.xml b/docs/reference/libsoup-3.0-docs.xml
index 88a6e0f8..bfa6971c 100644
--- a/docs/reference/libsoup-3.0-docs.xml
+++ b/docs/reference/libsoup-3.0-docs.xml
@@ -10,82 +10,90 @@
</releaseinfo>
</bookinfo>
- <chapter>
- <title>Tutorial</title>
- <xi:include href="build-howto.xml"/>
- <xi:include href="client-howto.xml"/>
- <xi:include href="server-howto.xml"/>
- </chapter>
+ <part>
+ <title>Overview</title>
+ <chapter>
+ <title>Tutorial</title>
+ <xi:include href="build-howto.xml"/>
+ <xi:include href="client-howto.xml"/>
+ <xi:include href="server-howto.xml"/>
+ </chapter>
- <chapter>
- <title>Core HTTP API</title>
- <xi:include href="xml/soup-cookie.xml"/>
- <xi:include href="xml/soup-message.xml"/>
- <xi:include href="xml/soup-message-headers.xml"/>
- <xi:include href="xml/soup-headers.xml"/>
- <xi:include href="xml/soup-method.xml"/>
- <xi:include href="xml/soup-multipart.xml"/>
- <xi:include href="xml/soup-multipart-input-stream.xml"/>
- <xi:include href="xml/soup-session.xml"/>
- <xi:include href="xml/soup-status.xml"/>
- </chapter>
+ <xi:include href="migrating-from-libsoup-2.xml"/>
+ </part>
- <chapter>
- <title>HTTP Server</title>
- <xi:include href="xml/soup-server.xml"/>
- <xi:include href="xml/soup-server-message.xml"/>
- <xi:include href="xml/soup-message-body.xml"/>
- </chapter>
+ <part>
+ <title>API Reference</title>
+ <chapter>
+ <title>Core HTTP API</title>
+ <xi:include href="xml/soup-cookie.xml"/>
+ <xi:include href="xml/soup-message.xml"/>
+ <xi:include href="xml/soup-message-headers.xml"/>
+ <xi:include href="xml/soup-headers.xml"/>
+ <xi:include href="xml/soup-method.xml"/>
+ <xi:include href="xml/soup-multipart.xml"/>
+ <xi:include href="xml/soup-multipart-input-stream.xml"/>
+ <xi:include href="xml/soup-session.xml"/>
+ <xi:include href="xml/soup-status.xml"/>
+ </chapter>
- <chapter>
- <title>Additional Features</title>
- <xi:include href="xml/soup-session-feature.xml"/>
- <xi:include href="xml/soup-content-decoder.xml"/>
- <xi:include href="xml/soup-content-sniffer.xml"/>
- <xi:include href="xml/soup-logger.xml"/>
- <section>
- <title>Authentication</title>
- <xi:include href="xml/soup-auth-manager.xml"/>
- <xi:include href="xml/soup-auth.xml"/>
- <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"/>
- </section>
- <section>
- <title>Caching</title>
- <xi:include href="xml/soup-cache.xml"/>
- </section>
- <section>
- <title>Cookie Storage Support</title>
- <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"/>
- </section>
- <section>
- <title>HSTS Support</title>
- <xi:include href="xml/soup-hsts-enforcer.xml"/>
- <xi:include href="xml/soup-hsts-enforcer-db.xml"/>
- <xi:include href="xml/soup-hsts-policy.xml"/>
- </section>
- </chapter>
+ <chapter>
+ <title>HTTP Server</title>
+ <xi:include href="xml/soup-server.xml"/>
+ <xi:include href="xml/soup-server-message.xml"/>
+ <xi:include href="xml/soup-message-body.xml"/>
+ </chapter>
- <chapter>
- <title>Web Services APIs</title>
- <xi:include href="xml/soup-form.xml"/>
- <section>
- <title>WebSocket Support</title>
- <xi:include href="xml/soup-websocket.xml"/>
- <xi:include href="xml/soup-websocket-extension.xml"/>
- </section>
- </chapter>
+ <chapter>
+ <title>Additional Features</title>
+ <xi:include href="xml/soup-session-feature.xml"/>
+ <xi:include href="xml/soup-content-decoder.xml"/>
+ <xi:include href="xml/soup-content-sniffer.xml"/>
+ <xi:include href="xml/soup-logger.xml"/>
+ <section>
+ <title>Authentication</title>
+ <xi:include href="xml/soup-auth-manager.xml"/>
+ <xi:include href="xml/soup-auth.xml"/>
+ <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"/>
+ </section>
+ <section>
+ <title>Caching</title>
+ <xi:include href="xml/soup-cache.xml"/>
+ </section>
+ <section>
+ <title>Cookie Storage Support</title>
+ <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"/>
+ </section>
+ <section>
+ <title>HSTS Support</title>
+ <xi:include href="xml/soup-hsts-enforcer.xml"/>
+ <xi:include href="xml/soup-hsts-enforcer-db.xml"/>
+ <xi:include href="xml/soup-hsts-policy.xml"/>
+ </section>
+ </chapter>
- <chapter>
- <title>Utility API</title>
- <xi:include href="xml/soup-date-utils.xml"/>
- <xi:include href="xml/soup-tld.xml"/>
- <xi:include href="xml/soup-uri-utils.xml"/>
- <xi:include href="xml/soup-version.xml"/>
- </chapter>
+ <chapter>
+ <title>Web Services APIs</title>
+ <xi:include href="xml/soup-form.xml"/>
+ <section>
+ <title>WebSocket Support</title>
+ <xi:include href="xml/soup-websocket.xml"/>
+ <xi:include href="xml/soup-websocket-extension.xml"/>
+ </section>
+ </chapter>
+
+ <chapter>
+ <title>Utility API</title>
+ <xi:include href="xml/soup-date-utils.xml"/>
+ <xi:include href="xml/soup-tld.xml"/>
+ <xi:include href="xml/soup-uri-utils.xml"/>
+ <xi:include href="xml/soup-version.xml"/>
+ </chapter>
+ </part>
<index id="api-index-full">
<title>Index of all symbols</title>
diff --git a/docs/reference/meson.build b/docs/reference/meson.build
index cd0468ca..b8982daf 100644
--- a/docs/reference/meson.build
+++ b/docs/reference/meson.build
@@ -67,6 +67,7 @@ gnome.gtkdoc('libsoup-3.0',
content_files: [
'build-howto.xml',
'client-howto.xml',
- 'server-howto.xml'
- ]
+ 'server-howto.xml',
+ 'migrating-from-libsoup-2.xml',
+ ],
)
diff --git a/docs/reference/migrating-from-libsoup-2.xml b/docs/reference/migrating-from-libsoup-2.xml
new file mode 100644
index 00000000..359a3473
--- /dev/null
+++ b/docs/reference/migrating-from-libsoup-2.xml
@@ -0,0 +1,214 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<?xml-model href="http://docbook.org/xml/5.1/rng/docbook.rng";
schematypens="http://relaxng.org/ns/structure/1.0";?>
+<?xml-model href="http://docbook.org/xml/5.1/sch/docbook.sch"; type="application/xml"
schematypens="http://purl.oclc.org/dsdl/schematron";?>
+<chapter xmlns="http://docbook.org/ns/docbook";
+ xmlns:xlink="http://www.w3.org/1999/xlink"; version="5.1">
+ <title>Migrating from libsoup 2</title>
+ <section>
+ <title>Removed features</title>
+ <para>This is a list of features that have been removed:<itemizedlist>
+ <listitem>
+ <para>XML-RPC support</para>
+ </listitem>
+ <listitem>
+ <para>Handling of <literal>file://</literal> and <literal>data://</literal>
+ URIs</para>
+ <para>You should use <link
+linkend="GFile"><type>GFile</type></link> for the former and <link
+linkend="soup-uri-decode-data-uri"><function>soup_uri_decode_data_uri()</function></link> for the
+ latter.</para>
+ </listitem>
+ <listitem>
+ <para><code>SOUP_LOGGER_LOG_BODY</code></para>
+ <para>You must log data as you read it.</para>
+ </listitem>
+ <listitem>
+ <para>Define aliases for property names</para>
+ <para>You must use the string name of properties directly which works in libsoup
+ 2 already.</para>
+ </listitem>
+ <listitem>
+ <para><literal>SoupSession:add-feature</literal> and
<literal>SoupSession:add-feature-by-type</literal></para>
+ <para>You must call <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>
directly.</para>
+ </listitem>
+ <listitem>
+ <para><type>SoupRequest</type></para>
+ <para>You should use the new <link
linkend="soup-session-read-uri"><function>soup_session_read_uri()</function></link> or
+ <link
linkend="soup-session-read-uri-async"><function>soup_session_read_uri_async()</function></link>
methods.</para>
+ </listitem>
+ <listitem>
+ <para><type>SoupAddress</type> has been replaced with <link
linkend="GInetAddress"><type>GInetAddress</type></link>
+ and <link linkend="GNetworkAddress"><type>GNetworkAddress</type></link></para>
+ </listitem>
+ <listitem>
+ <para><type>SoupSocket</type> has been removed</para>
+ </listitem>
+ <listitem>
+ <para><type>SoupProxyResolverDefault</type> is replaced by
+ <link
linkend="g-proxy-resolver-get-default"><function>g_proxy_resolver_get_default()</function></link></para>
+ </listitem>
+ <listitem>
+ <para><type>SoupBuffer</type> has been replaced by <link
linkend="GBytes"><type>GBytes</type></link> and <link
linkend="GBytesArray"><type>GBytesArray</type></link></para>
+ </listitem>
+ <listitem>
+ <para><type>SoupDate</type> has been replaced by <link
linkend="GDateTime"><type>GDateTime</type></link></para>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+ <section>
+ <title>Moved authenticate signal</title>
+ <para>The <literal>SoupSession::authenticate</literal> signal has simply been moved to
+ <link linkend="SoupMessage-authenticate"><literal>SoupMessage::authenticate</literal></link>,
its behavior is the same.</para>
+ </section>
+ <section>
+ <title>Structs are private</title>
+ <para>You can no longer directly access various structs such as SoupMessage. These are now
+ accessed by getters and setters. See below for direct conversions:<informaltable>
+ <tgroup cols="2">
+ <colspec colname="c1" colnum="1" colwidth="1*"/>
+ <colspec colname="c2" colnum="2" colwidth="1*"/>
+ <thead>
+ <row>
+ <entry>Struct field</entry>
+ <entry>Getter/Setter function</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>SoupMessage.method</entry>
+ <entry><link
linkend="soup-message-get-method"><function>soup_message_get_method()</function></link></entry>
+ </row>
+ <row>
+ <entry>SoupMessage.status_code</entry>
+ <entry><link
linkend="soup-message-get-status"><function>soup_message_get_status()</function></link></entry>
+ </row>
+ <row>
+ <entry>SoupMessage.reason_phrase</entry>
+ <entry><link
linkend="soup-message-get-reason-phrase"><function>soup_message_get_reason_phrase()</function></link></entry>
+ </row>
+ <row>
+ <entry>SoupMessage.uri</entry>
+ <entry><link
linkend="soup-message-get-uri"><function>soup_message_get_uri()</function></link>, <link
linkend="soup-message-set-uri"><function>soup_message_set_uri()</function></link></entry>
+ </row>
+ <row>
+ <entry>SoupMessage.request_headers</entry>
+ <entry><link
linkend="soup-message-get-request-headers"><function>soup_message_get_request_headers()</function></link></entry>
+ </row>
+ <row>
+ <entry>SoupMessage.response_headers</entry>
+ <entry><link
linkend="soup-message-get-response-headers"><function>soup_message_get_response_headers()</function></link></entry>
+ </row>
+ <row>
+ <entry>SoupMessage.request_body</entry>
+ <entry><link
linkend="soup-message-set-request-body"><function>soup_message_set_request_body()</function></link>,
+ <link
linkend="soup-message-set-request-body-from-bytes"><function>soup_message_set_request_body_from_bytes()</function></link></entry>
+ </row>
+ <row>
+ <entry>SoupMessage.response_body</entry>
+ <entry>See <link linkend="io-stream-based">section on IO</link> </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable></para>
+ <para>Similar struct changes exist for <link linkend="SoupCookie"><type>SoupCookie</type></link> but
have very straightforward
+ replacements.</para>
+ </section>
+ <section>
+ <title>URI type changed</title>
+ <para>The <type>SoupURI</type> type has been replaced with the <link
linkend="GUri"><type>GUri</type></link> type which has some
+ implications.</para>
+ <para>Creating a <link linkend="GUri"><type>GUri</type></link> is generally as simple as
<code>g_uri_parse (uri,
+ SOUP_HTTP_URI_FLAGS, NULL)</code>. You may want to add
+ <literal>G_URI_FLAGS_PARSE_RELAXED</literal> to accept input that used to be
+ considered valid.</para>
+ <para>Note that unlike <type>SoupURI</type> <link linkend="GUri"><type>GUri</type></link> is an
immutable type so you cannot change the contents
+ of one after it has been constructed.</para>
+ <para>The equivilent behavior to <code>soup_uri_to_string (uri, FALSE)</code> is
+ <code>g_uri_to_string (uri, G_URI_HIDE_PASSWORD)</code>.</para>
+ <para>Since GUri does not provide any function to check for equality
+ <link linkend="soup_uri_equal"><function>soup_uri_equal()</function></link> still
exists.</para>
+ <para>Sending a <literal>OPTIONS</literal> message with a path of <literal>*</literal> is no
+ longer a valid URI and has been replaced with SoupMessage:options-ping.</para>
+ </section>
+ <section>
+ <title>Status codes no longer used for internal errors</title>
+ <para>Previously <link linkend="SoupStatus"><type>SoupStatus</type></link> was used to hold libsoup
errors
+ (<code>SOUP_STATUS_IS_TRANSPORT_ERROR()</code>). Now all of these errors are
+ propagated up through the normal <link linkend="GError"><type>GError</type></link> method on the
various APIs to send messages.
+ Here is a mapping chart between the status codes and new errors:<informaltable>
+ <tgroup cols="2">
+ <colspec colname="c1" colnum="1" colwidth="1*"/>
+ <colspec colname="newCol4" colnum="2" colwidth="1*"/>
+ <thead>
+ <row>
+ <entry>Old Status Codes</entry>
+ <entry>New GError</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><code>SOUP_STATUS_CANCELLED</code></entry>
+ <entry>G_IO_ERROR_CANCELLED</entry>
+ </row>
+ <row>
+ <entry><code>SOUP_STATUS_MALFORMED</code></entry>
+ <entry>SOUP_SESSION_ERROR_PARSING, SOUP_SESSION_ERROR_ENCODING</entry>
+ </row>
+ <row>
+ <entry>SOUP_STATUS_TOO_MANY_REDIRECTS</entry>
+ <entry>SOUP_SESSION_ERROR_TOO_MANY_REDIRECTS</entry>
+ </row>
+ <row>
+ <entry/>
+ <entry>SOUP_SESSION_ERROR_BAD_URI</entry>
+ </row>
+ <row>
+ <entry/>
+ <entry>SOUP_SESSION_ERROR_UNSUPPORTED_URI_SCHEME</entry>
+ </row>
+ <row>
+ <entry/>
+ <entry>SOUP_SESSION_ERROR_TOO_MANY_RESTARTS</entry>
+ </row>
+ <row>
+ <entry/>
+ <entry>SOUP_SESSION_ERROR_REDIRECT_NO_LOCATION</entry>
+ </row>
+ <row>
+ <entry/>
+ <entry>SOUP_SESSION_ERROR_REDIRECT_BAD_URI</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable></para>
+ </section>
+ <section>
+ <title>Cancellation uses GCancellable</title>
+ <para>Pass a <link linkend="GCancellable"><type>GCancellable</type></link> to APIs and call <link
linkend="g_cancellable_cancel"><function>g_cancellable_cancel()</function></link> on them rather than
+ <function>soup_session_cancel_message()</function></para>
+ </section>
+ <section id="io-stream-based">
+ <title>All IO is now GIOStream based</title>
+ <para>Previously there were ways to allow libsoup to read data into buffers and for you to
+ read from those buffers such as <literal>SoupMessage:response-body</literal>,
+ <literal>SoupMessage:response-body-data</literal>.
<literal>SoupMessage::got-chunk</literal>.</para>
+ <para>libsoup no longer stores a buffer of data for you to read from and instead it returns
+ a <link linkend="GInputStream"><type>GInputStream</type></link> which you read from using normal
GIO APIs.</para>
+ <para>If you want to simply request a buffer and nothing more you can use the
+ <link
linkend="soup_session_load_uri_bytes"><function>soup_session_load_uri_bytes()</function></link> or
+ <link
linkend="soup_session_load_uri_bytes_async"><function>soup_session_load_uri_bytes_async()</function></link>
APIs.</para>
+ <para>This also applies to writing data where you can set a <link
linkend="GOutputStream"><type>GOutputStream</type></link> using
+ <link
linkend="soup_message_set_request_body"><function>soup_message_set_request_body()</function></link> or use
the convenience API
+ <link
linkend="soup_message_set_request_body_from_bytes"><function>soup_message_set_request_body_from_bytes()</function></link>
to use a GBytes
+ buffer.</para>
+ </section>
+ <section>
+ <title>Redirection is always handled internally</title>
+ <para>Previously a common pattern was using <code>SOUP_MESSAGE_NO_REDIRECT</code> and
+ manually handling re-queuing the message. This is now handled for you with the
+ <link linkend="SoupMessage-redirection"><literal>SoupMessage::redirection</literal></link>
signal where you can block or allow redirects and libsoup
+ handles the queueing.</para>
+ </section>
+</chapter>
+
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
