diff options
Diffstat (limited to 'docs/reference/client-howto.xml')
-rw-r--r-- | docs/reference/client-howto.xml | 535 |
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, &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, &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> |