1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
|
<refentry id="refreqbody">
<refmeta>
<refentrytitle>ne_set_request_body_buffer</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname id="ne_set_request_body_buffer">ne_set_request_body_buffer</refname>
<refname id="ne_set_request_body_fd">ne_set_request_body_fd</refname>
<refname id="ne_set_request_body_provider">ne_set_request_body_provider</refname>
<refpurpose>include a message body with a request</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include <ne_request.h></funcsynopsisinfo>
<funcprototype>
<funcdef>void <function>ne_set_request_body_buffer</function></funcdef>
<paramdef>ne_request *<parameter>req</parameter></paramdef>
<paramdef>const char *<parameter>buf</parameter></paramdef>
<paramdef>size_t <parameter>count</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>ne_set_request_body_fd</function></funcdef>
<paramdef>ne_request *<parameter>req</parameter></paramdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>ne_off_t <parameter>begin</parameter></paramdef>
<paramdef>ne_off_t <parameter>length</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>typedef ssize_t (*<function>ne_provide_body</function>)</funcdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
<paramdef>char *<parameter>data</parameter></paramdef>
<paramdef>size_t <parameter>buflen</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>ne_set_request_body_provider</function></funcdef>
<paramdef>ne_request *<parameter>req</parameter></paramdef>
<paramdef>ne_off_t <parameter>length</parameter></paramdef>
<paramdef>ne_provide_body <parameter>provider</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>The <function>ne_set_request_body_buffer</function>
function specifies that a message body should be included with the
body, which is stored in the <parameter>count</parameter> bytes buffer
<parameter>buf</parameter>.</para>
<para>The <function>ne_set_request_body_fd</function> function
can be used to include a message body with a request which is read
from a file descriptor. The body is read from the file descriptor
<parameter>fd</parameter>, which must be a associated with a seekable
file (not a pipe, socket, or FIFO). <parameter>count</parameter>
bytes are read, beginning at offset <parameter>begin</parameter>
(hence, passing <parameter>begin</parameter> as zero means the body is read
from the beginning of the file).</para>
<para>For both above functions, the source of the request
body must survive until the request has been dispatched;
neither the memory buffer passed to
<function>ne_set_request_body_buffer</function> nor the file
descriptor passed to
<function>ne_set_request_body_fd</function> are copied
internally.</para>
<para>The <function>ne_set_request_body_provider</function>
function can be used to include a message body with a request
which is provided by a callback function. The body length
passed in the <parameter>length</parameter> paramater must be
positive, or if a chunked request body is required, as covered
below, <literal>-1</literal> can be used.</para>
<para>Before sending the body, the callback is invoked once
with the <parameter>buflen</parameter> parameter as
<literal>0</literal>. The body is then read by invoking the
callback repeatedly until it returns <literal>0</literal>
indicating the end-of-body. The callback return value must be
as follows:
<variablelist>
<varlistentry>
<term>less than <literal>0</literal></term>
<listitem><simpara>An error; the request will be
aborted. The session error string must be set via
<function>ne_set_error</function>.</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>0</literal></term>
<listitem><simpara>End of body.</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>between <literal>0</literal> and
<constant>buflen</constant></term>
<listitem><simpara>Number of bytes of request body data.</simpara>
</listitem>
</varlistentry>
</variablelist></para>
<refsect2>
<title>Chunked request bodies</title>
<para>Chunked request bodies are only sent when
<function>ne_set_request_body_provider</function> is used
and <literal>-1</literal> is passed as the
<parameter>length</parameter>. In this case, the length of
the request body does not have to be determined ahead of
time. The end of the request body is indicated by returning
<literal>0</literal> from the callback function.</para>
<para>Before using a chunked request body, the caller must
determine that HTTP/1.1 is supported (by the origin server
and any HTTP proxy server configured). This can be done by
testing that <function>ne_version_pre_http11</function>
returns zero after performing an <literal>OPTIONS</literal>
or <literal>HEAD</literal> request.</para>
</refsect2>
</refsect1>
<refsect1>
<title>See also</title>
<para><xref linkend="ne_request_create"/>, <xref
linkend="ne_set_error"/></para>
</refsect1>
</refentry>
|
