1<?xml version="1.0"?> 2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> 4<refentry id="libsoup-request-howto"> 5<refmeta> 6<refentrytitle>libsoup Client SoupRequest API</refentrytitle> 7<manvolnum>3</manvolnum> 8<refmiscinfo>LIBSOUP Library</refmiscinfo> 9</refmeta> 10 11<refnamediv> 12<refname>libsoup Client SoupRequest API</refname><refpurpose>Using 13libsoup with a mix of <literal>http</literal> and non-<literal>http</literal> URIs.</refpurpose> 14</refnamediv> 15 16<refsect2> 17<title><type>SoupRequest</type></title> 18 19<para> 20<link linkend="SoupRequest"><type>SoupRequest</type></link> is an 21abstract type representing a request for a particular URI. The 22<type>SoupRequest</type> API is an alternative to the <link 23linkend="SoupMessage"><type>SoupMessage</type></link>-based <link 24linkend="SoupSession"><type>SoupSession</type></link> APIs which may be 25useful to programs that want to deal with multiple kinds of URIs. 26</para> 27 28<para> 29<type>SoupRequest</type> officially became part of the 30<application>libsoup</application> API in 2.42 with the addition of 31<link 32linkend="soup-session-request"><function>soup_session_request</function></link> 33and the related functions. However, parts of it are also available as 34far back as <application>libsoup</application> 2.34 via the 35(now-deprecated) <type>SoupRequester</type> session feature, if you 36define <literal>LIBSOUP_USE_UNSTABLE_REQUEST_API</literal> before 37including the <application>libsoup</application> headers. 38</para> 39 40<para> 41Additionally, before <application>libsoup</application> 2.42, the 42<type>SoupRequest</type> API was the only way to stream an HTTP 43response body via <link 44linkend="GInputStream"><type>GInputStream</type></link>. As of 2.42, 45there are streaming APIs based on <type>SoupMessage</type> (<link 46linkend="soup-session-send"><function>soup_session_send</function></link> 47and <link 48linkend="soup-session-send-async"><function>soup_session_send_async</function></link>), 49so applications that are using <type>SoupRequest</type> with only 50<literal>http</literal> and <literal>https</literal> URIs can be 51ported to those APIs now. 52</para> 53 54</refsect2> 55 56<refsect2> 57<title>Creating a SoupRequest</title> 58 59<para> 60There are four <type>SoupSession</type> methods for creating 61<type>SoupRequest</type>s: 62</para> 63 64<itemizedlist> 65 <listitem> 66 <para> 67 <link linkend="soup-session-request"><function>soup_session_request</function></link> 68 takes an arbitrary URI as a string, and returns a <link 69 linkend="SoupRequest"><type>SoupRequest</type></link>. 70 </para> 71 </listitem> 72 <listitem> 73 <para> 74 <link linkend="soup-session-request-uri"><function>soup_session_request_uri</function></link> 75 takes an arbitrary URI as a <link linkend="SoupURI"><type>SoupURI</type></link>, 76 and returns a <link linkend="SoupRequest"><type>SoupRequest</type></link>. 77 </para> 78 </listitem> 79 <listitem> 80 <para> 81 <link linkend="soup-session-request-http"><function>soup_session_request_http</function></link> 82 takes an HTTP method and an <literal>http</literal> or <literal>https</literal> URI as a string, and returns a <link 83 linkend="SoupRequestHTTP"><type>SoupRequestHTTP</type></link>. 84 </para> 85 </listitem> 86 <listitem> 87 <para> 88 <link linkend="soup-session-request-http-uri"><function>soup_session_request_http_uri</function></link> 89 takes an HTTP method and an <literal>http</literal> or <literal>https</literal> URI as a <link linkend="SoupURI"><type>SoupURI</type></link>, 90 and returns a <link linkend="SoupRequestHTTP"><type>SoupRequestHTTP</type></link>. 91 </para> 92 </listitem> 93</itemizedlist> 94 95</refsect2> 96 97<refsect2> 98<title>Sending a SoupRequest</title> 99 100<para> 101Once you have created a <type>SoupRequest</type>, you can send it with 102either <link 103linkend="soup-request-send"><function>soup_request_send</function></link> 104or <link 105linkend="soup-request-send-async"><function>soup_request_send_async</function></link>. 106This will provide you with a <link 107linkend="GInputStream"><type>GInputStream</type></link> which you can 108read to get the response body. 109</para> 110 111<para> 112After sending, you can use <link 113linkend="soup-request-get-content-length"><function>soup_request_get_content_length</function></link> 114and <link 115linkend="soup-request-get-content-type"><function>soup_request_get_content_type</function></link> 116to get information about the response body. 117</para> 118 119<para> 120As with the streaming <type>SoupMessage</type>-based APIs, 121<function>soup_request_send</function> and 122<function>soup_request_send_async</function> only return errors if a 123transport-level problem occurs (eg, it could not connect to the host, 124or the request was cancelled). In the case of an HTTP request, use the 125message's <structfield>status_code</structfield> field to determine 126whether the request was successful or not at the HTTP level (ie, "<literal>200 127OK</literal>" vs "<literal>401 Bad Request</literal>"). (You can call <link 128linkend="soup-request-http-get-message"><function>soup_request_http_get_message</function></link> 129to get the request's corresponding <link 130linkend="SoupMessage"><type>SoupMessage</type></link>, to look at the 131status code or other HTTP metadata.) 132</para> 133 134</refsect2> 135 136<refsect2> 137<title>Supported URI types, and adding your own</title> 138 139<para> 140Different URI types are implemented by different subclasses of 141<type>SoupRequest</type>. <application>libsoup</application> currently 142implements three <type>SoupRequest</type> classes: 143</para> 144 145<variablelist> 146 <varlistentry> 147 <term><link linkend="SoupRequestHTTP"><type>SoupRequestHTTP</type></link></term> 148 <listitem><para> 149 Handles <literal>http</literal> and 150 <literal>https</literal> URI. 151 </para></listitem> 152 </varlistentry> 153 <varlistentry> 154 <term><link linkend="SoupRequestData"><type>SoupRequestData</type></link></term> 155 <listitem><para> 156 Handles <literal>data</literal> URIs containing inline data. 157 </para></listitem> 158 </varlistentry> 159 <varlistentry> 160 <term><link linkend="SoupRequestFile"><type>SoupRequestFile</type></link></term> 161 <listitem><para> 162 Handles <literal>file</literal> and 163 <link linkend="GResource"><literal>resource</literal></link> URIs. 164 If you request a URI corresponding to a directory, this 165 will generate an HTML listing of the directory. 166 </para></listitem> 167 </varlistentry> 168</variablelist> 169 170<para> 171You can add additional URI types by implementing your own 172<type>SoupRequest</type> subclass; set the 173<type>SoupRequestClass</type>'s <structfield>schemes</structfield> 174field to point to a <literal>NULL</literal>-terminated array of scheme 175names, implement the various <type>SoupRequest</type> methods, and 176then register the type with your <type>SoupSession</type> by calling 177<link linkend="soup-session-add-feature-by-type"><function>soup_session_add_feature_by_type</function></link> 178and passing the <link linkend="GType"><type>GType</type></link> of 179your request class. 180</para> 181 182</refsect2> 183 184</refentry> 185