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:
soup_session_requesttakes an arbitrary URI as a string, and returns a SoupRequest.
soup_session_request_uritakes an arbitrary URI as a SoupURI, and returns a SoupRequest.
soup_session_request_httptakes an HTTP method and an
httpsURI as a string, and returns a SoupRequestHTTP.
soup_session_request_http_uritakes an HTTP method and an
httpsURI as a SoupURI, and returns a SoupRequestHTTP.
Sending a SoupRequest
Once you have created a SoupRequest, you can send it with
This will provide you with a GInputStream which you can
read to get the response body.
After sending, you can use
to get information about the response body.
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.