Debian Codegraph @

deps/libneon/doc/ref/req.xml

raw
1 <refentry id="refreq">
2
3 <refmeta>
4 <refentrytitle>ne_request_create</refentrytitle>
5 <manvolnum>3</manvolnum>
6 </refmeta>
7
8 <refnamediv>
9 <refname id="ne_request_create">ne_request_create</refname>
10 <refname id="ne_request_dispatch">ne_request_dispatch</refname>
11 <refname id="ne_request_destroy">ne_request_destroy</refname>
12 <refpurpose>low-level HTTP request handling</refpurpose>
13 </refnamediv>
14
15 <refsynopsisdiv>
16
17 <funcsynopsis>
18
19 <funcsynopsisinfo>#include &lt;ne_request.h&gt;</funcsynopsisinfo>
20
21 <funcprototype>
22 <funcdef>ne_request *<function>ne_request_create</function></funcdef>
23 <paramdef>ne_session *<parameter>session</parameter></paramdef>
24 <paramdef>const char *<parameter>method</parameter></paramdef>
25 <paramdef>const char *<parameter>path</parameter></paramdef>
26 </funcprototype>
27
28 <funcprototype>
29 <funcdef>int <function>ne_request_dispatch</function></funcdef>
30 <paramdef>ne_request *<parameter>req</parameter></paramdef>
31 </funcprototype>
32
33 <funcprototype>
34 <funcdef>void <function>ne_request_destroy</function></funcdef>
35 <paramdef>ne_request *<parameter>req</parameter></paramdef>
36 </funcprototype>
37 </funcsynopsis>
38
39 </refsynopsisdiv>
40
41 <refsect1>
42 <title>Description</title>
43
44 <para>An HTTP request, represented by the
45 <type>ne_request</type> type, specifies that some operation is to be
46 performed on some resource. The
47 <function>ne_request_create</function> function creates a request
48 object, specifying the operation in the <parameter>method</parameter>
49 parameter. The location of the resource is determined by the server in
50 use for the session given by the <parameter>sess</parameter>
51 parameter, combined with the <parameter>path</parameter> parameter.</para>
52
53 <para>The <parameter>path</parameter> string used must conform to the
54 <literal>abs_path</literal> definition given in RFC2396, with an
55 optional "?query" part, and must be URI-escaped by the caller (for
56 instance, using <function>ne_path_escape</function>). If the string
57 comes from an untrusted source, failure to perform URI-escaping
58 results in a security vulnerability.</para>
59
60 <para>To dispatch a request, and process the response, the
61 <function>ne_request_dispatch</function> function can be used. An
62 alternative is to use the (more complex, but more flexible)
63 combination of the <function>ne_begin_request</function>,
64 <function>ne_end_request</function>, and
65 <function>ne_read_response_block</function> functions; see
66 <function>ne_begin_request</function>.</para>
67
68 <para>To add extra headers in the request, the functions <xref
69 linkend="ne_add_request_header"/> and <xref
70 linkend="ne_print_request_header"/> can be used. To include a message
71 body with the request, one of the functions
72 <function>ne_set_request_body_buffer</function>, <xref
73 linkend="ne_set_request_body_fd"/>, or
74 <function>ne_set_request_body_provider</function> can be used.</para>
75
76 <para>The return value of
77 <function>ne_request_dispatch</function> indicates merely whether the
78 request was sent and the response read successfully. To discover the
79 result of the operation, <xref linkend="ne_get_status"/>, along with
80 any processing of the response headers and message body.</para>
81
82 <para>A request can only be dispatched once: calling
83 <function>ne_request_dispatch</function> more than once on a
84 single <type>ne_request</type> object produces undefined
85 behaviour. Once all processing associated with the request
86 object is complete, use the
87 <function>ne_request_destroy</function> function to destroy
88 the resources associated with it. Any subsequent use of the
89 request object produces undefined behaviour.</para>
90
91 <para>If a request is being using a non-idempotent method such
92 as <literal>POST</literal>, the
93 <literal>NE_REQFLAG_IDEMPOTENT</literal> flag should be
94 disabled; see <xref linkend="ne_set_request_flag"/>.</para>
95
96 </refsect1>
97
98 <refsect1>
99 <title>Return value</title>
100
101 <para>The <function>ne_request_create</function> function
102 returns a pointer to a request object (and never &null;).</para>
103
104 <para>The <function>ne_request_dispatch</function> function
105 returns zero if the request was dispatched successfully, and a
106 non-zero error code otherwise.</para>
107
108 </refsect1>
109
110 <!-- TODO: abs_path description in a NOTES section -->
111
112 <refsect1>
113 <title>Errors</title>
114
115 <variablelist>
116 <varlistentry><term><errorcode>NE_ERROR</errorcode></term>
117 <listitem>
118 <simpara>Request failed (see session error string)</simpara>
119 </listitem>
120 </varlistentry>
121 <varlistentry><term><errorcode>NE_LOOKUP</errorcode></term>
122 <listitem>
123 <simpara>The DNS lookup for the server (or proxy server) failed.</simpara>
124 </listitem>
125 </varlistentry>
126 <varlistentry><term><errorcode>NE_AUTH</errorcode></term>
127 <listitem>
128 <simpara>Authentication failed on the server.</simpara>
129 </listitem>
130 </varlistentry>
131 <varlistentry><term><errorcode>NE_PROXYAUTH</errorcode></term>
132 <listitem>
133 <simpara>Authentication failed on the proxy server.</simpara>
134 </listitem>
135 </varlistentry>
136 <varlistentry><term><errorcode>NE_CONNECT</errorcode></term>
137 <listitem>
138 <simpara>A connection to the server could not be established.</simpara>
139 </listitem>
140 </varlistentry>
141 <varlistentry><term><errorcode>NE_TIMEOUT</errorcode></term>
142 <listitem>
143 <simpara>A timeout occurred while waiting for the server to respond.</simpara>
144 </listitem>
145 </varlistentry>
146 </variablelist>
147
148 </refsect1>
149
150 <refsect1>
151 <title>Example</title>
152
153 <para>An example of applying a <literal>MKCOL</literal>
154 operation to the resource at the location
155 <literal>http://www.example.com/foo/bar/</literal>:</para>
156
157 <programlisting>ne_session *sess = ne_session_create("http", "www.example.com", 80);
158 ne_request *req = ne_request_create(sess, "MKCOL", "/foo/bar/");
159 if (ne_request_dispatch(req)) {
160 printf("Request failed: %s\n", ne_get_error(sess));
161 }
162 ne_request_destroy(req);</programlisting>
163 </refsect1>
164
165 <refsect1>
166 <title>See also</title>
167
168 <para><xref linkend="ne_get_error"/>, <xref
169 linkend="ne_set_error"/>, <xref linkend="ne_get_status"/>, <xref
170 linkend="ne_add_request_header"/>, <xref
171 linkend="ne_set_request_body_buffer"/>, <xref linkend="ne_set_request_flag"/>.</para>
172
173 </refsect1>
174
175 </refentry>