From 3b33f6878ee628da22fd4451f248c036aae231ed Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Mon, 5 Feb 2018 15:27:31 -0800 Subject: Inital swag at HTTP handler docs. We will need to document nng_aio_set_output, and both document and create an nng_aio_finish() function. --- docs/nng_http_handler_alloc.adoc | 137 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 docs/nng_http_handler_alloc.adoc (limited to 'docs/nng_http_handler_alloc.adoc') diff --git a/docs/nng_http_handler_alloc.adoc b/docs/nng_http_handler_alloc.adoc new file mode 100644 index 00000000..cde5b052 --- /dev/null +++ b/docs/nng_http_handler_alloc.adoc @@ -0,0 +1,137 @@ += nng_http_handler_alloc(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + \ + Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + \ + {blank} + \ + This document is supplied under the terms of the \ + https://opensource.org/licenses/MIT[MIT License]. + +== NAME + +nng_http_handler_alloc - allocate HTTP server handler + +== SYNOPSIS + +[source, c] +----------- +#include + +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. + +In some cases, a handler may reference a logical tree rather (directory) +rather than just a single element. +(See <>). + +=== 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 +<>): + + 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 +<> or +<>) and store that +in as the first output (index 0) with +<>. + +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 <> 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_ENOMEM`:: Insufficient free memory exists to allocate a message. +`NNG_ENOTSUP`:: HTTP support not configured. +`NNG_EINVAL`:: An invalid _path_ was specified. + +== SEE ALSO + +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<> + +== COPYRIGHT + +{copyright} -- cgit v1.2.3-70-g09d2