libsoup Reference Manual: libsoup Client SoupRequest API

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.