SYNOPSIS
#include <nng/nng.h>
#include <nng/supplemental/http/http.h>
typedef struct nng_http_handler nng_http_handler;
int nng_http_handler_alloc(nng_http_handler **hp, const char *path,
void (*func)(nng_aio *);
int nng_http_handler_alloc_directory(nng_http_handler **hp, const char *path,
const char *dirname);
int nng_http_handler_alloc_file(nng_http_handler **hp, const char *path,
const char *filename);
int nng_http_handler_alloc_static(nng_http_handler **hp, const char *path,
const void *data, size_t size, const char *content_type);DESCRIPTION
The nng_http_handler_alloc() 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 hp.
Every handler has a Request-URI to which it refers, which is determined by the path argument. Only the path component of the Request URI is considered when determining whether the handler should be called.
Additionally each handler has a method it is registered to handle (the default is "GET", see nng_http_handler_set_method(3)), and optionally a 'Host' header it can be matched against (see <<nng_http_handler_set_host#,nng_http_handler_set_host(3)).
In some cases, a handler may reference a logical tree rather (directory) rather than just a single element. (See nng_http_handler_set_tree(3)).
Custom Handler
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 nng_aio structure. That
structure will be passed with the following input values (retrieved with
nng_aio_get_input(3)):
- 0:
nng_http_req *request -
The client’s HTTP request.
- 1:
nng_http_handler *handler -
Pointer to the handler object.
- 2:
nng_http_conn *conn -
The underlying HTTP connection.
The handler should create an nng_http_res * response (such as via
nng_http_res_alloc(3) or
nng_http_res_alloc_error(3)) and store that
in as the first output (index 0) with
nng_aio_set_output(3).
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 aio should be NULL.
Finally, using the nng_aio_finish(3) function, the aio 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.
Directory Handler
The second member of this family, nng_http_handler_alloc_directory(), creates
a handler configured to serve a directory tree. The uri is taken as
the root, and files are served from the directory tree rooted at path.
When the client Request-URI resolves to a directory in the filesystem,
the handler looks first for a file named index.html or index.htm. If
one is found, then that file is returned back to the client. If no such
index file exists, then an NNG_HTTP_STATUS_NOT_FOUND (404) error is
sent back to the client.
The Content-Type will be set automatically based upon the extension
of the requsted file name. If a content type cannot be determined from
the extension, then application/octet-stream is used.
File Handler
The third member of this family, nng_http_handler_alloc_file(), creates
a handler to serve up a single file; it does not traverse directories
or search for index.html or index.htm files.
The Content-Type will be set automatically based upon the extension
of the requsted file name. If a content type cannot be determined from
the extension, then application/octet-stream is used.
Static Handler
The fourth member of this family, nng_http_handler_alloc_static(), creates
a handler to serve up fixed content located in program data. The client is
sent the data, with Content-Length of size bytes, and Content-Type of
content_type.
RETURN VALUES
This function returns 0 on success, and non-zero otherwise.
ERRORS
NNG_EINVAL-
An invalid path was specified.
NNG_ENOMEM-
Insufficient free memory exists to allocate a message.
NNG_ENOTSUP-
No support for HTTP in the library.