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 <ne_request.h></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