diff options
Diffstat (limited to 'docs/nng_http_handler_alloc.adoc')
| -rw-r--r-- | docs/nng_http_handler_alloc.adoc | 139 |
1 files changed, 0 insertions, 139 deletions
diff --git a/docs/nng_http_handler_alloc.adoc b/docs/nng_http_handler_alloc.adoc deleted file mode 100644 index 023d0400..00000000 --- a/docs/nng_http_handler_alloc.adoc +++ /dev/null @@ -1,139 +0,0 @@ -= nng_http_handler_alloc(3) -// -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_http_handler_alloc - allocate HTTP server handler - -== SYNOPSIS - -[source, c] ------------ -#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#,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#,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#,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#,nng_http_res_alloc(3)>> or -<<nng_http_res_alloc_error#,nng_http_res_alloc_error(3)>>) and store that -in as the first output (index 0) with -<<nng_aio_set_output#,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#,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. - -== SEE ALSO - -<<nng_aio_finish#,nng_aio_finish(3)>>, -<<nng_aio_get_input#,nng_aio_get_input(3)>>, -<<nng_aio_set_output#,nng_aio_set_output(3)>>, -<<nng_http_handler_free#,nng_http_handler_free(3)>>, -<<nng_http_handler_set_host#,nng_http_handler_set_host(3)>>, -<<nng_http_handler_set_method#,nng_http_handler_set_method(3)>>, -<<nng_http_handler_set_tree#,nng_http_handler_set_tree(3)>>, -<<nng_http_res_alloc#,nng_http_res_alloc(3)>>, -<<nng_http_res_alloc_error#,nng_http_res_alloc_error(3)>>, -<<nng_http_server_add_handler#,nng_http_server_add_handler(3)>>, -<<nng_strerror#,nng_strerror(3)>>, -<<nng#,nng(7)>> |