diff options
Diffstat (limited to 'docs/man/nng_http_handler_alloc.3http.adoc')
| -rw-r--r-- | docs/man/nng_http_handler_alloc.3http.adoc | 185 |
1 files changed, 0 insertions, 185 deletions
diff --git a/docs/man/nng_http_handler_alloc.3http.adoc b/docs/man/nng_http_handler_alloc.3http.adoc deleted file mode 100644 index 3eb9674a..00000000 --- a/docs/man/nng_http_handler_alloc.3http.adoc +++ /dev/null @@ -1,185 +0,0 @@ -= nng_http_handler_alloc(3http) -// -// Copyright 2025 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2020 Dirac Research <robert.bielik@dirac.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/http.h> - -typedef struct nng_http_handler nng_http_handler; - -typedef void (*nng_http_hander_func)(nng_http_conn *conn, void *arg, nng_aio *aio); - -int nng_http_handler_alloc(nng_http_handler **hp, const char *path, - nng_http_handler_func cb); - -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_redirect(nng_http_handler **hp, const char *path, - uint16_t status, const char *location); - -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. - -This implementation limits the _path_ length to 1024 bytes, including the -zero termination byte. This does not prevent requests with much longer -URIs from being supported, doing so will require setting the handler -to matching a parent path in the tree using -xref:nng_http_handler_set_tree.3http.adoc[`nng_http_handler_set_tree`()]. - -Additionally each handler has a method it is registered to handle -(the default is `GET`, see -xref:nng_http_handler_set_method.3http.adoc[`nng_http_handler_set_method()`]), and -optionally a 'Host' header it can be matched against (see -xref:nng_http_handler_set_host.3http.adoc[`nng_http_handler_set_host()`]). - -In some cases, a handler may reference a logical tree rather (directory) -rather than just a single element. -(See xref:nng_http_handler_set_tree.3http.adoc[`nng_http_handler_set_tree()`]). - -=== 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 receives the connection on _conn_, and the data that it set -previously with `nng_http_handler_set_data` as the second argument. The -final argument is the _aio_, which must be "finished" to complete the operation. - -The function takes a pointer to an xref:nng_aio.5.adoc[`nng_aio`] structure. - -The handler should obtain `nng_http_res *` response from the -connection (`nng_http_conn_res`) and update it to reflect the final status. - -The handler may call `nng_http_conn_write_res` to send the response, or -it may simply let the framework do so on its behalf. The server will perform -this step if the callback has not already done so. - -Finally, using the xref:nng_aio_finish.3.adoc[`nng_aio_finish()`] 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. - -The _aio_ may be scheduled for deferred completion using the -xref:nng_aio_start.3.adoc[`nng_aio_start()`] function. - -=== 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 file system, -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 requested file name. If a content type cannot be determined from -the extension, then `application/octet-stream` is used. - -The directory handler is created as a tree handler. - -=== 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 requested file name. -If a content type cannot be determined from -the extension, then `application/octet-stream` is used. - -=== Redirect Handler - -The fourth member is used to arrange for a server redirect from one -URL to another. -The reply will be with status code __status__, which should be a 3XX -code such as 301, and a `Location:` header will contain the URL -referenced by __location__, with any residual suffix from the request -URI appended. - -TIP: Use xref:nng_http_handler_set_tree.3http.adoc[`nng_http_handler_set_tree()`] -to redirect an entire tree. -For example, it is possible to redirect an entire HTTP site to another -HTTPS site by specifying `/` as the path and then using the base -of the new site, such as `https://newsite.example.com` as the -new location. - -TIP: Be sure to use the appropriate value for __status__. -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 `POST` should use 303. - -=== Static Handler - -The fifth 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 - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`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 - -[.text-left] -xref:nng_aio_start.3.adoc[nng_aio_start(3)], -xref:nng_aio_finish.3.adoc[nng_aio_finish(3)], -xref:nng_aio_get_input.3.adoc[nng_aio_get_input(3)], -xref:nng_aio_set_output.3.adoc[nng_aio_set_output(3)], -xref:nng_http_handler_collect_body.3http.adoc[nng_http_handler_collect_body(3http)], -xref:nng_http_handler_free.3http.adoc[nng_http_handler_free(3http)], -xref:nng_http_handler_set_host.3http.adoc[nng_http_handler_set_host(3http)], -xref:nng_http_handler_set_method.3http.adoc[nng_http_handler_set_method(3http)], -xref:nng_http_handler_set_tree.3http.adoc[nng_http_handler_set_tree(3http)], -xref:nng_http_server_add_handler.3http.adoc[nng_http_server_add_handler(3http)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng.7.adoc[nng(7)] |