"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 

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 

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="SOUP-SESSION-MAX-CONNS:CAPS"><literal>SOUP_SESSION_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="SOUP-SESSION-MAX-CONNS-PER-HOST:CAPS"><literal>SOUP_SESSION_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="SOUP-SESSION-USER-AGENT:CAPS"><literal>SOUP_SESSION_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="SOUP-SESSION-ACCEPT-LANGUAGE:CAPS"><literal>SOUP_SESSION_ACCEPT_LANGUAGE</literal></link>

	and <link linkend="SOUP-SESSION-ACCEPT-LANGUAGE-AUTO:CAPS"><literal>SOUP_SESSION_ACCEPT_LANGUAGE_AUTO</literal></link></term>

	<listitem><para>

	    Allow you to set an Accept-Language header on all outgoing

	    requests. <literal>SOUP_SESSION_ACCEPT_LANGUAGE</literal>

	    takes a list of language tags to use, while

	    <literal>SOUP_SESSION_ACCEPT_LANGUAGE_AUTO</literal>

	    automatically generates the list from the user's locale

	    settings.

	</para></listitem>

    </varlistentry>

    <varlistentry>

	<term><link linkend="SOUP-SESSION-HTTP-ALIASES:CAPS"><literal>SOUP_SESSION_HTTP_ALIASES</literal></link>

	and <link linkend="SOUP-SESSION-HTTPS-ALIASES:CAPS"><literal>SOUP_SESSION_HTTPS_ALIASES</literal></link></term>

	<listitem><para>

	    Allow you to tell the session to recognize additional URI

	    schemes as aliases for "<literal>http</literal>" or

	    <literal>https</literal>. You can set this if you are

	    using URIs with schemes like "<literal>dav</literal>" or

	    "<literal>webcal</literal>" (and in particular, you need

	    to set this if the server you are talking to might return

	    redirects with such a scheme).

	</para></listitem>

    </varlistentry>

    <varlistentry>

	<term><link linkend="SOUP-SESSION-PROXY-RESOLVER:CAPS"><literal>SOUP_SESSION_PROXY_RESOLVER</literal></link> and <link linkend="SOUP-SESSION-PROXY-URI:CAPS"><literal>SOUP_SESSION_PROXY_URI</literal></link></term>

	<listitem>

	    <para>

		<link linkend="SOUP-SESSION-PROXY-RESOLVER:CAPS"><literal>SOUP_SESSION_PROXY_RESOLVER</literal></link>

		specifies a 

		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 

		linkend="g-proxy-resolver-get-default"><function>g_proxy_resolver_get_default</function></link>,

		so you do not need to set it yourself.

	    </para>

	    <para>

		Alternatively, if you want all requests to go through a

		single proxy, you can set 

		linkend="SOUP-SESSION-PROXY-URI:CAPS"><literal>SOUP_SESSION_PROXY_URI</literal></link>.

	    </para>

	</listitem>

    </varlistentry>

    <varlistentry>

	<term><link linkend="SOUP-SESSION-ADD-FEATURE:CAPS"><literal>SOUP_SESSION_ADD_FEATURE</literal></link> and <link linkend="SOUP-SESSION-ADD-FEATURE-BY-TYPE:CAPS"><literal>SOUP_SESSION_ADD_FEATURE_BY_TYPE</literal></link></term>

	<listitem><para>

	    These allow you to specify 

	    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 

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 

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 

linkend="SoupSessionFeature"><type>SoupSessionFeature</type></link>s,

which can be added to a session, via the 

linkend="SOUP-SESSION-ADD-FEATURE:CAPS"><literal>SOUP_SESSION_ADD_FEATURE</literal></link>

and 

linkend="SOUP-SESSION-ADD-FEATURE-BY-TYPE:CAPS"><literal>SOUP_SESSION_ADD_FEATURE_BY_TYPE</literal></link>

options at session-construction-time, or afterward via the 

linkend="soup-session-add-feature"><function>soup_session_add_feature</function></link>

and 

linkend="soup-session-add-feature-by-type"><function>soup_session_add_feature_by_type</function></link>

functions.

</para>

<para>

A 

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 

linkend="SoupContentSniffer"><type>SoupContentSniffer</type></link>),

and the "add_feature" property/function to add features that must be

constructed first (such as 

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 (

		SOUP_SESSION_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 

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 

linkend="SoupMessage">SoupMessage</link>, 

linkend="SoupMessageHeaders">SoupMessageHeaders</link>, and 

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-2.4-HTML-Form-Support">HTML

forms</link>, as well as 

linkend="libsoup-2.4-XMLRPC-Support">XML-RPC</link>.)

</para>

<para>

You can also use 

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 

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 

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 

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 

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 be 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, 

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>

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 

linkend="soup-message-headers-get"><function>soup_message_headers_get</function></link>

and 

linkend="soup-message-headers-foreach"><function>soup_message_headers_foreach</function></link>.

</para>

<para>

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, 

linkend="soup-message-headers-get-content-type"><function>soup_message_headers_get_content_type</function></link>.

There are several generic methods such as 

linkend="soup-header-parse-param-list"><function>soup_header_parse_param_list</function></link>

(for parsing an attribute-list-type header) and 

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 

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 

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 

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 

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 

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 

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 

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. It shows how to use the 

	linkend="SoupMessageFlags"><literal>SOUP_MESSAGE_OVERWRITE_CHUNKS</literal></link>

	flag when reading a message to save memory by processing each

	chunk of the message as it is read, rather than accumulating

	them all into a single buffer to process all at the end.

    </para></listitem>

</itemizedlist>

<para>

More complicated examples are available in GNOME git.

</para>

</refsect2>

</refentry>