= nng_http_handler_alloc(3http) // // Copyright 2025 Staysail Systems, Inc. // Copyright 2018 Capitar IT Group BV // Copyright 2020 Dirac Research // // 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 #include 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 initially in exclusive mode (see xref:nng_http_handler_set_tree.3http.adoc[nng_http_handler_set_tree_exclusive]). This can be changed by calling xref:nng_http_handler_set_tree.3http.adoc[nng_http_handler_set_tree(3http)] after creating the directory 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_handler_set_tree.3http.adoc[nng_http_handler_set_tree_exclusive(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)]