Soup Client Basics3LIBSOUP LibrarySoup Client BasicsClient-side tutorialCreating a SoupSession
The first step in using the client API is to create a SoupSession. The session object
encapsulates all of the state that libsoup
is keeping on behalf of your program; cached HTTP connections,
authentication information, etc.
There are two subclasses of SoupSession that you can use, with
slightly different behavior:
SoupSessionAsync,
which uses callbacks and the glib main loop to provide
asynchronous I/O.
SoupSessionSync,
which uses blocking I/O rather than callbacks, making it more
suitable for threaded applications.
If you want to do a mix of synchronous and asynchronous I/O, you will
need to create two different session objects.
When you create the session (with soup_session_async_new_with_options
or soup_session_sync_new_with_options),
you can specify various additional options:
SOUP_SESSION_PROXY_URI
Tells the session to use an HTTP proxy rather than
directly connecting to HTTP servers.
SOUP_SESSION_MAX_CONNS
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.)
SOUP_SESSION_MAX_CONNS_PER_HOST
Allows you to set the maximum total number of connections
the session will have open to a single
host at one time.
SOUP_SESSION_USE_NTLM
If TRUE, then Microsoft NTLM
authentication will be used if available (and will be
preferred to HTTP Basic or Digest authentication).
If FALSE, 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.)
SOUP_SESSION_SSL_CA_FILE
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.)
SOUP_SESSION_ASYNC_CONTEXT
A GMainContext which
the session will use for asynchronous operations. This can
be set if you want to use a SoupSessionAsync
in a thread other than the main thread.
If you don't need to specify any options, you can just use soup_session_async_new or
soup_session_sync_new,
which take no arguments.
Creating and Sending SoupMessages
Once you have a session, you do HTTP traffic using SoupMessage. In the simplest case, you
only need to create the message and it's ready to send:
SoupMessage *msg;
msg = soup_message_new ("GET", "http://example.com/");
In more complicated cases, you can use various SoupMessage methods to set the request
headers and body of the message:
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);
You can also use soup_message_set_flags
to change some default behaviors. For example, by default,
SoupSession automatically handles responses from the
server that redirect to another URL. If you would like to handle these
yourself, you can set the SOUP_MESSAGE_NO_REDIRECT
flag.
Sending a Message Synchronously
To send a message and wait for the response, use soup_session_send_message:
guint status;
status = soup_session_send (session, msg);
session can be either a SoupSessionSync or a
SoupSessionAsync;
if you use soup_session_send_message on an async
session, it will run the main loop itself until the message is
complete.
The return value from soup_session_send is a soup status code, 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.
Sending a Message Asynchronously
To send a message asynchronously (which can only be done if you're
using SoupSessionAsync), use
soup_session_queue_message:
...
soup_session_queue_message (session, msg, my_callback, my_callback_data);
...
}
static void
my_callback (SoupMessage *msg, gpointer user_data)
{
/* Handle the response here */
}
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,
callback will be invoked, along with the data you
passed to soup_session_queue_message.
Processing the Response
Once you have received the response from the server, synchronously or
asynchronously, you can look at the response fields in the
SoupMessage to decide what to do next. The
status_code and
reason_phrase fields contain the numeric
status and textual status response from the server.
response_headers contains the response
headers, which you can investigate using soup_message_get_header and
soup_message_foreach_header.
The response body (if any) is in the
response field.
If you send the message with soup_session_queue_message,
libsoup 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 soup_session_send_message,
so in that case, you must unref it explicitly when you are done with
it.
Intermediate/Automatic Processing
You can also connect to various SoupMessage
signals, or set up handlers using soup_message_add_handler
and the other handler methods. Notably, soup_message_add_header_handler,
soup_message_add_status_code_handler,
and
soup_message_add_status_class_handler
allow you to invoke a handler automatically for messages with certain
response headers or status codes. SoupSession uses
this internally to handle authentication and redirection.
When using the synchronous API, the callbacks and signal handlers will
be invoked during the call to soup_session_send_message.
To automatically set up handlers on all messages sent via a session,
you can create a SoupMessageFilter and attach it to
the session with soup_session_add_filter.
Handling AuthenticationSoupSession 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
authenticate 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 username
and password parameters with authentication
information. (The session will g_free 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.
If the authenticate handler returns a username and
password, but the request still gets an authorization error using that
information, then the session will emit the reauthenticate 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 reauthenticate again and again until the
returned username/password successfully authentications, or until the
signal handler fails to provide a username, at which point
libsoup will allow the message to fail
(with status 401 or 407).
There are basically three ways an application might want to use
the signals:
An interactive application that doesn't cache passwords could
just connect both authenticate and
reauthenticate 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").
A slightly cleverer interactive application would look in its
password cache from the authenticate
handler, and return a password from there if one was
available. If no password was cached, it would just call its
reauthenticate handler to prompt the user.
The reauthenticate 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
reauthenticate will be called again to
force it to be uncached.)
A non-interactive program that only has access to cached
passwords would only connect to
authenticate. If the username and password
that authenticate returns fail, the session
will emit reauthenticate, 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.
Sample Programs
A few sample programs are available in the
libsoup sources:
get is a simple command-line
HTTP GET utility using the asynchronous API.
dict and
getbug are trivial
demonstrations of the SOAP and XMLRPC interfaces,
respectively.
auth-test shows how to use
authentication handlers and status-code handlers, although in
a fairly unusual way.
simple-proxy uses both the
client and server APIs to create a simple (and not very
RFC-compliant) proxy server. It shows how to use the SOUP_MESSAGE_OVERWRITE_CHUNKS
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.
More complicated examples are available in GNOME CVS. The libsoup
pages on the GNOME wiki include a list of applications using
libsoup.