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
46performed on some resource.  The
47<function>ne_request_create</function> function creates a request
48object, specifying the operation in the <parameter>method</parameter>
49parameter. The location of the resource is determined by the server in
50use for the session given by the <parameter>sess</parameter>
51parameter, 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
55optional "?query" part, and must be URI-escaped by the caller (for
56instance, using <function>ne_path_escape</function>).  If the string
57comes from an untrusted source, failure to perform URI-escaping
58results 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
62alternative is to use the (more complex, but more flexible)
63combination 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
69linkend="ne_add_request_header"/> and <xref
70linkend="ne_print_request_header"/> can be used.  To include a message
71body with the request, one of the functions
72<function>ne_set_request_body_buffer</function>, <xref
73linkend="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
78request was sent and the response read successfully.  To discover the
79result of the operation, <xref linkend="ne_get_status"/>, along with
80any 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
102returns a pointer to a request object (and never &null;).</para>
103
104	<para>The <function>ne_request_dispatch</function> function
105returns zero if the request was dispatched successfully, and a
106non-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);
158ne_request *req = ne_request_create(sess, "MKCOL", "/foo/bar/");
159if (ne_request_dispatch(req)) {
160   printf("Request failed: %s\n", ne_get_error(sess));
161}
162ne_request_destroy(req);</programlisting>
163      </refsect1>
164
165      <refsect1>
166	<title>See also</title>
167	
168	<para><xref linkend="ne_get_error"/>, <xref
169linkend="ne_set_error"/>, <xref linkend="ne_get_status"/>, <xref
170linkend="ne_add_request_header"/>, <xref
171linkend="ne_set_request_body_buffer"/>, <xref linkend="ne_set_request_flag"/>.</para>
172
173      </refsect1>
174
175    </refentry>
176