<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>libsoup Client SoupRequest API: libsoup Reference Manual</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="libsoup Reference Manual">
<link rel="up" href="ch01.html" title="Tutorial">
<link rel="prev" href="libsoup-client-howto.html" title="libsoup Client Basics">
<link rel="next" href="libsoup-session-porting.html" title="Porting to the new SoupSession">
<meta name="generator" content="GTK-Doc V1.28.1 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts"></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><a accesskey="u" href="ch01.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="libsoup-client-howto.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="libsoup-session-porting.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="refentry">
<a name="libsoup-request-howto"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle">libsoup Client SoupRequest API</span></h2>
<p>libsoup Client SoupRequest API — Using
libsoup with a mix of <code class="literal">http</code> and non-<code class="literal">http</code> URIs.</p>
</td>
<td class="gallery_image" valign="top" align="right"></td>
</tr></table></div>
<div class="refsect2">
<a name="id-1.2.4.3"></a><h3><span class="type">SoupRequest</span></h3>
<p>
<a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a> is an
abstract type representing a request for a particular URI. The
<span class="type">SoupRequest</span> API is an alternative to the <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>-based <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> APIs which may be
useful to programs that want to deal with multiple kinds of URIs.
</p>
<p>
<span class="type">SoupRequest</span> officially became part of the
<span class="application">libsoup</span> API in 2.42 with the addition of
<a class="link" href="SoupSession.html#soup-session-request" title="soup_session_request ()"><code class="function">soup_session_request</code></a>
and the related functions. However, parts of it are also available as
far back as <span class="application">libsoup</span> 2.34 via the
(now-deprecated) <span class="type">SoupRequester</span> session feature, if you
define <code class="literal">LIBSOUP_USE_UNSTABLE_REQUEST_API</code> before
including the <span class="application">libsoup</span> headers.
</p>
<p>
Additionally, before <span class="application">libsoup</span> 2.42, the
<span class="type">SoupRequest</span> API was the only way to stream an HTTP
response body via <span class="type">GInputStream</span>. As of 2.42,
there are streaming APIs based on <span class="type">SoupMessage</span> (<a class="link" href="SoupSession.html#soup-session-send" title="soup_session_send ()"><code class="function">soup_session_send</code></a>
and <a class="link" href="SoupSession.html#soup-session-send-async" title="soup_session_send_async ()"><code class="function">soup_session_send_async</code></a>),
so applications that are using <span class="type">SoupRequest</span> with only
<code class="literal">http</code> and <code class="literal">https</code> URIs can be
ported to those APIs now.
</p>
</div>
<hr>
<div class="refsect2">
<a name="id-1.2.4.4"></a><h3>Creating a SoupRequest</h3>
<p>
There are four <span class="type">SoupSession</span> methods for creating
<span class="type">SoupRequest</span>s:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>
<a class="link" href="SoupSession.html#soup-session-request" title="soup_session_request ()"><code class="function">soup_session_request</code></a>
takes an arbitrary URI as a string, and returns a <a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a>.
</p></li>
<li class="listitem"><p>
<a class="link" href="SoupSession.html#soup-session-request-uri" title="soup_session_request_uri ()"><code class="function">soup_session_request_uri</code></a>
takes an arbitrary URI as a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a>,
and returns a <a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a>.
</p></li>
<li class="listitem"><p>
<a class="link" href="SoupSession.html#soup-session-request-http" title="soup_session_request_http ()"><code class="function">soup_session_request_http</code></a>
takes an HTTP method and an <code class="literal">http</code> or <code class="literal">https</code> URI as a string, and returns a <a class="link" href="SoupRequestHTTP.html" title="SoupRequestHTTP"><span class="type">SoupRequestHTTP</span></a>.
</p></li>
<li class="listitem"><p>
<a class="link" href="SoupSession.html#soup-session-request-http-uri" title="soup_session_request_http_uri ()"><code class="function">soup_session_request_http_uri</code></a>
takes an HTTP method and an <code class="literal">http</code> or <code class="literal">https</code> URI as a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a>,
and returns a <a class="link" href="SoupRequestHTTP.html" title="SoupRequestHTTP"><span class="type">SoupRequestHTTP</span></a>.
</p></li>
</ul></div>
</div>
<hr>
<div class="refsect2">
<a name="id-1.2.4.5"></a><h3>Sending a SoupRequest</h3>
<p>
Once you have created a <span class="type">SoupRequest</span>, you can send it with
either <a class="link" href="SoupRequest.html#soup-request-send" title="soup_request_send ()"><code class="function">soup_request_send</code></a>
or <a class="link" href="SoupRequest.html#soup-request-send-async" title="soup_request_send_async ()"><code class="function">soup_request_send_async</code></a>.
This will provide you with a <span class="type">GInputStream</span> which you can
read to get the response body.
</p>
<p>
After sending, you can use <a class="link" href="SoupRequest.html#soup-request-get-content-length" title="soup_request_get_content_length ()"><code class="function">soup_request_get_content_length</code></a>
and <a class="link" href="SoupRequest.html#soup-request-get-content-type" title="soup_request_get_content_type ()"><code class="function">soup_request_get_content_type</code></a>
to get information about the response body.
</p>
<p>
As with the streaming <span class="type">SoupMessage</span>-based APIs,
<code class="function">soup_request_send</code> and
<code class="function">soup_request_send_async</code> 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 <em class="structfield"><code>status_code</code></em> field to determine
whether the request was successful or not at the HTTP level (ie, "<code class="literal">200
OK</code>" vs "<code class="literal">401 Bad Request</code>"). (You can call <a class="link" href="SoupRequestHTTP.html#soup-request-http-get-message" title="soup_request_http_get_message ()"><code class="function">soup_request_http_get_message</code></a>
to get the request's corresponding <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>, to look at the
status code or other HTTP metadata.)
</p>
</div>
<hr>
<div class="refsect2">
<a name="id-1.2.4.6"></a><h3>Supported URI types, and adding your own</h3>
<p>
Different URI types are implemented by different subclasses of
<span class="type">SoupRequest</span>. <span class="application">libsoup</span> currently
implements three <span class="type">SoupRequest</span> classes:
</p>
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody>
<tr>
<td><p><span class="term"><a class="link" href="SoupRequestHTTP.html" title="SoupRequestHTTP"><span class="type">SoupRequestHTTP</span></a></span></p></td>
<td><p>
Handles <code class="literal">http</code> and
<code class="literal">https</code> URI.
</p></td>
</tr>
<tr>
<td><p><span class="term"><a class="link" href="SoupRequestData.html" title="SoupRequestData"><span class="type">SoupRequestData</span></a></span></p></td>
<td><p>
Handles <code class="literal">data</code> URIs containing inline data.
</p></td>
</tr>
<tr>
<td><p><span class="term"><a class="link" href="SoupRequestFile.html" title="SoupRequestFile"><span class="type">SoupRequestFile</span></a></span></p></td>
<td><p>
Handles <code class="literal">file</code> and
<code class="literal">resource</code> URIs.
If you request a URI corresponding to a directory, this
will generate an HTML listing of the directory.
</p></td>
</tr>
</tbody>
</table></div>
<p>
You can add additional URI types by implementing your own
<span class="type">SoupRequest</span> subclass; set the
<span class="type">SoupRequestClass</span>'s <em class="structfield"><code>schemes</code></em>
field to point to a <code class="literal">NULL</code>-terminated array of scheme
names, implement the various <span class="type">SoupRequest</span> methods, and
then register the type with your <span class="type">SoupSession</span> by calling
<a class="link" href="SoupSession.html#soup-session-add-feature-by-type" title="soup_session_add_feature_by_type ()"><code class="function">soup_session_add_feature_by_type</code></a>
and passing the <span class="type">GType</span> of
your request class.
</p>
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.28.1</div>
</body>
</html>