diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/libnng.adoc | 37 | ||||
| -rw-r--r-- | docs/nng_http_conn_write_res.adoc | 9 | ||||
| -rw-r--r-- | docs/nng_http_handler_alloc.adoc | 137 |
3 files changed, 182 insertions, 1 deletions
diff --git a/docs/libnng.adoc b/docs/libnng.adoc index 37bc01c8..6ecf406b 100644 --- a/docs/libnng.adoc +++ b/docs/libnng.adoc @@ -14,7 +14,7 @@ libnng - nanomsg next generation library == SYNOPSIS -*cc* ['flags'] 'files' *-lnng* ['libraries'] +*cc* [_flags_] _files_ *-lnng* [_libraries_] == DESCRIPTION @@ -230,6 +230,41 @@ and connections. | <<nng_http_res_set_version#,nng_http_res_set_version(3)>>|set HTTP response protocol version |=== +==== HTTP Client Functions + +These functions are intended for use with HTTP client applications. + +|=== +| <<nng_http_client_alloc#,nng_http_client_alloc(3)>>|allocate HTTP client +| <<nng_http_client_connect#,nng_http_client_connect(3)>>|establish HTTP client connection +| <<nng_http_client_free#,nng_http_client_free(3)>>|free HTTP client +| <<nng_http_client_get_tls#,nng_http_client_get_tls(3)>>|get HTTP client TLS configuration +| <<nng_http_client_set_tls#,nng_http_client_set_tls(3)>>|set HTTP client TLS configuration +|=== + +==== HTTP Server Functions + +These functions are intended for use with HTTP server applications. + +|=== +| <<nng_http_handler_alloc#,nng_http_handler_alloc(3)>>|allocate HTTP server handler +| <<nng_http_handler_free#,nng_http_handler_free(3)>>|free HTTP server handler +| <<nng_http_handler_get_data#,nng_http_handler_get_data(3)>>|return extra data for HTTP handler +| <<nng_http_handler_set_data#,nng_http_handler_set_data(3)>>|set extra data for HTTP handler +| <<nng_http_handler_set_host#,nng_http_handler_set_host(3)>>|set host for HTTP handler +| <<nng_http_handler_set_method#,nng_http_handler_set_method(3)>>|set method for HTTP handler +| <<nng_http_handler_set_tree#,nng_http_handler_set_tree(3)>>|set HTTP handler to match trees +| <<nng_http_hijack#,nng_http_hijack(3)>>|hijack HTTP server connection +| <<nng_http_server_add_handler#,nng_http_server_add_handler(3)>>|add HTTP server handler +| <<nng_http_server_del_handler#,nng_http_server_del_handler(3)>>|delete HTTP server handler +| <<nng_http_server_get_tls#,nng_http_server_get_tls(3)>>|get HTTP server TLS configuration +| <<nng_http_server_hold#,nng_http_server_get_tls(3)>>|get and hold HTTP server instance +| <<nng_http_server_release#,nng_http_server_get_tls(3)>>|release HTTP server instance +| <<nng_http_server_set_tls#,nng_http_server_set_tls(3)>>|set HTTP server TLS configuration +| <<nng_http_server_start#,nng_http_server_start(3)>>|start HTTP server +| <<nng_http_server_stop#,nng_http_server_stop(3)>>|stop HTTP server +|=== + === TLS Configuration Objects The following functions are used to manipulate transport layer security diff --git a/docs/nng_http_conn_write_res.adoc b/docs/nng_http_conn_write_res.adoc index 8f5a407d..31e438b4 100644 --- a/docs/nng_http_conn_write_res.adoc +++ b/docs/nng_http_conn_write_res.adoc @@ -37,6 +37,15 @@ the operation is signaled via the _aio_, and the final result may be obtained via <<nng_aio_result#,nng_aio_result>>. That result will either be zero or an error code. +=== Persistent Connections + +By default, for `HTTP/1.1` connections, the connection is kept open, and +will be reused to receive new requests. + +If however the _res_ contains a header of `Connection:` with a value +of `Close` (case-insensitive) or the response corresponds to `HTTP/1.0`, +then the connection is immediately after sending the response. + == RETURN VALUES None. 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 <nng/nng.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. + +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_ENOMEM`:: Insufficient free memory exists to allocate a message. +`NNG_ENOTSUP`:: HTTP support not configured. +`NNG_EINVAL`:: An invalid _path_ was specified. + +== 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)>> + +== COPYRIGHT + +{copyright} |