## libsoup Client SoupRequest API

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 SoupRequests:

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