| 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 |
| 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> |