diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/man/libnng.3.adoc | 1 | ||||
| -rw-r--r-- | docs/man/nng_http_handler_alloc.3http.adoc | 1 | ||||
| -rw-r--r-- | docs/man/nng_http_handler_collect_body.3http.adoc | 78 |
3 files changed, 80 insertions, 0 deletions
diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index 0a62f931..25e8b08d 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -356,6 +356,7 @@ These functions are intended for use with HTTP server applications. |=== |<<nng_http_handler_alloc.3http#,nng_http_handler_alloc()>>|allocate HTTP server handler +|<<nng_http_handler_collect_body.3http#,nng_http_handler_collect_body()>>|set HTTP handler to collect request body |<<nng_http_handler_free.3http#,nng_http_handler_free()>>|free HTTP server handler |<<nng_http_handler_get_data.3http#,nng_http_handler_get_data()>>|return extra data for HTTP handler |<<nng_http_handler_set_data.3http#,nng_http_handler_set_data()>>|set extra data for HTTP handler diff --git a/docs/man/nng_http_handler_alloc.3http.adoc b/docs/man/nng_http_handler_alloc.3http.adoc index 523b5328..d5861d14 100644 --- a/docs/man/nng_http_handler_alloc.3http.adoc +++ b/docs/man/nng_http_handler_alloc.3http.adoc @@ -149,6 +149,7 @@ This function returns 0 on success, and non-zero otherwise. <<nng_aio_finish.3#,nng_aio_finish(3)>>, <<nng_aio_get_input.3#,nng_aio_get_input(3)>>, <<nng_aio_set_output.3#,nng_aio_set_output(3)>>, +<<nng_http_handler_collect_body.3http#,nng_http_handler_collect_body(3http)>>, <<nng_http_handler_free.3http#,nng_http_handler_free(3http)>>, <<nng_http_handler_set_host.3http#,nng_http_handler_set_host(3http)>>, <<nng_http_handler_set_method.3http#,nng_http_handler_set_method(3http)>>, diff --git a/docs/man/nng_http_handler_collect_body.3http.adoc b/docs/man/nng_http_handler_collect_body.3http.adoc new file mode 100644 index 00000000..875f32c4 --- /dev/null +++ b/docs/man/nng_http_handler_collect_body.3http.adoc @@ -0,0 +1,78 @@ += nng_http_handler_collect_body(3http) +// +// 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_collect_body - set HTTP handler to collect request body + +== SYNOPSIS + +[source, c] +---- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +int nng_http_handler_collect_body(nng_http_handler *handler, bool want, size_t maxsz); +---- + +== DESCRIPTION + +The `nng_http_handler_collect_data()` function causes the _handler_ to +collect any request body that was submitted with the request, and attach +it to the `nng_http_req` before the handler is called. + +Subsequently the data can be retrieved by the handler from the request with the +`<<nng_http_req_get_data.3http#,nng_http_req_get_data()>>` function. + +The collection is enabled if _want_ is true. +Furthermore, the data that the client may sent is limited by the +value of _maxsz_. +If the client attempts to send more data than _maxsz_, then the +request will be terminated with a 400 "`Bad Request`" status. + +TIP: Limiting the size of incoming request data can provide protection +against denial of service attacks, as a buffer of the client-supplied +size must be allocated to receive the data. + +In order to provide an unlimited size, use `(size_t)-1` for _maxsz_. +The value `0` for _maxsz_ can be used to prevent any data from being passed +by the client. + +The built-in handlers for files, directories, and static data limit the +_maxsz_ to zero by default. +Otherwise the default setting is to enable this capability with a default +value of _maxsz_ of 1 megabyte. + +NOTE: The handler looks for data indicated by the `Content-Length:` HTTP +header. +If this header is absent, the request is assumed not to contain any data. + +NOTE: This specifically does not support the `Chunked` transfer-encoding. +This is considered a bug, and is a deficiency for full HTTP/1.1 compliance. +However, few clients send data in this format, so in practice this should +not create few limitations. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +[.text-left] +<<nng_http_handler_alloc.3http#,nng_http_handler_alloc(3http)>>, +<<nng_http_server_add_handler.3http#,nng_http_server_add_handler(3http)>>, +<<nng_http_req_get_data.3http#,nng_http_req_get_data(3http)>>, +<<nng.7#,nng(7)>> |