## Soup Client Basics

Soup Client Basics — Client-side tutorial

### Creating 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 Authentication

SoupSession 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.