diff options
Diffstat (limited to 'docs/man/nng_http_handler_alloc.3http.adoc')
| -rw-r--r-- | docs/man/nng_http_handler_alloc.3http.adoc | 29 |
1 files changed, 13 insertions, 16 deletions
diff --git a/docs/man/nng_http_handler_alloc.3http.adoc b/docs/man/nng_http_handler_alloc.3http.adoc index 9291fd56..23171450 100644 --- a/docs/man/nng_http_handler_alloc.3http.adoc +++ b/docs/man/nng_http_handler_alloc.3http.adoc @@ -1,6 +1,6 @@ = nng_http_handler_alloc(3http) // -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// 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> // @@ -23,8 +23,10 @@ nng_http_handler_alloc - allocate HTTP server handler 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, - void (*func)(nng_aio *); + nng_http_handler_func cb); int nng_http_handler_alloc_directory(nng_http_handler **hp, const char *path, const char *dirname); @@ -72,24 +74,19 @@ rather than just a single element. 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 xref:nng_aio.5.adoc[`nng_aio`] structure. -The _aio_ will be passed with the following input values (retrieved with -xref:nng_aio_get_input.3.adoc[`nng_aio_get_input()`]): +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. - 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 function takes a pointer to an xref:nng_aio.5.adoc[`nng_aio`] structure. -The handler should create an `nng_http_res *` response (such as via -xref:nng_http_res_alloc.3http.adoc[`nng_http_res_alloc()`] or -xref:nng_http_res_alloc_error.3http.adoc[`nng_http_res_alloc_error()`]) and store that -in as the first output (index 0) with -xref:nng_aio_set_output.3.adoc[`nng_aio_set_output()`]. +The handler should obtain `nng_http_res *` response from the +connection (`nng_http_conn_res`) and update it to reflect the final status. -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. +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. |