summaryrefslogtreecommitdiff
path: root/docs/reference/client-howto.xml
diff options
context:
space:
mode:
Diffstat (limited to 'docs/reference/client-howto.xml')
-rw-r--r--docs/reference/client-howto.xml535
1 files changed, 0 insertions, 535 deletions
diff --git a/docs/reference/client-howto.xml b/docs/reference/client-howto.xml
deleted file mode 100644
index 898cfaf1..00000000
--- a/docs/reference/client-howto.xml
+++ /dev/null
@@ -1,535 +0,0 @@
-<?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-client-howto">
-<refmeta>
-<refentrytitle>libsoup Client Basics</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>LIBSOUP Library</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<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>
-The first step in using the client API is to create a <link
-linkend="SoupSession"><type>SoupSession</type></link>. The session object
-encapsulates all of the state that <application>libsoup</application>
-is keeping on behalf of your program; cached HTTP connections,
-authentication information, etc.
-</para>
-
-<para>
-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>
-
-<variablelist>
- <varlistentry>
- <term><link linkend="SoupSession:max-conns"><literal>"max-conns"</literal></link></term>
- <listitem><para>
- Allows you to set the maximum total number of connections
- 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.) The default value is 10.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term><link linkend="SoupSession:max-conns-per-host"><literal>"max-conns-per-host"</literal></link></term>
- <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. The default value is 2.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term><link linkend="SoupSession:user-agent"><literal>"user-agent"</literal></link></term>
- <listitem><para>
- Allows you to set a User-Agent string that will be sent
- on all outgoing requests.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term><link linkend="SoupSession:accept-language"><literal>"accept-language"</literal></link>
- and <link linkend="SoupSession:accept-language-auto"><literal>"accept-language-auto"</literal></link></term>
- <listitem><para>
- Allow you to set an Accept-Language header on all outgoing
- requests. <literal>"accept-language"</literal>
- takes a list of language tags to use, while
- <literal>"accept-language-auto"</literal>
- automatically generates the list from the user's locale
- settings.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term><link linkend="SoupSession:proxy-resolver"><literal>"proxy-resolver"</literal></link></term>
- <listitem>
- <para>
- <link linkend="SoupSession:proxy-resolver"><literal>"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>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><link linkend="SoupSession:add-feature"><literal>"add-feature"</literal></link> and <link linkend="SOUP-SESSION-ADD-FEATURE-BY-TYPE:CAPS"><literal>"add-feature-by-type"</literal></link></term>
- <listitem><para>
- These allow you to specify <link
- linkend="SoupSessionFeature"><type>SoupSessionFeature</type></link>s
- (discussed <link linkend="session-features">below</link>)
- to add at construct-time.
- </para></listitem>
- </varlistentry>
-</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-new"><function>soup_session_new</function></link>,
-which takes no arguments.
-</para>
-
-</refsect2>
-
-<refsect2 id="session-features">
-<title>Session features</title>
-
-<para>
-Additional session functionality is provided as <link
-linkend="SoupSessionFeature"><type>SoupSessionFeature</type></link>s,
-which can be added to a session, via the <link
-linkend="SoupSession:add-feature"><literal>"add-feature"</literal></link>
-and <link
-linkend="SoupSession:add-feature-by-type"><literal>"add-feature-by-type"</literal></link>
-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.
-</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>
- <varlistentry>
- <term><link linkend="SoupLogger"><type>SoupLogger</type></link></term>
- <listitem><para>
- A debugging aid, which logs all of libsoup's HTTP traffic
- to <literal>stdout</literal> (or another place you specify).
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <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, and
- <type>SoupCookieJarDB</type> uses a
- <application>SQLite</application> database.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term><link linkend="SoupContentSniffer"><type>SoupContentSniffer</type></link></term>
- <listitem><para>
- 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>
-
-<para>
-Use the "add_feature_by_type" property/function to add features that
-don't require any configuration (such as <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
-application might do something like the following:
-</para>
-
-<informalexample><programlisting>
- session = soup_session_new_with_options (
- "add-feature-by-type", SOUP_TYPE_CONTENT_SNIFFER,
- NULL);
-
- if (debug_level) {
- SoupLogger *logger;
-
- logger = soup_logger_new (debug_level, -1);
- soup_session_add_feature (session, SOUP_SESSION_FEATURE (logger));
- g_object_unref (logger);
- }
-</programlisting></informalexample>
-
-</refsect2>
-
-<refsect2>
-<title>Creating and Sending SoupMessages</title>
-
-<para>
-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>
-
-<informalexample><programlisting>
- SoupMessage *msg;
-
- msg = soup_message_new ("GET", "http://example.com/");
-</programlisting></informalexample>
-
-<para>
-In more complicated cases, you can use various <link
-linkend="SoupMessage">SoupMessage</link>, <link
-linkend="SoupMessageHeaders">SoupMessageHeaders</link>, and <link
-linkend="SoupMessageBody">SoupMessageBody</link> methods to set the
-request headers and body of the message:
-</para>
-
-<informalexample><programlisting>
- SoupMessage *msg;
-
- 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_message_headers_append (msg->request_headers, "Referer", referring_url);
-</programlisting></informalexample>
-
-<para>
-(Although this is a bad example, because
-<application>libsoup</application> actually has convenience methods
-for dealing with <link linkend="libsoup-3.0-HTML-Form-Support">HTML
-forms</link>.)
-</para>
-
-<para>
-You can also use <link
-linkend="soup-message-set-flags"><function>soup_message_set_flags</function></link>
-to change some default behaviors. For example, by default,
-<type>SoupSession</type> automatically handles responses from the
-server that redirect to another URL. If you would like to handle these
-yourself, you can set the <link linkend="SOUP-MESSAGE-NO-REDIRECT:CAPS"><literal>SOUP_MESSAGE_NO_REDIRECT</literal></link>
-flag.
-</para>
-
-<refsect3>
-<title>Sending a Message Synchronously</title>
-
-<para>
-To send a message and wait for the response, use <link
-linkend="soup-session-send"><function>soup_session_send</function></link>:
-</para>
-
-<informalexample><programlisting>
- GInputStream *stream;
- GError *error = NULL;
-
- stream = soup_session_send (session, msg, cancellable, &amp;error);
-</programlisting></informalexample>
-
-<para>
-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>
-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>
-
-<refsect3>
-<title>Sending a Message Asynchronously</title>
-
-<para>
-To send a message asynchronously, use <link
-linkend="soup-session-send-async"><function>soup_session_send_async</function></link>:
-</para>
-
-<informalexample><programlisting>
-{
- ...
- soup_session_send_async (session, msg, cancellable, my_callback, my_callback_data);
- ...
-}
-
-static void
-my_callback (GObject *object, GAsyncResult *result, gpointer user_data)
-{
- 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 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>
-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>
-<link
-linkend="soup-session-queue-message"><function>soup_session_queue_message</function></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>
-
-</refsect2>
-
-<refsect2>
-<title>Processing the Response</title>
-
-<para>
-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-list"><function>soup_message_headers_get_list</function></link>
-and <link
-linkend="soup-message-headers-foreach"><function>soup_message_headers_foreach</function></link>.
-</para>
-
-<para>
-<link
-linkend="SoupMessageHeaders"><type>SoupMessageHeaders</type></link>
-automatically parses several important headers in
-<structfield>response_headers</structfield> for you and provides
-specialized accessors for them. Eg, <link
-linkend="soup-message-headers-get-content-type"><function>soup_message_headers_get_content_type</function></link>.
-There are several generic methods such as <link
-linkend="soup-header-parse-param-list"><function>soup_header_parse_param_list</function></link>
-(for parsing an attribute-list-type header) and <link
-linkend="soup-header-contains"><function>soup_header_contains</function></link>
-(for quickly testing if a list-type header contains a particular
-token). These handle the various syntactical oddities of parsing HTTP
-headers much better than functions like
-<function>g_strsplit</function> or <function>strstr</function>.
-</para>
-
-</refsect2>
-
-<refsect2>
-<title>Handling Authentication</title>
-
-<para>
-<type>SoupSession</type> handles most of the details of HTTP
-authentication for you. If it receives a 401 ("Unauthorized") or 407
-("Proxy Authentication Required") response, the session will emit the
-<link linkend="SoupSession-authenticate">authenticate</link> signal,
-providing you with a <link
-linkend="SoupAuth"><type>SoupAuth</type></link> object indicating the
-authentication type ("Basic", "Digest", or "NTLM") and the realm name
-provided by the server. If you have a username and password available
-(or can generate one), call <link
-linkend="soup-auth-authenticate"><function>soup_auth_authenticate</function></link>
-to give the information to libsoup. The session will automatically
-requeue the message and try it again with that authentication
-information. (If you don't call
-<function>soup_auth_authenticate</function>, the session will just
-return the message to the application with its 401 or 407 status.)
-</para>
-
-<para>
-If the server doesn't accept the username and password provided, the
-session will emit <link
-linkend="SoupSession-authenticate">authenticate</link> again, with the
-<literal>retrying</literal> parameter set to <literal>TRUE</literal>. This lets the
-application know that the information it provided earlier was
-incorrect, and gives it a chance to try again. If this
-username/password pair also doesn't work, the session will contine to
-emit <literal>authenticate</literal> again and again until the
-provided username/password successfully authenticates, or until the
-signal handler fails to call <link
-linkend="soup-auth-authenticate"><function>soup_auth_authenticate</function></link>,
-at which point <application>libsoup</application> will allow the
-message to fail (with status 401 or 407).
-</para>
-
-<para>
-If you need to handle authentication asynchronously (eg, to pop up a
-password dialog without recursively entering the main loop), you can
-do that as well. Just call <link
-linkend="soup-session-pause-message"><function>soup_session_pause_message</function></link>
-on the message before returning from the signal handler, and
-<function>g_object_ref</function> the <type>SoupAuth</type>. Then,
-later on, after calling <function>soup_auth_authenticate</function>
-(or deciding not to), call <link
-linkend="soup-session-unpause-message"><function>soup_session_unpause_message</function></link>
-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>
-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>
-<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>
-
-<refsect2>
-<title>Sample Programs</title>
-
-<para>
-A few sample programs are available in the
-<application>libsoup</application> sources, in the
-<literal>examples</literal> directory:
-</para>
-
-<itemizedlist>
- <listitem><para>
- <emphasis role="bold"><literal>get</literal></emphasis> is a simple command-line
- HTTP GET utility using the asynchronous API.
- </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.
- </para></listitem>
-</itemizedlist>
-
-<para>
-More complicated examples are available in GNOME git.
-</para>
-
-</refsect2>
-
-</refentry>