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
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
|
---
version: v1.2.0
layout: refman
---
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 2.0.10">
<title>nng_http_handler_alloc(3http)</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
<link rel="stylesheet" href="./asciidoctor.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
</head>
<body class="manpage toc2 toc-left">
<div id="header">
<h1>nng_http_handler_alloc(3http) Manual Page</h1>
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel1">
<li><a href="#_synopsis">SYNOPSIS</a></li>
<li><a href="#_description">DESCRIPTION</a>
<ul class="sectlevel2">
<li><a href="#_custom_handler">Custom Handler</a></li>
<li><a href="#_directory_handler">Directory Handler</a></li>
<li><a href="#_file_handler">File Handler</a></li>
<li><a href="#_redirect_handler">Redirect Handler</a></li>
<li><a href="#_static_handler">Static Handler</a></li>
</ul>
</li>
<li><a href="#_return_values">RETURN VALUES</a></li>
<li><a href="#_errors">ERRORS</a></li>
<li><a href="#_see_also">SEE ALSO</a></li>
</ul>
</div>
<h2 id="_name">NAME</h2>
<div class="sectionbody">
<p>nng_http_handler_alloc - allocate HTTP server handler</p>
</div>
</div>
<div id="content">
<div class="sect1">
<h2 id="_synopsis">SYNOPSIS</h2>
<div class="sectionbody">
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span> <span class="tok-cpf"><nng/nng.h></span><span class="tok-cp"></span>
<span class="tok-cp">#include</span> <span class="tok-cpf"><nng/supplemental/http/http.h></span><span class="tok-cp"></span>
<span class="tok-k">typedef</span> <span class="tok-k">struct</span> <span class="tok-n">nng_http_handler</span> <span class="tok-n">nng_http_handler</span><span class="tok-p">;</span>
<span class="tok-kt">int</span> <span class="tok-nf">nng_http_handler_alloc</span><span class="tok-p">(</span><span class="tok-n">nng_http_handler</span> <span class="tok-o">**</span><span class="tok-n">hp</span><span class="tok-p">,</span> <span class="tok-k">const</span> <span class="tok-kt">char</span> <span class="tok-o">*</span><span class="tok-n">path</span><span class="tok-p">,</span>
<span class="tok-kt">void</span> <span class="tok-p">(</span><span class="tok-o">*</span><span class="tok-n">func</span><span class="tok-p">)(</span><span class="tok-n">nng_aio</span> <span class="tok-o">*</span><span class="tok-p">);</span>
<span class="tok-kt">int</span> <span class="tok-nf">nng_http_handler_alloc_directory</span><span class="tok-p">(</span><span class="tok-n">nng_http_handler</span> <span class="tok-o">**</span><span class="tok-n">hp</span><span class="tok-p">,</span> <span class="tok-k">const</span> <span class="tok-kt">char</span> <span class="tok-o">*</span><span class="tok-n">path</span><span class="tok-p">,</span>
<span class="tok-k">const</span> <span class="tok-kt">char</span> <span class="tok-o">*</span><span class="tok-n">dirname</span><span class="tok-p">);</span>
<span class="tok-kt">int</span> <span class="tok-nf">nng_http_handler_alloc_file</span><span class="tok-p">(</span><span class="tok-n">nng_http_handler</span> <span class="tok-o">**</span><span class="tok-n">hp</span><span class="tok-p">,</span> <span class="tok-k">const</span> <span class="tok-kt">char</span> <span class="tok-o">*</span><span class="tok-n">path</span><span class="tok-p">,</span>
<span class="tok-k">const</span> <span class="tok-kt">char</span> <span class="tok-o">*</span><span class="tok-n">filename</span><span class="tok-p">);</span>
<span class="tok-kt">int</span> <span class="tok-nf">nng_http_handler_alloc_redirect</span><span class="tok-p">(</span><span class="tok-n">nng_http_handler</span> <span class="tok-o">**</span><span class="tok-n">hp</span><span class="tok-p">,</span> <span class="tok-k">const</span> <span class="tok-kt">char</span> <span class="tok-o">*</span><span class="tok-n">path</span><span class="tok-p">,</span>
<span class="tok-kt">uint16_t</span> <span class="tok-n">status</span><span class="tok-p">,</span> <span class="tok-k">const</span> <span class="tok-kt">char</span> <span class="tok-o">*</span><span class="tok-n">location</span><span class="tok-p">);</span>
<span class="tok-kt">int</span> <span class="tok-nf">nng_http_handler_alloc_static</span><span class="tok-p">(</span><span class="tok-n">nng_http_handler</span> <span class="tok-o">**</span><span class="tok-n">hp</span><span class="tok-p">,</span> <span class="tok-k">const</span> <span class="tok-kt">char</span> <span class="tok-o">*</span><span class="tok-n">path</span><span class="tok-p">,</span>
<span class="tok-k">const</span> <span class="tok-kt">void</span> <span class="tok-o">*</span><span class="tok-n">data</span><span class="tok-p">,</span> <span class="tok-kt">size_t</span> <span class="tok-n">size</span><span class="tok-p">,</span> <span class="tok-k">const</span> <span class="tok-kt">char</span> <span class="tok-o">*</span><span class="tok-n">content_type</span><span class="tok-p">);</span></code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_description">DESCRIPTION</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The <code>nng_http_handler_alloc()</code> family of functions allocate a handler
which will be used to process requests coming into an HTTP server.
On success, a pointer to the handler is stored at the located pointed to
by <em>hp</em>.</p>
</div>
<div class="paragraph">
<p>Every handler has a Request-URI to which it refers, which is determined
by the <em>path</em> argument.
Only the path component of the Request URI is
considered when determining whether the handler should be called.</p>
</div>
<div class="paragraph">
<p>Additionally each handler has a method it is registered to handle
(the default is <code>GET</code>, see
<a href="nng_http_handler_set_method.3http.html"><code>nng_http_handler_set_method()</code></a>), and
optionally a 'Host' header it can be matched against (see
<a href="nng_http_handler_set_host.3http.html"><code>nng_http_handler_set_host()</code></a>).</p>
</div>
<div class="paragraph">
<p>In some cases, a handler may reference a logical tree rather (directory)
rather than just a single element.
(See <a href="nng_http_handler_set_tree.3http.html"><code>nng_http_handler_set_tree()</code></a>).</p>
</div>
<div class="sect2">
<h3 id="_custom_handler">Custom Handler</h3>
<div class="paragraph">
<p>The generic (first) form of this creates a handler that uses a user-supplied
function to process HTTP requests.
This function uses the asynchronous I/O framework.
The function takes a pointer to an <a href="nng_aio.5.html"><code>nng_aio</code></a> structure.</p>
</div>
<div class="paragraph">
<p>The <em>aio</em> will be passed with the following input values (retrieved with
<a href="nng_aio_get_input.3.html"><code>nng_aio_get_input()</code></a>):</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">0: <code>nng_http_req *</code> <em>request</em></dt>
<dd>
<p>The client’s HTTP request.</p>
</dd>
<dt class="hdlist1">1: <code>nng_http_handler *</code> <em>handler</em></dt>
<dd>
<p>Pointer to the handler object.</p>
</dd>
<dt class="hdlist1">2: <code>nng_http_conn *</code> <em>conn</em></dt>
<dd>
<p>The underlying HTTP connection.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>The handler should create an <code>nng_http_res *</code> response (such as via
<a href="nng_http_res_alloc.3http.html"><code>nng_http_res_alloc()</code></a> or
<a href="nng_http_res_alloc_error.3http.html"><code>nng_http_res_alloc_error()</code></a>) and store that
in as the first output (index 0) with
<a href="nng_aio_set_output.3.html"><code>nng_aio_set_output()</code></a>.</p>
</div>
<div class="paragraph">
<p>Alternatively, the handler may send the HTTP response (and any associated
body data) itself using the connection.
In that case the output at index 0 of the <em>aio</em> should be NULL.</p>
</div>
<div class="paragraph">
<p>Finally, using the <a href="nng_aio_finish.3.html"><code>nng_aio_finish()</code></a> function, the
<em>aio</em> should be completed successfully.
If any non-zero status is returned back to the caller instead,
then a generic 500 response will be created and
sent, if possible, and the connection will be closed.</p>
</div>
<div class="paragraph">
<p>The <em>aio</em> may be scheduled for deferred completion using the
<a href="nng_aio_defer.3.html"><code>nng_aio_defer()</code></a> function.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The callback function should <strong>NOT</strong> call
<a href="nng_aio_begin.3.html"><code>nng_aio_begin()</code></a>,
as that will already have been done by the server framework.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="_directory_handler">Directory Handler</h3>
<div class="paragraph">
<p>The second member of this family, <code>nng_http_handler_alloc_directory()</code>, creates
a handler configured to serve a directory tree.
The <em>uri</em> is taken as the root, and files are served from the directory
tree rooted at <em>path</em>.</p>
</div>
<div class="paragraph">
<p>When the client Request-URI resolves to a directory in the file system,
the handler looks first for a file named <code>index.html</code> or <code>index.htm</code>.
If one is found, then that file is returned back to the client.
If no such index file exists, then an <code>NNG_HTTP_STATUS_NOT_FOUND</code> (404) error is
sent back to the client.</p>
</div>
<div class="paragraph">
<p>The <code>Content-Type</code> will be set automatically based upon the extension
of the requested file name.
If a content type cannot be determined from
the extension, then <code>application/octet-stream</code> is used.</p>
</div>
</div>
<div class="sect2">
<h3 id="_file_handler">File Handler</h3>
<div class="paragraph">
<p>The third member of this family, <code>nng_http_handler_alloc_file()</code>, creates
a handler to serve up a single file; it does not traverse directories
or search for <code>index.html</code> or <code>index.htm</code> files.</p>
</div>
<div class="paragraph">
<p>The <code>Content-Type</code> will be set automatically based upon the extension
of the requested file name.
If a content type cannot be determined from
the extension, then <code>application/octet-stream</code> is used.</p>
</div>
</div>
<div class="sect2">
<h3 id="_redirect_handler">Redirect Handler</h3>
<div class="paragraph">
<p>The fourth member is used to arrange for a server redirect from one
URL to another.
The reply will be with status code <em>status</em>, which should be a 3XX
code such as 301, and a <code>Location:</code> header will contain the URL
referenced by <em>location</em>, with any residual suffix from the request
URI appended.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
Use <a href="nng_http_handler_set_tree.3http.html"><code>nng_http_handler_set_tree()</code></a>
to redirect an entire tree.
For example, it is possible to redirect an entire HTTP site to another
HTTPS site by specifying <code>/</code> as the path and then using the base
of the new site, such as <code><a href="https://newsite.example.com" class="bare">https://newsite.example.com</a></code> as the
new location.
</td>
</tr>
</table>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
Be sure to use the appropriate value for <em>status</em>.
Permanent redirection should use 301 and temporary redirections should use 307.
In REST APIs, using a redirection to supply the new location of an object
created with <code>POST</code> should use 303.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="_static_handler">Static Handler</h3>
<div class="paragraph">
<p>The fifth member of this family, <code>nng_http_handler_alloc_static()</code>, creates
a handler to serve up fixed content located in program data.
The client is
sent the <em>data</em>, with <code>Content-Length</code> of <em>size</em> bytes, and <code>Content-Type</code> of
<em>content_type</em>.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_return_values">RETURN VALUES</h2>
<div class="sectionbody">
<div class="paragraph">
<p>These functions return 0 on success, and non-zero otherwise.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_errors">ERRORS</h2>
<div class="sectionbody">
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
<code>NNG_EINVAL</code>
</td>
<td class="hdlist2">
<p>An invalid <em>path</em> was specified.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<code>NNG_ENOMEM</code>
</td>
<td class="hdlist2">
<p>Insufficient free memory exists to allocate a message.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<code>NNG_ENOTSUP</code>
</td>
<td class="hdlist2">
<p>No support for HTTP in the library.</p>
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_see_also">SEE ALSO</h2>
<div class="sectionbody">
<div class="paragraph text-left">
<p><a href="nng_aio_defer.3.html">nng_aio_defer(3)</a>,
<a href="nng_aio_finish.3.html">nng_aio_finish(3)</a>,
<a href="nng_aio_get_input.3.html">nng_aio_get_input(3)</a>,
<a href="nng_aio_set_output.3.html">nng_aio_set_output(3)</a>,
<a href="nng_http_handler_collect_body.3http.html">nng_http_handler_collect_body(3http)</a>,
<a href="nng_http_handler_free.3http.html">nng_http_handler_free(3http)</a>,
<a href="nng_http_handler_set_host.3http.html">nng_http_handler_set_host(3http)</a>,
<a href="nng_http_handler_set_method.3http.html">nng_http_handler_set_method(3http)</a>,
<a href="nng_http_handler_set_tree.3http.html">nng_http_handler_set_tree(3http)</a>,
<a href="nng_http_res_alloc.3http.html">nng_http_res_alloc(3http)</a>,
<a href="nng_http_res_alloc_error.3http.html">nng_http_res_alloc_error(3http)</a>,
<a href="nng_http_server_add_handler.3http.html">nng_http_server_add_handler(3http)</a>,
<a href="nng_strerror.3.html">nng_strerror(3)</a>,
<a href="nng_aio.5.html">nng_aio(5)</a>,
<a href="nng.7.html">nng(7)</a></p>
</div>
</div>
</div>
</div>
<link rel="stylesheet" href="./pygments-default.css">
</body>
</html>
|
