path: root/docs/reference/client-howto.xml

<?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>Soup Client Basics</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>LIBSOUP Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Soup Client Basics</refname><refpurpose>Client-side tutorial</refpurpose>
</refnamediv>

<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>
There are two subclasses of <link
linkend="SoupSession"><type>SoupSession</type></link> that you can use, with
slightly different behavior:
</para>

<itemizedlist>
    <listitem><para>
	<link linkend="SoupSessionAsync"><type>SoupSessionAsync</type></link>,
	which uses callbacks and the glib main loop to provide
	asynchronous I/O.
    </para></listitem>

    <listitem><para>
	<link linkend="SoupSessionSync"><type>SoupSessionSync</type></link>,
	which uses blocking I/O rather than callbacks, making it more
	suitable for threaded applications.
    </para></listitem>
</itemizedlist>

<para>
If you want to do a mix of synchronous and asynchronous I/O, you will
need to create two different session objects.
</para>

<para>
When you create the session (with <link
linkend="soup-session-async-new-with-options"><function>soup_session_async_new_with_options</function></link>
or <link
linkend="soup-session-sync-new-with-options"><function>soup_session_sync_new_with_options</function></link>),
you can specify various additional options:
</para>

<variablelist>
    <varlistentry>
	<term><link linkend="SOUP-SESSION-PROXY-URI:CAPS"><literal>SOUP_SESSION_PROXY_URI</literal></link></term>
	<listitem><para>
	    Tells the session to use an HTTP proxy rather than
	    directly connecting to HTTP servers.
	</para></listitem>
    </varlistentry>
    <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.)
	</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.
	</para></listitem>
    </varlistentry>
    <varlistentry>
	<term><link linkend="SOUP-SESSION-USE-NTLM:CAPS"><literal>SOUP_SESSION_USE_NTLM</literal></link></term>
	<listitem><para>
	    If <literal>TRUE</literal>, then Microsoft NTLM
	    authentication will be used if available (and will be
	    preferred to HTTP Basic or Digest authentication).
	    If <literal>FALSE</literal>, NTLM authentication won't be
	    used, even if it's the only authentication type available.
	    (NTLM works differently from the standard HTTP
	    authentication types, so it needs to be handled
	    specially.)
	</para></listitem>
    </varlistentry>
    <varlistentry>
	<term><link linkend="SOUP-SESSION-SSL-CA-FILE:CAPS"><literal>SOUP_SESSION_SSL_CA_FILE</literal></link></term>
	<listitem><para>
	    Points to a file containing certificates for recognized
	    SSL Certificate Authorities. If this is set, then HTTPS
	    connections will be checked against these authorities, and
	    rejected if they can't be verified. (Otherwise all SSL
	    certificates will be accepted automatically.)
	</para></listitem>
    </varlistentry>
    <varlistentry>
	<term><link linkend="SOUP-SESSION-ASYNC-CONTEXT:CAPS"><literal>SOUP_SESSION_ASYNC_CONTEXT</literal></link></term>
	<listitem><para>
	    A <link linkend="GMainContext">GMainContext</link> which
	    the session will use for asynchronous operations. This can
	    be set if you want to use a <type>SoupSessionAsync</type>
	    in a thread other than the main thread.
	</para></listitem>
    </varlistentry>
</variablelist>

<para>
If you don't need to specify any options, you can just use <link
linkend="soup-session-async-new"><function>soup_session_async_new</function></link> or
<link linkend="soup-session-sync-new"><function>soup_session_sync_new</function></link>,
which take no arguments.
</para>

</refsect2>

<refsect2>
<title>Creating and Sending SoupMessages</title>

<para>
Once you have a session, you do HTTP traffic using <link
linkend="SoupMessage">SoupMessage</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> 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_BUFFER_USER_OWNED, formdata, strlen (formdata));
	soup_message_add_header (msg->request_headers, "Referer", referring_url);
</programlisting></informalexample>

<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-message"><function>soup_session_send_message</function></link>:
</para>

<informalexample><programlisting>
	guint status;

	status = soup_session_send (session, msg);
</programlisting></informalexample>

<para>
<literal>session</literal> can be either a <link
linkend="SoupSessionSync"><type>SoupSessionSync</type></link> or a
<link linkend="SoupSessionAsync"><type>SoupSessionAsync</type></link>;
if you use <function>soup_session_send_message</function> on an async
session, it will run the main loop itself until the message is
complete.
</para>

<para>
The return value from <function>soup_session_send</function> is a <link
linkend="soup-status">soup status code</link>, indicating either a
transport error that prevented the message from being sent, or the
HTTP status that was returned by the server in response to the
message.
</para>

</refsect3>

<refsect3>
<title>Sending a Message Asynchronously</title>

<para>
To send a message asynchronously (which can only be done if you're
using <link
linkend="SoupSessionAsync"><type>SoupSessionAsync</type></link>), use
<link linkend="soup-session-queue-message"><function>soup_session_queue_message</function></link>:
</para>

<informalexample><programlisting>
	...
	soup_session_queue_message (session, msg, my_callback, my_callback_data);
	...
}

static void
my_callback (SoupMessage *msg, gpointer user_data)
{
	/* Handle the response here */
}
</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 is complete,
<literal>callback</literal> will be invoked, along with the data you
passed to <function>soup_session_queue_message</function>.
</para>

</refsect3>

</refsect2>

<refsect2>
<title>Processing the Response</title>

<para>
Once you have received the response from the server, synchronously or
asynchronously, 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-get-header"><function>soup_message_get_header</function></link> and
<link
    linkend="soup-message-foreach-header"><function>soup_message_foreach_header</function></link>.
The response body (if any) is in the
<structfield>response</structfield> field.
</para>

<para>
If you send the message with <link
linkend="soup-session-queue-message"><function>soup_session_queue_message</function></link>,
<application>libsoup</application> will steal a reference to the
message object, and unref the message after the last callback is
invoked on it. So in the usual case, messages will be automatically
freed for you without you needing to do anything. Of course, this
won't work when using the synchronous API, since you will usually need
continue working with the message after calling <link
linkend="soup-session-send-message"><function>soup_session_send_message</function></link>,
so in that case, you must unref it explicitly when you are done with
it.
</para>

</refsect2>

<refsect2>
<title>Intermediate/Automatic Processing</title>

<para>
You can also connect to various <literal>SoupMessage</literal>
signals, or set up handlers using <link
linkend="soup-message-add-handler"><function>soup_message_add_handler</function></link>
and the other handler methods. Notably, <link
linkend="soup-message-add-header-handler"><function>soup_message_add_header_handler</function></link>,
<link linkend="soup-message-add-status-code-handler"><function>soup_message_add_status_code_handler</function></link>,
and
<link linkend="soup-message-add-status-class-handler"><function>soup_message_add_status_class_handler</function></link>
allow you to invoke a handler automatically for messages with certain
response headers or status codes. <type>SoupSession</type> uses
this internally to handle authentication and redirection.
</para>

<para>
When using the synchronous API, the callbacks and signal handlers will
be invoked during the call to <link
linkend="soup-session-send-message"><function>soup_session_send_message</function></link>.
</para>

<para>
To automatically set up handlers on all messages sent via a session,
you can create a <link
linkend="SoupMessageFilter">SoupMessageFilter</link> and attach it to
the session with <link
linkend="soup-session-add-filter"><function>soup_session_add_filter</function></link>.
</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,
indicating the authentication type ("Basic", "Digest", or "NTLM") and
the realm name provided by the server. You should connect to this
signal and, if possible, fill in the <parameter>username</parameter>
and <parameter>password</parameter> parameters with authentication
information. (The session will <function>g_free</function> the strings
when it is done with them.) If the handler doesn't fill in those
parameters, then the session will just return the message to the
application with its 401 or 407 status.
</para>

<para>
If the <literal>authenticate</literal> handler returns a username and
password, but the request still gets an authorization error using that
information, then the session will emit the <link
linkend="SoupSession-reauthenticate">reauthenticate</link> signal.
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>reauthenticate</literal> again and again until the
returned username/password successfully authentications, or until the
signal handler fails to provide a username, at which point
<application>libsoup</application> will allow the message to fail
(with status 401 or 407).
</para>

<para>
There are basically three ways an application might want to use
the signals:
</para>

<itemizedlist>
    <listitem><para>
	An interactive application that doesn't cache passwords could
	just connect both <literal>authenticate</literal> and
	<literal>reauthenticate</literal> to the same signal handler,
	which would ask the user for a username and password and then
	return that to soup. This handler would be called repeatedly
	until the provided information worked, or until it failed to
	return any information (eg, because the user hit "Cancel"
	instead of "OK").
    </para></listitem>

    <listitem><para>
	A slightly cleverer interactive application would look in its
	password cache from the <literal>authenticate</literal>
	handler, and return a password from there if one was
	available. If no password was cached, it would just call its
	<literal>reauthenticate</literal> handler to prompt the user.
	The <literal>reauthenticate</literal> handler would first
	clear any cached password for this host, auth type, and realm,
	then ask the user as in the case above, and then store that
	information in its cache before returning it to soup. (If the
	password turns out to be incorrect, then
	<literal>reauthenticate</literal> will be called again to
	force it to be uncached.)
    </para></listitem>

    <listitem><para>
	A non-interactive program that only has access to cached
	passwords would only connect to
	<literal>authenticate</literal>. If the username and password
	that <literal>authenticate</literal> returns fail, the session
	will emit <literal>reauthenticate</literal>, but since the
	application is not listening to that signal, no new username
	and password will be returned there, so the message will be
	returned to the application with a 401 or 407 status, which
	the application can deal with as it needs to.
    </para></listitem>
</itemizedlist>

</refsect2>

<refsect2>
<title>Sample Programs</title>

<para>
A few sample programs are available in the
<application>libsoup</application> sources:
</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>dict</literal></emphasis> and
	<emphasis role="bold"><literal>getbug</literal></emphasis> are trivial
	demonstrations of the <link
	linkend="SoupSoapMessage">SOAP</link> and <link
	linkend="SoupXmlrpcMessage">XMLRPC</link> interfaces,
	respectively.
    </para></listitem>

    <listitem><para>
	<emphasis role="bold"><literal>auth-test</literal></emphasis> shows how to use
	authentication handlers and status-code handlers, although in
	a fairly unusual way.
    </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 <link
	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 CVS. The <ulink
url="http://live.gnome.org/LibSoup"><application>libsoup</application>
pages</ulink> on the GNOME wiki include a <ulink
url="http://live.gnome.org/LibSoup/Users">list of applications using
<application>libsoup</application></ulink>.
</para>

</refsect2>

</refentry>