libsoup Client SoupRequest API
libsoup Client SoupRequest API — Using
libsoup with a mix of
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
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
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 (
so applications that are using SoupRequest with only
https URIs can be
ported to those APIs now.
Creating a SoupRequest
There are four SoupSession methods for creating SoupRequests:
Sending a SoupRequest
As with the streaming SoupMessage-based APIs,
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
status_code field to determine
whether the request was successful or not at the HTTP level (ie, "
OK" vs "
401 Bad Request"). (You can call
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:
You can add additional URI types by implementing your own
SoupRequest subclass; set the
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
and passing the GType of
your request class.