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