libsoup Client SoupRequest API

3 LIBSOUP Library

libsoup Client SoupRequest API

Using libsoup with a mix of `http` and non-`http` URIs.

## `SoupRequest`

`SoupRequest` is an abstract type representing a request for a particular URI. The `SoupRequest` API is an alternative to the `SoupMessage`-based `SoupSession` APIs which may be useful to programs that want to deal with multiple kinds of URIs.

`SoupRequest` officially became part of the libsoup API in 2.42 with the addition of `soup_session_request` and the related functions. However, parts of it are also available as far back as libsoup 2.34 via the (now-deprecated) `SoupRequester` session feature, if you define `LIBSOUP_USE_UNSTABLE_REQUEST_API` before including the libsoup headers.

Additionally, before libsoup 2.42, the `SoupRequest` API was the only way to stream an HTTP response body via `GInputStream`. As of 2.42, there are streaming APIs based on `SoupMessage` (`soup_session_send` and `soup_session_send_async`), so applications that are using `SoupRequest` with only `http` and `https` URIs can be ported to those APIs now.

## Creating a SoupRequest

There are four `SoupSession` methods for creating `SoupRequest`s:

- `soup_session_request` takes an arbitrary URI as a string, and returns a `SoupRequest`.

- `soup_session_request_uri` takes an arbitrary URI as a `SoupURI`, and returns a `SoupRequest`.

- `soup_session_request_http` takes an HTTP method and an `http` or `https` URI as a string, and returns a `SoupRequestHTTP`.

- `soup_session_request_http_uri` takes an HTTP method and an `http` or `https` URI as a `SoupURI`, and returns a `SoupRequestHTTP`.

## Sending a SoupRequest

Once you have created a `SoupRequest`, you can send it with either `soup_request_send` or `soup_request_send_async`. This will provide you with a `GInputStream` which you can read to get the response body.

After sending, you can use `soup_request_get_content_length` and `soup_request_get_content_type` to get information about the response body.

As with the streaming `SoupMessage`-based APIs, `soup_request_send` and `soup_request_send_async` only return errors if a transport-level problem occurs (eg, it could not connect to the host, or the request was cancelled). In the case of an HTTP request, use the message's status_code field to determine whether the request was successful or not at the HTTP level (ie, "`200 OK`" vs "`401 Bad Request`"). (You can call `soup_request_http_get_message` to get the request's corresponding `SoupMessage`, to look at the status code or other HTTP metadata.)

## Supported URI types, and adding your own

Different URI types are implemented by different subclasses of `SoupRequest`. libsoup currently implements three `SoupRequest` classes:

`SoupRequestHTTP`

- Handles `http` and `https` URI.

`SoupRequestData`

- Handles `data` URIs containing inline data.

`SoupRequestFile`

- Handles `file` and `resource` URIs. If you request a URI corresponding to a directory, this will generate an HTML listing of the directory.

You can add additional URI types by implementing your own `SoupRequest` subclass; set the `SoupRequestClass`'s schemes field to point to a `NULL`-terminated array of scheme names, implement the various `SoupRequest` methods, and then register the type with your `SoupSession` by calling `soup_session_add_feature_by_type` and passing the `GType` of your request class.