diff options
| author | Garrett D'Amore <garrett@damore.org> | 2025-01-06 15:20:09 -0800 |
|---|---|---|
| committer | Garrett D'Amore <garrett@damore.org> | 2025-01-09 23:22:56 -0800 |
| commit | 73f50e2679525e7df8734c875a3c12732565f953 (patch) | |
| tree | 23bd167dfcd95305b58a29c142b51879011f63b2 /docs/man | |
| parent | a381af4f5ca79576a4a9b461529a0f22fcf1e088 (diff) | |
| download | nng-http-client-trans.tar.gz nng-http-client-trans.tar.bz2 nng-http-client-trans.zip | |
http: The big HTTP API refactoring of January 2025.v2.0.0-alpha.3http-client-trans
This represents a major change in the HTTP code base, consisting
of a complete revamp of the HTTP API. The changes here are too
numerous to mention, but the end result should be a vastly
simpler API for both server and client applications.
Many needless allocations were removed by providing fixed buffers
for various parameters and headers when possible.
A few bugs were fixed. Most especially we have fixed some bugs
around very large URIs and headers, and we have also addressed
conformance bugs to more closely conform to RFCs 9110 and 9112.
As part of this work, the APIs for WebSockets changed slightly
as well. In particular the properties available for accessing
headers have changed.
There is still documentation conversion work to do, and additional
functionality (such as proper support for chunked transfers), but
this is a big step in the right direction.
Diffstat (limited to 'docs/man')
73 files changed, 47 insertions, 3225 deletions
diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index f6366942..5bc947b1 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -99,48 +99,16 @@ The following functions are used to work with HTTP requests, responses, and connections. |=== -|xref:nng_http_conn_close.3http.adoc[nng_http_conn_close()]|close HTTP connection -|xref:nng_http_conn_read.3http.adoc[nng_http_conn_read()]|read from HTTP connection -|xref:nng_http_conn_read_all.3http.adoc[nng_http_conn_read_all()]|read all from HTTP connection |xref:nng_http_conn_read_req.3http.adoc[nng_http_conn_read_req()]|read HTTP request |xref:nng_http_conn_read_res.3http.adoc[nng_http_conn_read_res()]|read HTTP response -|xref:nng_http_conn_write.3http.adoc[nng_http_conn_write()]|write to HTTP connection -|xref:nng_http_conn_write_all.3http.adoc[nng_http_conn_write_all()]|write all to HTTP connection |xref:nng_http_conn_write_req.3http.adoc[nng_http_conn_write_req()]|write HTTP request |xref:nng_http_conn_write_res.3http.adoc[nng_http_conn_write_res()]|write HTTP response -|xref:nng_http_req_add_header.3http.adoc[nng_http_req_add_header()]|add HTTP request header -|xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc()]|allocate HTTP request structure -|xref:nng_http_req_copy_data.3http.adoc[nng_http_req_copy_data()]|copy HTTP request body -|xref:nng_http_req_del_header.3http.adoc[nng_http_req_del_header()]|delete HTTP request header -|xref:nng_http_req_free.3http.adoc[nng_http_req_free()]|free HTTP request structure |xref:nng_http_req_get_data.3http.adoc[nng_http_req_get_data()]|get HTTP request body -|xref:nng_http_req_get_header.3http.adoc[nng_http_req_get_header()]|return HTTP request header -|xref:nng_http_req_get_method.3http.adoc[nng_http_req_get_method()]|return HTTP request method -|xref:nng_http_req_get_uri.3http.adoc[nng_http_req_get_uri()]|return HTTP request URI -|xref:nng_http_req_get_version.3http.adoc[nng_http_req_get_version()]|return HTTP request protocol version -|xref:nng_http_req_reset.3http.adoc[nng_http_req_reset()]|reset HTTP request structure |xref:nng_http_req_set_data.3http.adoc[nng_http_req_set_data()]|set HTTP request body -|xref:nng_http_req_set_header.3http.adoc[nng_http_req_set_header()]|set HTTP request header -|xref:nng_http_req_set_method.3http.adoc[nng_http_req_set_method()]|set HTTP request method -|xref:nng_http_req_set_uri.3http.adoc[nng_http_req_set_uri()]|set HTTP request URI -|xref:nng_http_req_set_version.3http.adoc[nng_http_req_set_version()]|set HTTP request protocol version -|xref:nng_http_res_add_header.3http.adoc[nng_http_res_add_header()]|add HTTP response header -|xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc()]|allocate HTTP response structure -|xref:nng_http_res_alloc_error.3http.adoc[nng_http_res_alloc_error()]|allocate HTTP error response |xref:nng_http_res_copy_data.3http.adoc[nng_http_res_copy_data()]|copy HTTP response body -|xref:nng_http_res_del_header.3http.adoc[nng_http_res_del_header()]|delete HTTP response header -|xref:nng_http_res_free.3http.adoc[nng_http_res_free()]|free HTTP response structure |xref:nng_http_res_get_data.3http.adoc[nng_http_res_get_data()]|get HTTP response body |xref:nng_http_res_get_header.3http.adoc[nng_http_res_get_header()]|return HTTP response header -|xref:nng_http_res_get_reason.3http.adoc[nng_http_res_get_reason()]|return HTTP response reason -|xref:nng_http_res_get_status.3http.adoc[nng_http_res_get_status()]|return HTTP response status -|xref:nng_http_res_get_version.3http.adoc[nng_http_res_get_version()]|return HTTP response protocol version -|xref:nng_http_res_reset.3http.adoc[nng_http_res_reset()]|reset HTTP response structure |xref:nng_http_res_set_data.3http.adoc[nng_http_res_set_data()]|set HTTP response body -|xref:nng_http_res_set_header.3http.adoc[nng_http_res_set_header()]|set HTTP response header -|xref:nng_http_res_set_reason.3http.adoc[nng_http_res_set_reason()]|set HTTP response reason -|xref:nng_http_res_set_status.3http.adoc[nng_http_res_set_status()]|set HTTP response status -|xref:nng_http_res_set_version.3http.adoc[nng_http_res_set_version()]|set HTTP response protocol version |=== ==== HTTP Client Functions @@ -148,12 +116,6 @@ and connections. These functions are intended for use with HTTP client applications. |=== -|xref:nng_http_client_alloc.3http.adoc[nng_http_client_alloc()]|allocate HTTP client -|xref:nng_http_client_connect.3http.adoc[nng_http_client_connect()]|establish HTTP client connection -|xref:nng_http_client_free.3http.adoc[nng_http_client_free()]|free HTTP client -|xref:nng_http_client_get_tls.3http.adoc[nng_http_client_get_tls()]|get HTTP client TLS configuration -|xref:nng_http_client_set_tls.3http.adoc[nng_http_client_set_tls()]|set HTTP client TLS configuration -|xref:nng_http_client_transact.3http.adoc[nng_http_client_transact()]|perform one HTTP transaction |xref:nng_http_conn_transact.3http.adoc[nng_http_conn_transact()]|perform one HTTP transaction on connection |=== @@ -170,7 +132,6 @@ These functions are intended for use with HTTP server applications. |xref:nng_http_handler_set_host.3http.adoc[nng_http_handler_set_host()]|set host for HTTP handler |xref:nng_http_handler_set_method.3http.adoc[nng_http_handler_set_method()]|set HTTP handler method |xref:nng_http_handler_set_tree.3http.adoc[nng_http_handler_set_tree()]|set HTTP handler to match trees -|xref:nng_http_hijack.3http.adoc[nng_http_hijack()]|hijack HTTP server connection |xref:nng_http_server_add_handler.3http.adoc[nng_http_server_add_handler()]|add HTTP server handler |xref:nng_http_server_del_handler.3http.adoc[nng_http_server_del_handler()]|delete HTTP server handler |xref:nng_http_server_get_addr.3http.adoc[nng_http_server_get_addr()]|get HTTP server address diff --git a/docs/man/nng.7.adoc b/docs/man/nng.7.adoc index 2c5d0d72..e1680e1a 100644 --- a/docs/man/nng.7.adoc +++ b/docs/man/nng.7.adoc @@ -73,7 +73,6 @@ xref:nng_socket.7.adoc[nng_socket(7)]:: BSD socket transport xref:nng_tls.7.adoc[nng_tls(7)]:: TLSv1.2 over TCP transport xref:nng_tcp.7.adoc[nng_tcp(7)]:: TCP (and TCPv6) transport xref:nng_ws.7.adoc[nng_ws(7)]:: WebSocket transport -xref:nng_zerotier.7.adoc[nng_zerotier(7)]:: ZeroTier transport === Conceptual Overview diff --git a/docs/man/nng_http_client_alloc.3http.adoc b/docs/man/nng_http_client_alloc.3http.adoc deleted file mode 100644 index f433001a..00000000 --- a/docs/man/nng_http_client_alloc.3http.adoc +++ /dev/null @@ -1,49 +0,0 @@ -= nng_http_client_alloc(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_client_alloc - allocate HTTP client - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -int nng_http_client_alloc(nng_http_client *clientp, const nng_url *url); ----- - -== DESCRIPTION - -The `nng_http_client_alloc()` allocates an HTTP client suitable for -connecting to the server identified by _url_ and stores a pointer to -it in the location referenced by _clientp_. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists. -`NNG_ENOTSUP`:: HTTP not supported. - -== SEE ALSO - -[.text-left] -xref:nng_http_client_connect.3http.adoc[nng_http_client_connect(3http)], -xref:nng_http_client_free.3http.adoc[nng_http_client_free(3http)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_url_parse.3.adoc[nng_url_parse(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_client_connect.3http.adoc b/docs/man/nng_http_client_connect.3http.adoc deleted file mode 100644 index e2a3e23c..00000000 --- a/docs/man/nng_http_client_connect.3http.adoc +++ /dev/null @@ -1,98 +0,0 @@ -= nng_http_client_connect(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_client_connect - establish HTTP client connection - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -void nng_http_client_connect(nng_http_client *client, nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_http_client_connect()` starts the process of establishing an HTTP -connection from _client_ to the server that was indicated in the URL that -_client_ was configured with. - -The result of the operation will be stored in the _aio_ when the operation -is complete, and will be obtainable via -xref:nng_aio_result.3.adoc[`nng_aio_result()`]. - -On success, a pointer to the underlying HTTP client (type `nng_http_conn *`) -will be stored in the first output result of the _aio_, and can be -obtained by -xref:nng_aio_get_output.3.adoc[`nng_aio_get_output()`] with an _index_ of zero (0). - -== RETURN VALUES - -None. - -== ERRORS - -[horizontal] -`NNG_EADDRINVAL`:: The client is configured with an invalid address. -`NNG_ECANCELED`:: The operation was aborted. -`NNG_ECONNREFUSED`:: The TCP connection was refused by the server. -`NNG_ECONNRESET`:: The TCP connection was reset by the server. -`NNG_ENOMEM`:: Insufficient free memory exists. - -== EXAMPLE - -[source, c] ----- - nng_aio *aio; - nng_url *url; - nng_http_client *client; - nng_http_conn *conn; - int rv; - - // Error checks elided for clarity. - nng_url_parse(&url, "http://www.google.com"); - nng_aio_alloc(&aio, NULL, NULL); - nng_http_client_alloc(&client, url); - - nng_http_client_connect(client, aio); - - // Wait for connection to establish (or attempt to fail). - nng_aio_wait(aio); - - if ((rv = nng_aio_result(aio)) != 0) { - printf("Connection failed: %s\n", nng_strerror(rv)); - } else { - // Connection established, get it. - conn = nng_aio_get_output(aio, 0); - - // ... do something with it here - - // Close the connection when done to avoid leaking it. - nng_http_conn_close(conn); - } ----- - -== SEE ALSO - -[.text-left] -xref:nng_aio_get_output.3.adoc[nng_aio_get_output(3)], -xref:nng_aio_result.3.adoc[nng_aio_result(3)], -xref:nng_aio_wait.3.adoc[nng_aio_wait(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_http_client_alloc.3http.adoc[nng_http_client_alloc(3http)], -xref:nng_http_conn_close.3http.adoc[nng_http_conn_close(3http)], -xref:nng_http_conn_read.3http.adoc[nng_http_conn_read(3http)], -xref:nng_http_conn_write.3http.adoc[nng_http_conn_write(3http)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_client_free.3http.adoc b/docs/man/nng_http_client_free.3http.adoc deleted file mode 100644 index 2343672c..00000000 --- a/docs/man/nng_http_client_free.3http.adoc +++ /dev/null @@ -1,48 +0,0 @@ -= nng_http_client_free(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_client_free - free HTTP client - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -void nng_http_client_free(nng_http_client *client); ----- - -== DESCRIPTION - -The `nng_http_client_free()` frees the HTTP client and any associated -resources referenced by _client_. - -NOTE: Any connections created by -xref:nng_http_client_connect.3http.adoc[`nng_http_client_connect()`] are unaffected, -and so the caller must close those explicitly if desired. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_http_client_alloc.3http.adoc[nng_http_client_alloc(3)], -xref:nng_http_client_connect.3http.adoc[nng_http_client_connect(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_client_get_tls.3http.adoc b/docs/man/nng_http_client_get_tls.3http.adoc deleted file mode 100644 index 89f03029..00000000 --- a/docs/man/nng_http_client_get_tls.3http.adoc +++ /dev/null @@ -1,59 +0,0 @@ -= nng_http_client_get_tls(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_client_get_tls - get HTTP client TLS configuration - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -int nng_http_client_get_tls(nng_http_client *client, nng_tls_config **cfgp); ----- - -== DESCRIPTION - -The `nng_http_client_get_tls()` obtains the TLS configuration of _client_ and -saves a pointer to it in the address referenced by _cfgp_. - -The object will be returned with an extra hold (see -xref:nng_tls_config_hold.3tls.adoc[`nng_tls_config_hold()`]) -placed on it on behalf of the caller. -The caller should free this hold by calling -xref:nng_tls_config_free.3tls.adoc[`nng_tls_config_free()`] with it is done -with the TLS configuration. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_EINVAL`:: TLS not configured on client. -`NNG_ENOMEM`:: Insufficient free memory exists. -`NNG_ENOTSUP`:: Either HTTP or TLS not supported. - -== SEE ALSO - -[.text-left] -xref:nng_http_client_alloc.3http.adoc[nng_http_client_alloc(3http)], -xref:nng_http_client_connect.3http.adoc[nng_http_client_connect(3http)], -xref:nng_http_client_set_tls.3http.adoc[nng_http_client_set_tls(3http)], -xref:nng_tls_config_alloc.3tls.adoc[nng_tls_config_alloc(3tls)], -xref:nng_tls_config_free.3tls.adoc[nng_tls_config_free(3tls)], -xref:nng_tls_config_hold.3tls.adoc[nng_tls_config_hold(3tls)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_client_set_tls.3http.adoc b/docs/man/nng_http_client_set_tls.3http.adoc deleted file mode 100644 index 023b8a4e..00000000 --- a/docs/man/nng_http_client_set_tls.3http.adoc +++ /dev/null @@ -1,57 +0,0 @@ -= nng_http_client_set_tls(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_client_set_tls - set HTTP client TLS configuration - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -int nng_http_client_set_tls(nng_http_client *client, nng_tls_config *cfg); ----- - -== DESCRIPTION - -The `nng_http_client_set_tls()` sets the TLS configuration of _client_ to _cfg_. - -This change overwrites any previous TLS configuration. - -IMPORTANT: This also invalidates any previously obtained values from -xref:nng_http_client_get_tls.3http.adoc[`nng_http_client_get_tls()`]. - -NOTE: Any connections established with -xref:nng_http_client_connect.3http.adoc[`nng_http_client_connect()`] -will continue to use any TLS configuration that they were started with. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists. -`NNG_ENOTSUP`:: Either HTTP or TLS not supported. - -== SEE ALSO - -[.text-left] -xref:nng_http_client_alloc.3http.adoc[nng_http_client_alloc(3http)], -xref:nng_http_client_connect.3http.adoc[nng_http_client_connect(3http)], -xref:nng_http_client_get_tls.3http.adoc[nng_http_client_get_tls(3http)], -xref:nng_tls_config_alloc.3tls.adoc[nng_tls_config_alloc(3tls)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_client_transact.3http.adoc b/docs/man/nng_http_client_transact.3http.adoc deleted file mode 100644 index 0585fa7e..00000000 --- a/docs/man/nng_http_client_transact.3http.adoc +++ /dev/null @@ -1,84 +0,0 @@ -= nng_http_client_transact(3http) -// -// Copyright 2020 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_client_transact - perform one HTTP transaction - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -void nng_http_client_transact(nng_http_client *client, nng_http_req *req, - nng_http_res *res, nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_http_client_transact()` function is used to perform a complete -HTTP exchange. -It creates a new connection using _client_, performs the transaction by -sending the request _req_ -(and attached body data) to the remote server, then reading the response -_res_, and finally closes the connection that it created. -The entire response is read, including any associated body, which can -subsequently be obtained using -xref:nng_http_res_get_data.3http.adoc[`nng_http_res_get_data()`]. - -This function is intended to make creation of client applications easier, -by performing multiple asynchronous operations required to complete an -entire HTTP transaction. - -A similar function, -xref:nng_http_conn_transact.3http.adoc[`nng_http_conn_transact()`], -exists. -That function behaves similarily, but uses an existing connection, which -can be reused. - -WARNING: If the remote server tries to send an extremely large buffer, -then a corresponding allocation will be made, which can lead to denial -of service attacks. -Client applications should take care to use this only with reasonably -trust-worthy servers. - -This function returns immediately, with no return value. -Completion of the operation is signaled via the _aio_, and the final result -may be obtained via xref:nng_aio_result.3.adoc[`nng_aio_result()`]. -That result will either be zero or an error code. - -== RETURN VALUES - -None. - -== ERRORS - -[horizontal] -`NNG_ECANCELED`:: The operation was canceled. -`NNG_ECLOSED`:: The connection was closed. -`NNG_ECONNRESET`:: The peer closed the connection. -`NNG_ENOMEM`:: Insufficient free memory to perform the operation. -`NNG_ENOTSUP`:: HTTP operations are not supported, or peer sent chunked encoding. -`NNG_EPROTO`:: An HTTP protocol error occurred. -`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. - -== SEE ALSO - -[.text-left] -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_result.3.adoc[nng_aio_result(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_http_client_connect.3http.adoc[nng_http_client_connect(3http)], -xref:nng_http_conn_transact.3http.adoc[nng_http_conn_transact(3http)], -xref:nng_http_res_get_data.3http.adoc[nng_http_res_get_data(3http)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_conn_close.3http.adoc b/docs/man/nng_http_conn_close.3http.adoc deleted file mode 100644 index 95c266e2..00000000 --- a/docs/man/nng_http_conn_close.3http.adoc +++ /dev/null @@ -1,47 +0,0 @@ -= nng_http_conn_close(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_conn_close - close HTTP connection - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -void nng_http_conn_close(nng_http_conn *conn); ----- - -== DESCRIPTION - -The `nng_http_conn_close()` function closes the supplied HTTP connection _conn_, -including any disposing of any underlying file descriptors or related resources. - -Once this function, no further access to the _conn_ structure may be made. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_http_client_connect.3http.adoc[nng_http_client_connect(3http)], -xref:nng_http_handler_alloc.3http.adoc[nng_http_handler_alloc(3http)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_conn_read.3http.adoc b/docs/man/nng_http_conn_read.3http.adoc deleted file mode 100644 index dfb6e08c..00000000 --- a/docs/man/nng_http_conn_read.3http.adoc +++ /dev/null @@ -1,77 +0,0 @@ -= nng_http_conn_read(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_conn_read - read from HTTP connection - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -void nng_http_conn_read(nng_http_conn *conn, nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_http_conn_read()` function starts an asynchronous read from the -HTTP connection _conn_, into the scatter/gather vector located in the -asynchronous I/O structure _aio_. - -NOTE: The xref:nng_aio_set_iov.3.adoc[`nng_aio_set_iov()`] function must have been -called first, to set the scatter/gather vector for _aio_. - -This function returns immediately, with no return value. -Completion of the operation is signaled via the _aio_, -and the final result may be obtained via -xref:nng_aio_result.3.adoc[`nng_aio_result()`]. -That result will either be zero or an error code. - -The I/O operation completes as soon as at least one byte has been -read, or an error has occurred. -Therefore, the number of bytes read may be less than requested. -The actual number of bytes read can be determined with -xref:nng_aio_count.3.adoc[`nng_aio_count()`]. - -TIP: This function is intended to facilitate uses cases that involve changing -the protocol from HTTP, such as WebSocket. -Most applications will never need to use this function. - -== RETURN VALUES - -None. - -== ERRORS - -[horizontal] -`NNG_ECANCELED`:: The operation was canceled. -`NNG_ECLOSED`:: The connection was closed. -`NNG_ECONNRESET`:: The peer closed the connection. -`NNG_EINVAL`:: The _aio_ does not contain a valid scatter/gather vector. -`NNG_ENOMEM`:: Insufficient free memory to perform the operation. -`NNG_ENOTSUP`:: HTTP operations are not supported. -`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. - -== SEE ALSO - -[.text-left] -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_count.3.adoc[nng_aio_count(3)], -xref:nng_aio_result.3.adoc[nng_aio_result(3)], -xref:nng_aio_set_iov.3.adoc[nng_aio_set_iov(3)], -xref:nng_http_handler_alloc.3http.adoc[nng_http_handler_alloc(3http)], -xref:nng_http_client_connect.3http.adoc[nng_http_client_connect(3http)], -xref:nng_http_conn_read_all.3http.adoc[nng_http_conn_read_all(3http)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_conn_read_all.3http.adoc b/docs/man/nng_http_conn_read_all.3http.adoc deleted file mode 100644 index 21b892f0..00000000 --- a/docs/man/nng_http_conn_read_all.3http.adoc +++ /dev/null @@ -1,78 +0,0 @@ -= nng_http_conn_read_all(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_conn_read_all - read all from HTTP connection - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -void nng_http_conn_read_all(nng_http_conn *conn, nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_http_conn_read_all()` function starts an asynchronous read from the -HTTP connection _conn_, into the scatter/gather vector located in the -asynchronous I/O structure _aio_. - -NOTE: The xref:nng_aio_set_iov.3.adoc[`nng_aio_set_iov()`] function must have been -called first, to set the scatter/gather vector for _aio_. - -This function returns immediately, with no return value. -Completion of the operation is signaled via the _aio_, and the final result -may be obtained via xref:nng_aio_result.3.adoc[`nng_aio_result()`]. -That result will either be zero or an error code. - -The I/O operation completes only when the entire amount of data -requested has been read, or an error has occurred. -If the operation -completes successfully, then the entire requested data has been read. - -It is still possible for a partial read to complete in the event of an error. -The actual number of bytes read can be determined with -xref:nng_aio_count.3.adoc[`nng_aio_count()`]. - -TIP: The main purpose for this function is to facilitate reading HTTP -body content, after first determining the length of the body content -from the relevant HTTP headers (typically `Content-Length`). - -== RETURN VALUES - -None. - -== ERRORS - -[horizontal] -`NNG_ECANCELED`:: The operation was canceled. -`NNG_ECLOSED`:: The connection was closed. -`NNG_ECONNRESET`:: The peer closed the connection. -`NNG_EINVAL`:: The _aio_ does not contain a valid scatter/gather vector. -`NNG_ENOMEM`:: Insufficient free memory to perform the operation. -`NNG_ENOTSUP`:: HTTP operations are not supported. -`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. - -== SEE ALSO - -[.text-left] -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_count.3.adoc[nng_aio_count(3)], -xref:nng_aio_result.3.adoc[nng_aio_result(3)], -xref:nng_aio_set_iov.3.adoc[nng_aio_set_iov(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_http_client_connect.3http.adoc[nng_http_client_connect(3)], -xref:nng_http_conn_read.3http.adoc[nng_http_conn_read(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_conn_read_req.3http.adoc b/docs/man/nng_http_conn_read_req.3http.adoc deleted file mode 100644 index 4a8d3e05..00000000 --- a/docs/man/nng_http_conn_read_req.3http.adoc +++ /dev/null @@ -1,66 +0,0 @@ -= nng_http_conn_read_req(3http) -// -// Copyright 2025 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_conn_read_req - read HTTP request - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -void nng_http_conn_read_req(nng_http_conn *conn, nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_http_conn_read_req()` function starts an asynchronous read from the -HTTP connection _conn_, reading an HTTP request into the request object -associated with _conn_, including all of the related headers. -(The request object can be obtained via `nng_http_conn_req()`. - -NOTE: Any HTTP entity/body data associated with the request is *not* read -automatically. -The caller should use -xref:nng_http_conn_read_all.3http.adoc[`nng_http_conn_read_all()`] -to read the entity data, based on the details of the request itself. - -This function returns immediately, with no return value. -Completion of the operation is signaled via the _aio_, and the final result -may be obtained via xref:nng_aio_result.3.adoc[`nng_aio_result()`]. -That result will either be zero or an error code. - -== RETURN VALUES - -None. - -== ERRORS - -[horizontal] -`NNG_ECANCELED`:: The operation was canceled. -`NNG_ECLOSED`:: The connection was closed. -`NNG_ECONNRESET`:: The peer closed the connection. -`NNG_ENOMEM`:: Insufficient free memory to perform the operation. -`NNG_ENOTSUP`:: HTTP operations are not supported. -`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. - -== SEE ALSO - -[.text-left] -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_result.3.adoc[nng_aio_result(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_http_client_connect.3http.adoc[nng_http_client_connect(3http)], -xref:nng_http_conn_read_all.3http.adoc[nng_http_conn_read_all(3http)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_conn_read_res.3http.adoc b/docs/man/nng_http_conn_read_res.3http.adoc deleted file mode 100644 index ff5cd7a3..00000000 --- a/docs/man/nng_http_conn_read_res.3http.adoc +++ /dev/null @@ -1,75 +0,0 @@ -= nng_http_conn_read_res(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_conn_read_res - read HTTP response - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -void nng_http_conn_read_res(nng_http_conn *conn, nng_http_res *res, - nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_http_conn_read_res()` function starts an asynchronous read from the -HTTP connection _conn_, reading an HTTP response into the _res_, including all -of the related headers. - -NOTE: Any HTTP entity/body data associated with the response is *not* read -automatically. -The caller should use -xref:nng_http_conn_read_all.3http.adoc[`nng_http_conn_read_all`] to read the entity -data, based on the details of the response itself. - -This function returns immediately, with no return value. -Completion of -the operation is signaled via the _aio_, and the final result may be -obtained via xref:nng_aio_result.3.adoc[`nng_aio_result()`]. -That result will either be zero or an error code. - -NOTE: Consider using the -xref:nng_http_client_transact.3http.adoc[`nng_http_client_transact()`] or -xref:nng_http_conn_transact.3http.adoc[`nng_http_conn_transact()`] functions, -which provide a simpler interface for performing a complete HTTP client -transaction. - -== RETURN VALUES - -None. - -== ERRORS - -[horizontal] -`NNG_ECANCELED`:: The operation was canceled. -`NNG_ECLOSED`:: The connection was closed. -`NNG_ECONNRESET`:: The peer closed the connection. -`NNG_ENOMEM`:: Insufficient free memory to perform the operation. -`NNG_ENOTSUP`:: HTTP operations are not supported. -`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. - -== SEE ALSO - -[.text-left] -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_result.3.adoc[nng_aio_result(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_http_client_connect.3http.adoc[nng_http_client_connect(3http)], -xref:nng_http_client_transact.3http.adoc[nng_http_client_transact(3http)], -xref:nng_http_conn_transact.3http.adoc[nng_http_conn_transact(3http)], -xref:nng_http_conn_read_all.3http.adoc[nng_http_conn_read_all(3http)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_conn_transact.3http.adoc b/docs/man/nng_http_conn_transact.3http.adoc deleted file mode 100644 index 7239f628..00000000 --- a/docs/man/nng_http_conn_transact.3http.adoc +++ /dev/null @@ -1,93 +0,0 @@ -= nng_http_conn_transact(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_conn_transact - perform one HTTP transaction on connection - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -void nng_http_conn_transact(nng_http_conn *conn, nng_http_req *req, - nng_http_res *res, nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_http_conn_transact()` function is used to perform a complete -HTTP exchange over the connection _conn_, sending the request _req_ -(and attached body data) to the remote server, and reading the response -_res_. -The entire response is read, including any associated body, which can -subsequently be obtained using -xref:nng_http_res_get_data.3http.adoc[`nng_http_res_get_data()`]. - -This function is intended to make creation of client applications easier, -by performing multiple asynchronous operations required to complete an -entire HTTP transaction. - -If an error occurs, the caller should close _conn_ with -xref:nng_http_conn_close.3http.adoc[`nng_http_conn_close()`], as it may not -necessarily be usable with other transactions. - -A similar function, -xref:nng_http_client_transact.3http.adoc[`nng_http_client_transact()`], -exists. -That function behaves similarily, but creates a connection on demand -for the transaction, and disposes of it when finished. - -WARNING: If the remote server tries to send an extremely large buffer, -then a corresponding allocation will be made, which can lead to denial -of service attacks. -Client applications should take care to use this only with reasonably -trust-worthy servers. - -WARNING: A given connection _conn_ should be used with only one -operation or transaction at a time as HTTP/1.1 has no support for -request interleaving. - -This function returns immediately, with no return value. -Completion of the operation is signaled via the _aio_, and the final result -may be obtained via xref:nng_aio_result.3.adoc[`nng_aio_result()`]. -That result will either be zero or an error code. - -== RETURN VALUES - -None. - -== ERRORS - -[horizontal] -`NNG_ECANCELED`:: The operation was canceled. -`NNG_ECLOSED`:: The connection was closed. -`NNG_ECONNRESET`:: The peer closed the connection. -`NNG_ENOMEM`:: Insufficient free memory to perform the operation. -`NNG_ENOTSUP`:: HTTP operations are not supported. -`NNG_EPROTO`:: An HTTP protocol error occurred. -`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. - -== SEE ALSO - -[.text-left] -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_result.3.adoc[nng_aio_result(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_http_client_connect.3http.adoc[nng_http_client_connect(3http)], -xref:nng_http_client_transact.3http.adoc[nng_http_client_transact(3http)], -xref:nng_http_conn_read_res.3http.adoc[nng_http_conn_read_res(3http)], -xref:nng_http_conn_read_all.3http.adoc[nng_http_conn_read_all(3http)], -xref:nng_http_conn_write_req.3http.adoc[nng_http_conn_write_req(3http)], -xref:nng_http_res_get_data.3http.adoc[nng_http_res_get_data(3http)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_conn_write.3http.adoc b/docs/man/nng_http_conn_write.3http.adoc deleted file mode 100644 index d2e1ac31..00000000 --- a/docs/man/nng_http_conn_write.3http.adoc +++ /dev/null @@ -1,76 +0,0 @@ -= nng_http_conn_write(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_conn_write - write to HTTP connection - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -void nng_http_conn_write(nng_http_conn *conn, nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_http_conn_write()` function starts an asynchronous write to the -HTTP connection _conn_ from the scatter/gather vector located in the -asynchronous I/O structure _aio_. - -NOTE: The xref:nng_aio_set_iov.3.adoc[`nng_aio_set_iov()`] function must have been -called first, to set the scatter/gather vector for _aio_. - -This function returns immediately, with no return value. -Completion of the operation is signaled via the _aio_, and the final -result may be obtained via xref:nng_aio_result.3.adoc[`nng_aio_result()`]. -That result will either be zero or an error code. - -The I/O operation completes as soon as at least one byte has been -written, or an error has occurred. -Therefore, the number of bytes written may be less than requested. -The actual number of bytes written can be determined with -xref:nng_aio_count.3.adoc[`nng_aio_count()`]. - -TIP: This function is intended to facilitate uses cases that involve changing -the protocol from HTTP, such as WebSocket. -Most applications will never need to use this function. - -== RETURN VALUES - -None. - -== ERRORS - -[horizontal] -`NNG_ECANCELED`:: The operation was canceled. -`NNG_ECLOSED`:: The connection was closed. -`NNG_ECONNRESET`:: The peer closed the connection. -`NNG_EINVAL`:: The _aio_ does not contain a valid scatter/gather vector. -`NNG_ENOMEM`:: Insufficient free memory to perform the operation. -`NNG_ENOTSUP`:: HTTP operations are not supported. -`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. - -== SEE ALSO - -[.text-left] -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_count.3.adoc[nng_aio_count(3)], -xref:nng_aio_result.3.adoc[nng_aio_result(3)], -xref:nng_aio_set_iov.3.adoc[nng_aio_set_iov(3)], -xref:nng_http_client_connect.3http.adoc[nng_http_client_connect(3http)], -xref:nng_http_conn_write_all.3http.adoc[nng_http_conn_write_all(3http)], -xref:nng_http_handler_alloc.3http.adoc[nng_http_handler_alloc(3http)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_conn_write_all.3http.adoc b/docs/man/nng_http_conn_write_all.3http.adoc deleted file mode 100644 index 329a8302..00000000 --- a/docs/man/nng_http_conn_write_all.3http.adoc +++ /dev/null @@ -1,96 +0,0 @@ -= nng_http_conn_write_all(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_conn_write_all - write all to HTTP connection - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -void nng_http_conn_write_all(nng_http_conn *conn, nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_http_conn_write_all()` function starts an asynchronous write to the -HTTP connection _conn_, into the scatter/gather vector located in the -asynchronous I/O structure _aio_. - -NOTE: The xref:nng_aio_set_iov.3.adoc[`nng_aio_set_iov()`] function must have been -called first, to set the scatter/gather vector for _aio_. - -This function returns immediately, with no return value. -Completion of the operation is signaled via the _aio_, and the -final result may be obtained via xref:nng_aio_result.3.adoc[`nng_aio_result()`]. -That result will either be zero or an error code. - -The I/O operation completes only when the entire amount of data -requested has been written, or an error has occurred. -If the operation completes successfully, then the entire requested data has -been written. - -It is still possible for a partial write to complete in the event of an error. -The actual number of bytes written can be determined with -xref:nng_aio_count.3.adoc[`nng_aio_count()`]. - -TIP: The main purpose for this function is to facilitate writing HTTP -body content. - -TIP: Usually an HTTP request or response will have been written immediately -prior to this with xref:nng_http_conn_write_req.3http.adoc[`http_conn_write_req()`] or -xref:nng_http_conn_write_res.3http.adoc[`http_conn_write_res()`]. -In that case the request or response should have also contained -an `Content-Length` header, and possibly a `Content-Type` header. - -TIP: An easier solution to sending HTTP content data, is to include the -content with the request or reply using a function like -xref:nng_http_req_copy_data.3http.adoc[`nng_http_req_copy_data()`]. -In that case, the body data will be written automatically by the -xref:nng_http_conn_write_req.3http.adoc[`http_conn_write_req()`] or -xref:nng_http_conn_write_req.3http.adoc[`http_conn_write_res()`] function. - -== RETURN VALUES - -None. - -== ERRORS - -[horizontal] -`NNG_ECANCELED`:: The operation was canceled. -`NNG_ECLOSED`:: The connection was closed. -`NNG_ECONNRESET`:: The peer closed the connection. -`NNG_EINVAL`:: The _aio_ does not contain a valid scatter/gather vector. -`NNG_ENOMEM`:: Insufficient free memory to perform the operation. -`NNG_ENOTSUP`:: HTTP operations are not supported. -`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. - -== SEE ALSO - -[.text-left] -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_count.3.adoc[nng_aio_count(3)], -xref:nng_aio_result.3.adoc[nng_aio_result(3)], -xref:nng_aio_set_iov.3.adoc[nng_aio_set_iov(3)], -xref:nng_http_client_connect.3http.adoc[nng_http_client_connect(3http)], -xref:nng_http_conn_write.3http.adoc[nng_http_conn_write(3http)], -xref:nng_http_conn_write_req.3http.adoc[http_conn_write_req(3http)], -xref:nng_http_conn_write_res.3http.adoc[http_conn_write_res(3http)], -xref:nng_http_req_copy_data.3http.adoc[nng_http_req_copy_data(3http)], -xref:nng_http_req_set_data.3http.adoc[nng_http_req_set_data(3http)], -xref:nng_http_res_copy_data.3http.adoc[nng_http_res_copy_data(3http)], -xref:nng_http_res_set_data.3http.adoc[nng_http_res_set_data(3http)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_conn_write_req.3http.adoc b/docs/man/nng_http_conn_write_req.3http.adoc deleted file mode 100644 index faed7604..00000000 --- a/docs/man/nng_http_conn_write_req.3http.adoc +++ /dev/null @@ -1,72 +0,0 @@ -= nng_http_conn_write_req(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_conn_write_req - write HTTP request - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -void nng_http_conn_write_req(nng_http_conn *conn, nng_http_req *req, - nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_http_conn_write_req()` function starts an asynchronous write of -the HTTP request _req_ to the connection _conn_. -The entire request is sent, -including headers, and if present, the request body data. -(The request body can be set with -xref:nng_http_req_set_data.3http.adoc[`nng_http_req_set_data()`] or -xref:nng_http_req_copy_data.3http.adoc[`nng_http_req_copy_data()`].) - -This function returns immediately, with no return value. -Completion of the operation is signaled via the _aio_, and the final result -may be obtained via xref:nng_aio_result.3.adoc[`nng_aio_result()`]. -That result will either be zero or an error code. - -NOTE: Consider using the -xref:nng_http_client_transact.3http.adoc[`nng_http_client_transact()`] or -xref:nng_http_conn_transact.3http.adoc[`nng_http_conn_transact()`] functions, -which provide a simpler interface for performing a complete HTTP client -transaction. - -== RETURN VALUES - -None. - -== ERRORS - -[horizontal] -`NNG_ECANCELED`:: The operation was canceled. -`NNG_ECLOSED`:: The connection was closed. -`NNG_ECONNRESET`:: The peer closed the connection. -`NNG_ENOMEM`:: Insufficient free memory to perform the operation. -`NNG_ENOTSUP`:: HTTP operations are not supported. -`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. - -== SEE ALSO - -[.text-left] -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_result.3.adoc[nng_aio_result(3)], -xref:nng_http_client_connect.3http.adoc[nng_http_client_connect(3http)], -xref:nng_http_client_transact.3http.adoc[nng_http_client_transact(3http)], -xref:nng_http_conn_read_all.3http.adoc[nng_http_conn_read_all(3http)], -xref:nng_http_conn_transact.3http.adoc[nng_http_conn_transact(3http)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_conn_write_res.3http.adoc b/docs/man/nng_http_conn_write_res.3http.adoc deleted file mode 100644 index e88ad164..00000000 --- a/docs/man/nng_http_conn_write_res.3http.adoc +++ /dev/null @@ -1,80 +0,0 @@ -= nng_http_conn_write_res(3http) -// -// Copyright 2025 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_conn_write_res - write HTTP response - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -void nng_http_conn_write_res(nng_http_conn *conn, nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_http_conn_write_res()` function starts an asynchronous write of -the HTTP response associated with the connection _conn_. -The entire response is sent, -including headers, and if present, the response body data. -(The response body can be set with -xref:nng_http_res_set_data.3http.adoc[`nng_http_res_set_data()`] or -xref:nng_http_res_copy_data.3http.adoc[`nng_http_res_copy_data()`].) - -This function returns immediately, with no return value. -Completion of the operation is signaled via the _aio_, and the final result -may be obtained via xref:nng_aio_result.3.adoc[`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. - -NOTE: Consider using the -xref:nng_http_client_transact.3http.adoc[`nng_http_client_transact()`] or -xref:nng_http_conn_transact.3http.adoc[`nng_http_conn_transact()`] functions, -which provide a simpler interface for performing a complete HTTP client -transaction. - -== RETURN VALUES - -None. - -== ERRORS - -[horizontal] -`NNG_ECANCELED`:: The operation was canceled. -`NNG_ECLOSED`:: The connection was closed. -`NNG_ECONNRESET`:: The peer closed the connection. -`NNG_ENOMEM`:: Insufficient free memory to perform the operation. -`NNG_ENOTSUP`:: HTTP operations are not supported. -`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. - -== SEE ALSO - -[.text-left] -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_result.3.adoc[nng_aio_result(3)], -xref:nng_http_client_connect.3http.adoc[nng_http_client_connect(3http)], -xref:nng_http_client_transact.3http.adoc[nng_http_client_transact(3http)], -xref:nng_http_conn_read_all.3http.adoc[nng_http_conn_read_all(3http)], -xref:nng_http_conn_transact.3http.adoc[nng_http_conn_transact(3http)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_handler_alloc.3http.adoc b/docs/man/nng_http_handler_alloc.3http.adoc index 23171450..8d55c752 100644 --- a/docs/man/nng_http_handler_alloc.3http.adoc +++ b/docs/man/nng_http_handler_alloc.3http.adoc @@ -19,7 +19,7 @@ nng_http_handler_alloc - allocate HTTP server handler [source, c] ---- #include <nng/nng.h> -#include <nng/supplemental/http/http.h> +#include <nng/http.h> typedef struct nng_http_handler nng_http_handler; @@ -184,8 +184,6 @@ 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_res_alloc.3http.adoc[nng_http_res_alloc(3http)], -xref:nng_http_res_alloc_error.3http.adoc[nng_http_res_alloc_error(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)], diff --git a/docs/man/nng_http_handler_collect_body.3http.adoc b/docs/man/nng_http_handler_collect_body.3http.adoc index d02919cd..5012680d 100644 --- a/docs/man/nng_http_handler_collect_body.3http.adoc +++ b/docs/man/nng_http_handler_collect_body.3http.adoc @@ -18,7 +18,7 @@ nng_http_handler_collect_body - set HTTP handler to collect request body [source, c] ---- #include <nng/nng.h> -#include <nng/supplemental/http/http.h> +#include <nng/http.h> void nng_http_handler_collect_body(nng_http_handler *handler, bool want, size_t maxsz); ---- diff --git a/docs/man/nng_http_handler_free.3http.adoc b/docs/man/nng_http_handler_free.3http.adoc index c7b30e0e..0e1a5b1c 100644 --- a/docs/man/nng_http_handler_free.3http.adoc +++ b/docs/man/nng_http_handler_free.3http.adoc @@ -18,7 +18,7 @@ nng_http_handler_free - free HTTP server handler [source, c] ---- #include <nng/nng.h> -#include <nng/supplemental/http/http.h> +#include <nng/http.h> void nng_http_handler_free(nng_http_handler *h); ---- diff --git a/docs/man/nng_http_handler_get_data.3http.adoc b/docs/man/nng_http_handler_get_data.3http.adoc index 0467b2b6..0f2396f6 100644 --- a/docs/man/nng_http_handler_get_data.3http.adoc +++ b/docs/man/nng_http_handler_get_data.3http.adoc @@ -18,7 +18,7 @@ nng_http_handler_get_data - return extra data for HTTP handler [source, c] ---- #include <nng/nng.h> -#include <nng/supplemental/http/http.h> +#include <nng/http.h> void *nng_http_handler_get_data(nng_http_handler *handler); ---- diff --git a/docs/man/nng_http_handler_set_data.3http.adoc b/docs/man/nng_http_handler_set_data.3http.adoc index 94cb9b4c..e83ecb6b 100644 --- a/docs/man/nng_http_handler_set_data.3http.adoc +++ b/docs/man/nng_http_handler_set_data.3http.adoc @@ -18,7 +18,7 @@ nng_http_handler_set_data - set extra data for HTTP handler [source, c] ---- #include <nng/nng.h> -#include <nng/supplemental/http/http.h> +#include <nng/http.h> void nng_http_handler_set_data(nng_http_handler *handler, void *data, void (*dtor)(void *)); diff --git a/docs/man/nng_http_handler_set_host.3http.adoc b/docs/man/nng_http_handler_set_host.3http.adoc index 3f25172f..e3d5e80a 100644 --- a/docs/man/nng_http_handler_set_host.3http.adoc +++ b/docs/man/nng_http_handler_set_host.3http.adoc @@ -18,7 +18,7 @@ nng_http_handler_set_host - set host for HTTP handler [source, c] ---- #include <nng/nng.h> -#include <nng/supplemental/http/http.h> +#include <nng/http.h> void nng_http_handler_set_host(nng_http_handler *handler, const char *host); ---- diff --git a/docs/man/nng_http_handler_set_method.3http.adoc b/docs/man/nng_http_handler_set_method.3http.adoc index 17c4481d..e216ab54 100644 --- a/docs/man/nng_http_handler_set_method.3http.adoc +++ b/docs/man/nng_http_handler_set_method.3http.adoc @@ -18,7 +18,7 @@ nng_http_handler_set_method - set HTTP handler method [source, c] ---- #include <nng/nng.h> -#include <nng/supplemental/http/http.h> +#include <nng/http.h> void nng_http_handler_set_method(nng_http_handler *handler, const char *method); ---- diff --git a/docs/man/nng_http_handler_set_tree.3http.adoc b/docs/man/nng_http_handler_set_tree.3http.adoc index 3ee73de0..821a5f7b 100644 --- a/docs/man/nng_http_handler_set_tree.3http.adoc +++ b/docs/man/nng_http_handler_set_tree.3http.adoc @@ -18,7 +18,7 @@ nng_http_handler_set_tree - set HTTP handler to match trees [source,c] ---- #include <nng/nng.h> -#include <nng/supplemental/http/http.h> +#include <nng/http.h> void nng_http_handler_set_tree(nng_http_handler *handler); @@ -53,5 +53,5 @@ handling. [.text-left] xref:nng_http_handler_alloc.3http.adoc[nng_http_handler_alloc(3http)], xref:nng_http_server_add_handler.3http.adoc[nng_http_server_add_handler(3http)], -xref:nng_http_req_get_method.3http.adoc[nng_http_req_get_method(3http)], +xref:nng_http_get_method.3http.adoc[nng_http_get_method(3http)], xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_hijack.3http.adoc b/docs/man/nng_http_hijack.3http.adoc deleted file mode 100644 index 51231425..00000000 --- a/docs/man/nng_http_hijack.3http.adoc +++ /dev/null @@ -1,65 +0,0 @@ -= nng_http_hijack(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_hijack - hijack HTTP server connection - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -void nng_http_hijack(nng_http_conn *conn); ----- - -== DESCRIPTION -(((HTTP, hijack))) -The `nng_http_hijack()` function hijacks the connection _conn_, causing it -to be disassociated from the HTTP server where it was created. - -The purpose of this function is the creation of HTTP upgraders (such as -WebSocket), where the underlying HTTP connection will be taken over for -some other purpose, and should not be used any further by the server. - -This function is most useful when called from a handler function. -(See xref:nng_http_handler_alloc.3http.adoc[`nng_http_handler_alloc()`].) - -NOTE: It is the responsibility of the caller to dispose of the underlying -connection when it is no longer needed. -Furthermore, the HTTP server will no longer send any responses to the -hijacked connection, so the caller should do that as well if appropriate. -(See xref:nng_http_conn_write_res.3http.adoc[`nng_http_conn_write_res()`].) - -TIP: This function is intended to facilitate uses cases that involve changing -the protocol from HTTP, such as WebSocket. -Most applications will never need to use this function. - -== RETURN VALUES - -None. - -== ERRORS - -[horizontal] -`NNG_ECLOSED`:: The connection was closed. -`NNG_ENOMEM`:: Insufficient free memory exists. -`NNG_ENOTSUP`:: HTTP not supported. - -== SEE ALSO - -[.text-left] -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_http_conn_write_res.3http.adoc[nng_http_conn_write_res(3http)], -xref:nng_http_handler_alloc.3http.adoc[nng_http_handler_alloc(3http)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_req_add_header.3http.adoc b/docs/man/nng_http_req_add_header.3http.adoc deleted file mode 100644 index bf95254a..00000000 --- a/docs/man/nng_http_req_add_header.3http.adoc +++ /dev/null @@ -1,65 +0,0 @@ -= nng_http_req_add_header(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_req_add_header - add HTTP request header - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -int nng_http_req_add_header(nng_http_req *req, const char *key, - const char *val); ----- - -== DESCRIPTION - -The `nng_http_req_add_header()` adds an HTTP header for the request -_req_ and the _key_ to the _val_. The _key_ and _val_ are copied. - -If a header with the value of _key_ already exists, then a comma -and whitespace separate are appended to it, followed by _val_. - -If no such header already exists, then one is created with the value _val_. - -TIP: The HTTP specification requires that duplicate headers be treated -identically to a single header with multiple comma-delimited values. - -TIP: See xref:nng_http_req_set_header.3http.adoc[`nng_http_req_set_header()`] if -replacement of an existing header rather than appending to it is desired. - -The value of _key_ is case insensitive, and should not include the final -colon in an HTTP header. -For example, specifying `Host` or `hOSt` are -equivalent, whereas the value `Host:` is not a legal header key. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory to perform the operation. -`NNG_ENOTSUP`:: No support for HTTP in the library. - -== SEE ALSO - -[.text-left] -xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc(3http)], -xref:nng_http_req_del_header.3http.adoc[nng_http_req_del_header(3http)], -xref:nng_http_req_get_header.3http.adoc[nng_http_req_get_header(3http)], -xref:nng_http_req_set_header.3http.adoc[nng_http_req_set_header(3http)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_req_alloc.3http.adoc b/docs/man/nng_http_req_alloc.3http.adoc deleted file mode 100644 index 706ef9d9..00000000 --- a/docs/man/nng_http_req_alloc.3http.adoc +++ /dev/null @@ -1,68 +0,0 @@ -= nng_http_req_alloc(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_req_alloc - allocate HTTP request structure - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -int nng_http_req_alloc(nng_http_req **reqp, const nng_url *url); ----- - -== DESCRIPTION - -The `nng_http_req_alloc()` function allocates a new HTTP request structure -and stores a pointer to it in __reqp__. -The request will be initialized -to perform an HTTP/1.1 `GET` operation using the URL specified in __url__. - -TIP: It is possible to specify `NULL` for the URL. -In this case the URI for the request must be specified by a subsequent call -to xref:nng_http_req_set_uri.3http.adoc[`nng_http_req_set_uri()`]. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists to allocate a message. -`NNG_ENOTSUP`:: HTTP support not configured. - -== SEE ALSO - -[.text-left] -xref:nng_http_conn_read_req.3http.adoc[nng_http_conn_read_req(3http)], -xref:nng_http_conn_write_req.3http.adoc[nng_http_conn_write_req(3http)], -xref:nng_http_req_add_header.3http.adoc[nng_http_req_add_header(3http)], -xref:nng_http_req_copy_data.3http.adoc[nng_http_req_copy_data(3http)], -xref:nng_http_req_del_header.3http.adoc[nng_http_req_del_header(3http)], -xref:nng_http_req_free.3http.adoc[nng_http_req_free(3http)], -xref:nng_http_req_get_header.3http.adoc[nng_http_req_get_header(3http)], -xref:nng_http_req_get_method.3http.adoc[nng_http_req_get_method(3http)], -xref:nng_http_req_get_uri.3http.adoc[nng_http_req_get_uri(3http)], -xref:nng_http_req_get_version.3http.adoc[nng_http_req_get_version(3http)], -xref:nng_http_req_reset.3http.adoc[nng_http_req_reset(3http)], -xref:nng_http_req_set_data.3http.adoc[nng_http_req_set_data(3http)], -xref:nng_http_req_set_method.3http.adoc[nng_http_req_set_method(3http)], -xref:nng_http_req_set_uri.3http.adoc[nng_http_req_set_uri(3http)], -xref:nng_http_req_set_version.3http.adoc[nng_http_req_set_version(3http)], -xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc(3http)], -xref:nng_url_parse.3.adoc[nng_url_parse(3)] -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_req_copy_data.3http.adoc b/docs/man/nng_http_req_copy_data.3http.adoc deleted file mode 100644 index 7ab864fa..00000000 --- a/docs/man/nng_http_req_copy_data.3http.adoc +++ /dev/null @@ -1,62 +0,0 @@ -= nng_http_req_copy_data(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_req_copy_data - copy HTTP request body - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -int nng_http_req_copy_data(nng_http_req *req, const void *body, size_t size); ----- - -== DESCRIPTION - -The `nng_http_req_copy_data()` makes a copy of _body_ (of size __size__) -and sets the HTTP body for the request _req_ to it. -The copy will be deallocated automatically when _req_ is freed. - -The copied body data will be automatically sent with the request when it -is sent using xref:nng_http_conn_write_req.3http.adoc[`nng_http_conn_write_req()`]. - -This also updates the relevant `Content-Length` header of _req_. - -NOTE: The current framework does not support sending data via chunked -transfer-encoding. - -TIP: To avoid copying data, the -xref:nng_http_req_set_data.3http.adoc[`nng_http_req_set_data()`] may be used instead. - -TIP: It is a good idea to also set the `Content-Type` header. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory to perform the operation. -`NNG_ENOTSUP`:: No support for HTTP in the library. - -== SEE ALSO - -[.text-left] -xref:nng_http_conn_write_req.3http.adoc[nng_http_conn_write_req(3http)], -xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc(3http)], -xref:nng_http_req_set_data.3http.adoc[nng_http_req_set_data(3http)], -xref:nng_http_req_set_header.3http.adoc[nng_http_req_set_header(3http)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_req_del_header.3http.adoc b/docs/man/nng_http_req_del_header.3http.adoc deleted file mode 100644 index d54f65e7..00000000 --- a/docs/man/nng_http_req_del_header.3http.adoc +++ /dev/null @@ -1,53 +0,0 @@ -= nng_http_req_del_header(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_req_del_header - delete HTTP request header - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -int nng_http_req_del_header(nng_http_req *req, const char *key); ----- - -== DESCRIPTION - -The `nng_http_req_del_header()` removes all HTTP headers with the -associated _key_ from the request structure _req_. - -The value of _key_ is case insensitive, and should not include the final -colon in an HTTP header. -For example, specifying `Host` or `hOSt` are -equivalent, whereas the value `Host:` is not a legal header key. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOENT`:: No header with the key _key_ was present. -`NNG_ENOTSUP`:: No support for HTTP in the library. - -== SEE ALSO - -[.text-left] -xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc(3http)], -xref:nng_http_req_add_header.3http.adoc[nng_http_req_add_header(3http)], -xref:nng_http_req_del_header.3http.adoc[nng_http_req_del_header(3http)], -xref:nng_http_req_get_header.3http.adoc[nng_http_req_get_header(3http)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_req_free.3http.adoc b/docs/man/nng_http_req_free.3http.adoc deleted file mode 100644 index daa858b8..00000000 --- a/docs/man/nng_http_req_free.3http.adoc +++ /dev/null @@ -1,47 +0,0 @@ -= nng_http_req_free(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_req_free - free HTTP request structure - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -void nng_http_req_free(nng_http_req *req); ----- - -== DESCRIPTION - -The `nng_http_req_free()` function deallocates the HTTP request structure -_req_ entirely. - -TIP: Instead of freeing and reallocating request structures, it is possible -to reuse _req_ with xref:nng_http_req_reset.3http.adoc[`nng_http_req_reset()`]. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc(3http)], -xref:nng_http_req_reset.3http.adoc[nng_http_req_reset(3http)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_req_get_data.3http.adoc b/docs/man/nng_http_req_get_data.3http.adoc deleted file mode 100644 index e006bb1b..00000000 --- a/docs/man/nng_http_req_get_data.3http.adoc +++ /dev/null @@ -1,50 +0,0 @@ -= nng_http_req_get_data(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_req_get_data - get HTTP request body - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -void nng_http_req_get_data(nng_http_req *req, void **bodyp, size_t *sizep); ----- - -== DESCRIPTION - -The `nng_http_req_get_data()` gets the HTTP body associated with -the request _req_, storing a pointer to the buffer at the location referenced -by _bodyp_, and the length of the associated buffer at the location referenced -by _sizep_. - -NOTE: The buffer returned is owned by _req_, and will automatically freed -when the request is freed. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc(3http)], -xref:nng_http_req_set_data.3http.adoc[nng_http_req_copy_data(3http)], -xref:nng_http_req_copy_data.3http.adoc[nng_http_req_copy_data(3http)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_req_get_header.3http.adoc b/docs/man/nng_http_req_get_header.3http.adoc deleted file mode 100644 index cbc6ec49..00000000 --- a/docs/man/nng_http_req_get_header.3http.adoc +++ /dev/null @@ -1,52 +0,0 @@ -= nng_http_req_get_header(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_req_get_header - return HTTP request header - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -const char *nng_http_req_get_header(const nng_http_req *req, const char *key); ----- - -== DESCRIPTION - -The `nng_http_req_get_header()` looks for an HTTP header _key_ in -the request _req_, and returns the associated value if found, -or `NULL` if not found. - -The value of _key_ is case insensitive, and should not include the final -colon in an HTTP header. -For example, specifying `Host` or `hOSt` are -equivalent, whereas the value `Host:` will not find anything. - - -== RETURN VALUES - -HTTP header value for _key_, if it exists, or NULL otherwise. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc(3http)], -xref:nng_http_req_add_header.3http.adoc[nng_http_req_add_header(3http)], -xref:nng_http_req_set_header.3http.adoc[nng_http_req_set_header(3http)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_req_get_method.3http.adoc b/docs/man/nng_http_req_get_method.3http.adoc deleted file mode 100644 index 20f6010b..00000000 --- a/docs/man/nng_http_req_get_method.3http.adoc +++ /dev/null @@ -1,46 +0,0 @@ -= nng_http_req_get_method(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_req_get_method - return HTTP request method - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -const char *nng_http_req_get_method(const nng_http_req *req); ----- - -== DESCRIPTION - -The `nng_http_req_get_method()` returns the HTTP method associated with -the request _req_. -The value will be a string, such as "GET" or "POST". - - -== RETURN VALUES - -Request method as a string. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc(3http)], -xref:nng_http_req_set_method.3http.adoc[nng_http_req_set_method(3http)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_req_get_uri.3http.adoc b/docs/man/nng_http_req_get_uri.3http.adoc deleted file mode 100644 index 8e664a1f..00000000 --- a/docs/man/nng_http_req_get_uri.3http.adoc +++ /dev/null @@ -1,47 +0,0 @@ -= nng_http_req_get_uri(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_req_get_uri - return HTTP request URI - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -const char *nng_http_req_get_uri(const nng_http_req *req); ----- - -== DESCRIPTION - -The `nng_http_req_get_uri()` returns the URI (path) associated with the HTTP -request _req_. -The value returned includes the path, as well as any query information or -fragment. The value will look like a file system path -with those optional components appended, such as `/api/get_info.cgi?name=garrett`. - -== RETURN VALUES - -Request URI as a string. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc(3http)], -xref:nng_http_req_set_uri.3http.adoc[nng_http_req_set_uri(3http)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_req_get_version.3http.adoc b/docs/man/nng_http_req_get_version.3http.adoc deleted file mode 100644 index 537f6caf..00000000 --- a/docs/man/nng_http_req_get_version.3http.adoc +++ /dev/null @@ -1,45 +0,0 @@ -= nng_http_req_get_version(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_req_get_version - return HTTP request protocol version - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -const char *nng_http_req_get_version(const nng_http_req *req); ----- - -== DESCRIPTION - -The `nng_http_req_get_version()` returns a string representing the HTTP -protocol version associated with the request _req_, such as "HTTP/1.1". - - -== RETURN VALUES - -Request version as a string. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc(3http)], -xref:nng_http_req_set_version.3http.adoc[nng_http_req_set_version(3http)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_req_reset.3http.adoc b/docs/man/nng_http_req_reset.3http.adoc deleted file mode 100644 index 58dcc149..00000000 --- a/docs/man/nng_http_req_reset.3http.adoc +++ /dev/null @@ -1,48 +0,0 @@ -= nng_http_req_reset(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_req_reset - reset HTTP request structure - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -void nng_http_req_reset(nng_http_req *req); ----- - -== DESCRIPTION - -The `nng_http_req_reset()` function resets the request __req__ so that it -is just as if it had been freshly allocated with -xref:nng_http_req_alloc.3http.adoc[`nng_http_req_alloc()`] with a `NULL` URL. - -NOTE: Before using this with an HTTP operation, the URI must be set using -xref:nng_http_req_set_uri.3http.adoc[`nng_http_req_set_uri()`]. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc(3http)], -xref:nng_http_req_set_uri.3http.adoc[nng_http_req_set_uri(3http)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_req_set_data.3http.adoc b/docs/man/nng_http_req_set_data.3http.adoc deleted file mode 100644 index 583d7a58..00000000 --- a/docs/man/nng_http_req_set_data.3http.adoc +++ /dev/null @@ -1,64 +0,0 @@ -= nng_http_req_set_data(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_req_set_data - set HTTP request body - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -int nng_http_req_set_data(nng_http_req *req, const void *body, size_t size); ----- - -== DESCRIPTION - -The `nng_http_req_set_data()` sets the HTTP body associated with -the request _req_ to _body_, and the size of the body to _size_. -This body data will be automatically sent with the request when it -is sent using xref:nng_http_conn_write_req.3http.adoc[`nng_http_conn_write_req()`]. - -This also updates the relevant `Content-Length` header of _req_. - -NOTE: The current framework does not support sending data via chunked -transfer-encoding. - -The _body_ is *not* copied, and the caller must ensure that it is available -until the _req_ is deallocated. - -TIP: To have a local copy allocated with _req_ that will be automatically -deallocated when _req_ is freed, -see xref:nng_http_req_copy_data.3http.adoc[`nng_http_req_copy_data()`]. - -TIP: It is a good idea to also set the `Content-Type` header. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory to perform the operation. -`NNG_ENOTSUP`:: No support for HTTP in the library. - -== SEE ALSO - -[.text-left] -xref:nng_http_conn_write_req.3http.adoc[nng_http_conn_write_req(3http)], -xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc(3http)], -xref:nng_http_req_copy_data.3http.adoc[nng_http_req_copy_data(3http)], -xref:nng_http_req_set_header.3http.adoc[nng_http_req_set_header(3http)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_req_set_header.3http.adoc b/docs/man/nng_http_req_set_header.3http.adoc deleted file mode 100644 index e38b5664..00000000 --- a/docs/man/nng_http_req_set_header.3http.adoc +++ /dev/null @@ -1,59 +0,0 @@ -= nng_http_req_set_header(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_req_set_header - set HTTP request header - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -int nng_http_req_set_header(nng_http_req *req, const char *key, - const char *val); ----- - -== DESCRIPTION - -The `nng_http_req_set_header()` sets the HTTP header for the request -_req_ and the _key_ to the _val_. -The _key_ and _val_ are copied. -Any previous header with the same _key_ is replaced. - -TIP: See xref:nng_http_req_add_header.3http.adoc[`nng_http_req_add_header()`] to -add additional headers with the same _key_ without replacing them. - -The value of _key_ is case insensitive, and should not include the final -colon in an HTTP header. -For example, specifying `Host` or `hOSt` are -equivalent, whereas the value `Host:` is not a legal header key. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory to perform the operation. -`NNG_ENOTSUP`:: No support for HTTP in the library. - -== SEE ALSO - -[.text-left] -xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc(3http)], -xref:nng_http_req_add_header.3http.adoc[nng_http_req_add_header(3http)], -xref:nng_http_req_del_header.3http.adoc[nng_http_req_del_header(3http)], -xref:nng_http_req_get_header.3http.adoc[nng_http_req_get_header(3http)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_req_set_uri.3http.adoc b/docs/man/nng_http_req_set_uri.3http.adoc deleted file mode 100644 index fd6961d6..00000000 --- a/docs/man/nng_http_req_set_uri.3http.adoc +++ /dev/null @@ -1,59 +0,0 @@ -= nng_http_req_set_uri(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_req_set_uri - set HTTP request URI - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -int nng_http_req_set_uri(nng_http_req *req, const char *uri); ----- - -== DESCRIPTION - -The `nng_http_req_set_uri()` sets the Request-URI associated with -the request _req_ to _uri_. -The _uri_ should contain precisely the -string that will be sent to the HTTP server in the request, including -any query information or fragment. - -A local copy of the _uri_ is made in the request _req_. - -NOTE: No validation or canonicalization of the _uri_ is performed. - -TIP: The xref:nng_url_parse.3.adoc[`nng_url_parse()`] function can be used to -perform validation and canonicalization. -The `u_requri` member will -contain a suitable value that can be used with this function. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory to perform the operation. -`NNG_ENOTSUP`:: No support for HTTP in the library. - -== SEE ALSO - -[.text-left] -xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc(3http)], -xref:nng_http_req_get_uri.3http.adoc[nng_http_req_get_uri(3http)], -xref:nng_url_parse.3.adoc[nng_url_parse(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_req_set_version.3http.adoc b/docs/man/nng_http_req_set_version.3http.adoc deleted file mode 100644 index ca41f0ef..00000000 --- a/docs/man/nng_http_req_set_version.3http.adoc +++ /dev/null @@ -1,57 +0,0 @@ -= nng_http_req_set_version(3http) -// -// Copyright 2024 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_req_set_version - set HTTP request protocol version - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -#define NNG_HTTP_VERSION_1_1 "HTTP/1.0" -#define NNG_HTTP_VERSION_1_1 "HTTP/1.1" - -int nng_http_req_set_version(nng_http_req *req, const char *version); ----- - -== DESCRIPTION - -The `nng_http_req_set_version()` sets the HTTP protocol version associated with -the request _req_ to _version_. -The _version_ must be a string containing -a valid HTTP protocol version, such as "HTTP/1.0". -The default value is "HTTP/1.1". - -A local copy of the _version_ is made in the request _req_. - -NOTE: The library does not contain support for versions of HTTP other than -"HTTP/1.0" and "HTTP/1.1". - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory to perform the operation. -`NNG_ENOTSUP`:: No support for HTTP in the library, or no support for the version specified. - -== SEE ALSO - -[.text-left] -xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc(3http)], -xref:nng_http_req_get_version.3http.adoc[nng_http_req_get_version(3http)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_res_add_header.3http.adoc b/docs/man/nng_http_res_add_header.3http.adoc deleted file mode 100644 index eb2a79c1..00000000 --- a/docs/man/nng_http_res_add_header.3http.adoc +++ /dev/null @@ -1,65 +0,0 @@ -= nng_http_res_add_header(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_res_add_header - add HTTP response header - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -int nng_http_res_add_header(nng_http_res *res, const char *key, - const char *val); ----- - -== DESCRIPTION - -The `nng_http_res_add_header()` adds an HTTP header for the response -_res_ and the _key_ to the _val_. -The _key_ and _val_ are copied. - -If a header with the value of _key_ already exists, then a comma -and whitespace separate are appended to it, followed by _val_. - -If no such header already exists, then one is created with the value _val_. - -TIP: The HTTP specification requires that duplicate headers be treated -identically to a single header with multiple comma-delimited values. - -TIP: See xref:nng_http_res_set_header.3http.adoc[`nng_http_res_set_header()`] if -replacement of an existing header rather than appending to it is desired. - -The value of _key_ is case insensitive, and should not include the final -colon in an HTTP header. For example, specifying `Host` or `hOSt` are -equivalent, whereas the value `Host:` is not a legal header key. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory to perform the operation. -`NNG_ENOTSUP`:: No support for HTTP in the library. - -== SEE ALSO - -[.text-left] -xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc(3http)], -xref:nng_http_res_del_header.3http.adoc[nng_http_res_del_header(3http)], -xref:nng_http_res_get_header.3http.adoc[nng_http_res_get_header(3http)], -xref:nng_http_res_set_header.3http.adoc[nng_http_res_set_header(3http)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_res_alloc.3http.adoc b/docs/man/nng_http_res_alloc.3http.adoc deleted file mode 100644 index f546d151..00000000 --- a/docs/man/nng_http_res_alloc.3http.adoc +++ /dev/null @@ -1,68 +0,0 @@ -= nng_http_res_alloc(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_res_alloc - allocate HTTP response structure - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -int nng_http_res_alloc(nng_http_res **resp); ----- - -== DESCRIPTION - -The `nng_http_res_alloc()` function allocates a new HTTP response structure -and stores a pointer to it in __resp__. -The response will be initialized -with status code 200 (`NNG_HTTP_STATUS_OK`), and a reason phrase of `OK`, -and HTTP protocol version `HTTP/1.1`. - -TIP: When an error response is needed, consider using -xref:nng_http_res_alloc_error.3http.adoc[`nng_http_res_alloc_error()`] instead. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists to allocate a message. -`NNG_ENOTSUP`:: HTTP support not configured. - -== SEE ALSO - -[.text-left] -xref:nng_http_conn_read_res.3http.adoc[nng_http_conn_read_res(3http)], -xref:nng_http_conn_write_res.3http.adoc[nng_http_conn_write_res(3http)], -xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc(3http)], -xref:nng_http_res_alloc_error.3http.adoc[nng_http_res_alloc_error(3http)], -xref:nng_http_res_add_header.3http.adoc[nng_http_res_add_header(3http)], -xref:nng_http_res_copy_data.3http.adoc[nng_http_res_copy_data(3http)], -xref:nng_http_res_del_header.3http.adoc[nng_http_res_del_header(3http)], -xref:nng_http_res_free.3http.adoc[nng_http_res_free(3http)], -xref:nng_http_res_get_header.3http.adoc[nng_http_res_get_header(3http)], -xref:nng_http_res_get_reason.3http.adoc[nng_http_res_get_reason(3http)], -xref:nng_http_res_get_status.3http.adoc[nng_http_res_get_status(3http)], -xref:nng_http_res_get_version.3http.adoc[nng_http_res_get_version(3http)], -xref:nng_http_res_reset.3http.adoc[nng_http_res_reset(3http)], -xref:nng_http_res_set_data.3http.adoc[nng_http_res_set_data(3http)], -xref:nng_http_res_set_reason.3http.adoc[nng_http_res_set_reason(3http)], -xref:nng_http_res_set_status.3http.adoc[nng_http_res_set_status(3http)], -xref:nng_http_res_set_version.3http.adoc[nng_http_res_set_version(3http)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_res_alloc_error.3http.adoc b/docs/man/nng_http_res_alloc_error.3http.adoc deleted file mode 100644 index 2c8d729f..00000000 --- a/docs/man/nng_http_res_alloc_error.3http.adoc +++ /dev/null @@ -1,58 +0,0 @@ -= nng_http_res_alloc_error(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_res_alloc_error - allocate HTTP error response - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -int nng_http_res_alloc_error(nng_http_res **resp, uint16_t status); ----- - -== DESCRIPTION - -The `nng_http_res_alloc_error()` function allocates a new HTTP response structure -and stores a pointer to it in __resp__. -The response will be initialized -with the status code _status_, a corresponding reason phrase, and -a simple HTML page containing the same information will be generated and -attached to the response. -(Relevant HTTP headers will be set as well, such as `Content-Type` -and `Content-Length`.) -The HTTP protocol version is also set to "HTTP/1.1". - -TIP: This is the simplest way to generate an error response. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists to allocate a message. -`NNG_ENOTSUP`:: HTTP support not configured. - -== SEE ALSO - -[.text-left] -xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc(3http)], -xref:nng_http_res_free.3http.adoc[nng_http_res_free(3http)], -xref:nng_http_res_set_reason.3http.adoc[nng_http_res_set_reason(3http)], -xref:nng_http_res_set_status.3http.adoc[nng_http_res_set_status(3http)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_res_copy_data.3http.adoc b/docs/man/nng_http_res_copy_data.3http.adoc deleted file mode 100644 index b2cea28a..00000000 --- a/docs/man/nng_http_res_copy_data.3http.adoc +++ /dev/null @@ -1,62 +0,0 @@ -= nng_http_res_copy_data(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_res_copy_data - copy HTTP response body - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -int nng_http_res_copy_data(nng_http_res *res, const void *body, size_t size); ----- - -== DESCRIPTION - -The `nng_http_res_copy_data()` makes a copy of _body_ (of size __size__) -and sets the HTTP body for the response _res_ to it. -The copy will be deallocated automatically when _res_ is freed. - -The copied body data will be automatically sent with the response when it -is sent using xref:nng_http_conn_write_res.3http.adoc[`nng_http_conn_write_res()`]. - -This also updates the relevant `Content-Length` header of _res_. - -NOTE: The current framework does not support sending data via chunked -transfer-encoding. - -TIP: To avoid copying data, the -xref:nng_http_res_set_data.3http.adoc[`nng_http_res_set_data()`] may be used instead. - -TIP: It is a good idea to also set the `Content-Type` header. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory to perform the operation. -`NNG_ENOTSUP`:: No support for HTTP in the library. - -== SEE ALSO - -[.text-left] -xref:nng_http_conn_write_res.3http.adoc[nng_http_conn_write_res(3http)], -xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc(3http)], -xref:nng_http_res_set_data.3http.adoc[nng_http_res_set_data(3http)], -xref:nng_http_res_set_header.3http.adoc[nng_http_res_set_header(3http)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_res_del_header.3http.adoc b/docs/man/nng_http_res_del_header.3http.adoc deleted file mode 100644 index 2a8500ee..00000000 --- a/docs/man/nng_http_res_del_header.3http.adoc +++ /dev/null @@ -1,52 +0,0 @@ -= nng_http_res_del_header(3http) -// -// Copyright 2020 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_res_del_header - delete HTTP response header - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -int nng_http_res_del_header(nng_http_res *res, const char *key); ----- - -== DESCRIPTION - -The `nng_http_res_del_header()` removes all HTTP headers with the -associated _key_ from the response structure _res_. - -The value of _key_ is case insensitive, and should not include the final -colon in an HTTP header. For example, specifying `Host` or `hOSt` are -equivalent, whereas the value `Host:` is not a legal header key. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOENT`:: No header with the key _key_ was present. -`NNG_ENOTSUP`:: No support for HTTP in the library. - -== SEE ALSO - -[.text-left] -xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc(3http)], -xref:nng_http_res_add_header.3http.adoc[nng_http_res_add_header(3http)], -xref:nng_http_res_del_header.3http.adoc[nng_http_res_del_header(3http)], -xref:nng_http_res_get_header.3http.adoc[nng_http_res_get_header(3http)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_res_free.3http.adoc b/docs/man/nng_http_res_free.3http.adoc deleted file mode 100644 index c278648c..00000000 --- a/docs/man/nng_http_res_free.3http.adoc +++ /dev/null @@ -1,47 +0,0 @@ -= nng_http_res_free(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_res_free - free HTTP response structure - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -void nng_http_res_free(nng_http_res *req); ----- - -== DESCRIPTION - -The `nng_http_res_free()` function deallocates the HTTP response structure -_res_ entirely. - -TIP: Instead of freeing and reallocating response structures, it is possible -to reuse _res_ with xref:nng_http_res_reset.3http.adoc[`nng_http_res_reset()`]. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc(3http)], -xref:nng_http_res_reset.3http.adoc[nng_http_res_reset(3http)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_res_get_data.3http.adoc b/docs/man/nng_http_res_get_data.3http.adoc deleted file mode 100644 index 374bce70..00000000 --- a/docs/man/nng_http_res_get_data.3http.adoc +++ /dev/null @@ -1,50 +0,0 @@ -= nng_http_res_get_data(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_res_get_data - get HTTP response body - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -void nng_http_res_get_data(nng_http_res *res, void **bodyp, size_t *sizep); ----- - -== DESCRIPTION - -The `nng_http_res_get_data()` gets the HTTP body associated with -the request _res_, storing a pointer to the buffer at the location referenced -by _bodyp_, and the length of the associated buffer at the location referenced -by _sizep_. - -NOTE: The buffer returned is owned by _res_, and will automatically freed -when the request is freed. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_http_res_alloc.3http.adoc[nng_http_req_alloc(3http)], -xref:nng_http_res_set_data.3http.adoc[nng_http_req_copy_data(3http)], -xref:nng_http_res_copy_data.3http.adoc[nng_http_req_copy_data(3http)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_res_get_header.3http.adoc b/docs/man/nng_http_res_get_header.3http.adoc deleted file mode 100644 index 51d37aba..00000000 --- a/docs/man/nng_http_res_get_header.3http.adoc +++ /dev/null @@ -1,52 +0,0 @@ -= nng_http_res_get_header(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_res_get_header - return HTTP response header - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -const char *nng_http_res_get_header(const nng_http_res *res, const char *key); ----- - -== DESCRIPTION - -The `nng_http_res_get_header()` looks for an HTTP header _key_ in -the response _res_, and returns the associated value if found, -or `NULL` if not found. - -The value of _key_ is case insensitive, and should not include the final -colon in an HTTP header. -For example, specifying `Host` or `hOSt` are -equivalent, whereas the value `Host:` will not find anything. - - -== RETURN VALUES - -HTTP header value for _key_, if it exists, or NULL otherwise. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc(3http)], -xref:nng_http_res_add_header.3http.adoc[nng_http_res_add_header(3http)], -xref:nng_http_res_set_header.3http.adoc[nng_http_res_set_header(3http)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_res_get_reason.3http.adoc b/docs/man/nng_http_res_get_reason.3http.adoc deleted file mode 100644 index 3b9fdd58..00000000 --- a/docs/man/nng_http_res_get_reason.3http.adoc +++ /dev/null @@ -1,48 +0,0 @@ -= nng_http_res_get_reason(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_res_get_reason - return HTTP response reason - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -const char *nng_http_res_get_reason(const nng_http_res *res); ----- - -== DESCRIPTION - -The `nng_http_res_get_reason()` returns a string representing the -reason associated with the response _res_. -This is a human-readable explanation of the status code that -would be obtained from -xref:nng_http_res_get_status.3http.adoc[`nng_http_res_get_status()`]. - -== RETURN VALUES - -Reason as a string. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc(3http)], -xref:nng_http_res_get_status.3http.adoc[nng_http_res_get_status(3http)], -xref:nng_http_res_set_reason.3http.adoc[nng_http_res_set_reason(3http)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_res_get_status.3http.adoc b/docs/man/nng_http_res_get_status.3http.adoc deleted file mode 100644 index 827cfbf6..00000000 --- a/docs/man/nng_http_res_get_status.3http.adoc +++ /dev/null @@ -1,117 +0,0 @@ -= nng_http_res_get_status(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_res_get_status - return HTTP status code - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -uint16_t nng_http_res_get_status(const nng_http_res *res); ----- - -== DESCRIPTION - -The `nng_http_res_get_status()` returns a numeric code corresponding to -the HTTP status of the response _res_. - -For convenience, a number of predefined symbols corresponding to well-known -HTTP status codes are available. - -[source, c] ----- -enum { - NNG_HTTP_STATUS_CONTINUE = 100, - NNG_HTTP_STATUS_SWITCHING = 101, - NNG_HTTP_STATUS_PROCESSING = 102, - NNG_HTTP_STATUS_OK = 200, - NNG_HTTP_STATUS_CREATED = 201, - NNG_HTTP_STATUS_ACCEPTED = 202, - NNG_HTTP_STATUS_NOT_AUTHORITATIVE = 203, - NNG_HTTP_STATUS_NO_CONTENT = 204, - NNG_HTTP_STATUS_RESET_CONTENT = 205, - NNG_HTTP_STATUS_PARTIAL_CONTENT = 206, - NNG_HTTP_STATUS_MULTI_STATUS = 207, - NNG_HTTP_STATUS_ALREADY_REPORTED = 208, - NNG_HTTP_STATUS_IM_USED = 226, - NNG_HTTP_STATUS_MULTIPLE_CHOICES = 300, - NNG_HTTP_STATUS_STATUS_MOVED_PERMANENTLY = 301, - NNG_HTTP_STATUS_FOUND = 302, - NNG_HTTP_STATUS_SEE_OTHER = 303, - NNG_HTTP_STATUS_NOT_MODIFIED = 304, - NNG_HTTP_STATUS_USE_PROXY = 305, - NNG_HTTP_STATUS_TEMPORARY_REDIRECT = 307, - NNG_HTTP_STATUS_PERMANENT_REDIRECT = 308, - NNG_HTTP_STATUS_BAD_REQUEST = 400, - NNG_HTTP_STATUS_UNAUTHORIZED = 401, - NNG_HTTP_STATUS_PAYMENT_REQUIRED = 402, - NNG_HTTP_STATUS_FORBIDDEN = 403, - NNG_HTTP_STATUS_NOT_FOUND = 404, - NNG_HTTP_STATUS_METHOD_NOT_ALLOWED = 405, - NNG_HTTP_STATUS_NOT_ACCEPTABLE = 406, - NNG_HTTP_STATUS_PROXY_AUTH_REQUIRED = 407, - NNG_HTTP_STATUS_REQUEST_TIMEOUT = 408, - NNG_HTTP_STATUS_CONFLICT = 409, - NNG_HTTP_STATUS_GONE = 410, - NNG_HTTP_STATUS_LENGTH_REQUIRED = 411, - NNG_HTTP_STATUS_PRECONDITION_FAILED = 412, - NNG_HTTP_STATUS_PAYLOAD_TOO_LARGE = 413, - NNG_HTTP_STATUS_ENTITY_TOO_LONG = 414, - NNG_HTTP_STATUS_UNSUPPORTED_MEDIA_TYPE = 415, - NNG_HTTP_STATUS_RANGE_NOT_SATISFIABLE = 416, - NNG_HTTP_STATUS_EXPECTATION_FAILED = 417, - NNG_HTTP_STATUS_TEAPOT = 418, - NNG_HTTP_STATUS_UNPROCESSABLE_ENTITY = 422, - NNG_HTTP_STATUS_LOCKED = 423, - NNG_HTTP_STATUS_FAILED_DEPENDENCY = 424, - NNG_HTTP_STATUS_UPGRADE_REQUIRED = 426, - NNG_HTTP_STATUS_PRECONDITION_REQUIRED = 428, - NNG_HTTP_STATUS_TOO_MANY_REQUESTS = 429, - NNG_HTTP_STATUS_HEADERS_TOO_LARGE = 431, - NNG_HTTP_STATUS_UNAVAIL_LEGAL_REASONS = 451, - NNG_HTTP_STATUS_INTERNAL_SERVER_ERROR = 500, - NNG_HTTP_STATUS_NOT_IMPLEMENTED = 501, - NNG_HTTP_STATUS_BAD_GATEWAY = 502, - NNG_HTTP_STATUS_SERVICE_UNAVAILABLE = 503, - NNG_HTTP_STATUS_GATEWAY_TIMEOUT = 504, - NNG_HTTP_STATUS_HTTP_VERSION_NOT_SUPP = 505, - NNG_HTTP_STATUS_VARIANT_ALSO_NEGOTIATES = 506, - NNG_HTTP_STATUS_INSUFFICIENT_STORAGE = 507, - NNG_HTTP_STATUS_LOOP_DETECTED = 508, - NNG_HTTP_STATUS_NOT_EXTENDED = 510, - NNG_HTTP_STATUS_NETWORK_AUTH_REQUIRED = 511, -} ----- - -TIP: When displaying status information to users (or logging such information), -consider also including the reason obtained with -xref:nng_http_res_get_reason.3http.adoc[`nng_http_res_get_reason()`]. - -== RETURN VALUES - -HTTP status code. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc(3http)], -xref:nng_http_res_get_reason.3http.adoc[nng_http_res_get_reason(3http)], -xref:nng_http_res_set_status.3http.adoc[nng_http_res_set_status(3http)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_res_get_version.3http.adoc b/docs/man/nng_http_res_get_version.3http.adoc deleted file mode 100644 index d69e387c..00000000 --- a/docs/man/nng_http_res_get_version.3http.adoc +++ /dev/null @@ -1,45 +0,0 @@ -= nng_http_res_get_version(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_res_get_version - return HTTP response protocol version - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -const char *nng_http_res_get_version(nng_http_res *res); ----- - -== DESCRIPTION - -The `nng_http_res_get_version()` returns a string representing the HTTP -protocol version associated with the request _res_, such as "HTTP/1.1". - - -== RETURN VALUES - -Response version as a string. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc(3http)], -xref:nng_http_res_set_version.3http.adoc[nng_http_res_set_version(3http)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_res_reset.3http.adoc b/docs/man/nng_http_res_reset.3http.adoc deleted file mode 100644 index f78d29a2..00000000 --- a/docs/man/nng_http_res_reset.3http.adoc +++ /dev/null @@ -1,44 +0,0 @@ -= nng_http_res_reset(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_res_reset - reset HTTP response structure - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -void nng_http_res_reset(nng_http_res *res); ----- - -== DESCRIPTION - -The `nng_http_res_reset()` function resets the response __res__ so that it -is just as if it had been freshly allocated with -xref:nng_http_res_alloc.3http.adoc[`nng_http_res_alloc()`]. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc(3http)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_res_set_data.3http.adoc b/docs/man/nng_http_res_set_data.3http.adoc deleted file mode 100644 index 7c4c06bc..00000000 --- a/docs/man/nng_http_res_set_data.3http.adoc +++ /dev/null @@ -1,64 +0,0 @@ -= nng_http_res_set_data(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_res_set_data - set HTTP response body - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -int nng_http_res_set_data(nng_http_res *res, const void *body, size_t size); ----- - -== DESCRIPTION - -The `nng_http_res_set_data()` sets the HTTP body associated with -the response _res_ to _body_, and the size of the body to _size_. -This body data will be automatically sent with the response when it -is sent using xref:nng_http_conn_write_res.3http.adoc[`nng_http_conn_write_res()`]. - -This also updates the relevant `Content-Length` header of _res_. - -NOTE: The current framework does not support sending data via chunked -transfer-encoding. - -The _body_ is *not* copied, and the caller must ensure that it is available -until the _res_ is deallocated. - -TIP: To have a local copy allocated with _res_ that will be automatically -deallocated when _res_ is freed, -see xref:nng_http_res_copy_data.3http.adoc[`nng_http_res_copy_data()`]. - -TIP: It is a good idea to also set the `Content-Type` header. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory to perform the operation. -`NNG_ENOTSUP`:: No support for HTTP in the library. - -== SEE ALSO - -[.text-left] -xref:nng_http_conn_write_res.3http.adoc[nng_http_conn_write_res(3http)], -xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc(3http)], -xref:nng_http_res_copy_data.3http.adoc[nng_http_res_copy_data(3http)], -xref:nng_http_res_set_header.3http.adoc[nng_http_res_set_header(3http)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_res_set_header.3http.adoc b/docs/man/nng_http_res_set_header.3http.adoc deleted file mode 100644 index 2ad4282e..00000000 --- a/docs/man/nng_http_res_set_header.3http.adoc +++ /dev/null @@ -1,59 +0,0 @@ -= nng_http_res_set_header(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_res_set_header - set HTTP response header - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -int nng_http_res_set_header(nng_http_res *res, const char *key, - const char *val); ----- - -== DESCRIPTION - -The `nng_http_res_set_header()` sets the HTTP header for the response -_res_ and the _key_ to the _val_. -The _key_ and _val_ are copied. -Any previous header with the same _key_ is replaced. - -TIP: See xref:nng_http_res_add_header.3http.adoc[`nng_http_res_add_header()`] to -add additional headers with the same _key_ without replacing them. - -The value of _key_ is case insensitive, and should not include the final -colon in an HTTP header. -For example, specifying `Host` or `hOSt` are -equivalent, whereas the value `Host:` is not a legal header key. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory to perform the operation. -`NNG_ENOTSUP`:: No support for HTTP in the library. - -== SEE ALSO - -[.text-left] -xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc(3http)], -xref:nng_http_res_add_header.3http.adoc[nng_http_res_add_header(3http)], -xref:nng_http_res_del_header.3http.adoc[nng_http_res_del_header(3http)], -xref:nng_http_res_get_header.3http.adoc[nng_http_res_get_header(3http)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_res_set_status.3http.adoc b/docs/man/nng_http_res_set_status.3http.adoc deleted file mode 100644 index a1374941..00000000 --- a/docs/man/nng_http_res_set_status.3http.adoc +++ /dev/null @@ -1,115 +0,0 @@ -= nng_http_res_set_status(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_res_set_status - set HTTP response status - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -void nng_http_res_set_status(nng_http_res *res, uint16_t status); ----- - -== DESCRIPTION - -The `nng_http_res_set_status()` sets the numeric HTTP status code -associated with the response _res_ to _status_. -The default value for a newly allocated response is 200 (`NNG_HTTP_STATUS_OK`). - -The _status_ is not verified, so the caller should take care to ensure -that only a valid code is supplied. - -For convenience, a number of predefined symbols are available. - -[source, c] ----- -enum { - NNG_HTTP_STATUS_CONTINUE = 100, - NNG_HTTP_STATUS_SWITCHING = 101, - NNG_HTTP_STATUS_PROCESSING = 102, - NNG_HTTP_STATUS_OK = 200, - NNG_HTTP_STATUS_CREATED = 201, - NNG_HTTP_STATUS_ACCEPTED = 202, - NNG_HTTP_STATUS_NOT_AUTHORITATIVE = 203, - NNG_HTTP_STATUS_NO_CONTENT = 204, - NNG_HTTP_STATUS_RESET_CONTENT = 205, - NNG_HTTP_STATUS_PARTIAL_CONTENT = 206, - NNG_HTTP_STATUS_MULTI_STATUS = 207, - NNG_HTTP_STATUS_ALREADY_REPORTED = 208, - NNG_HTTP_STATUS_IM_USED = 226, - NNG_HTTP_STATUS_MULTIPLE_CHOICES = 300, - NNG_HTTP_STATUS_STATUS_MOVED_PERMANENTLY = 301, - NNG_HTTP_STATUS_FOUND = 302, - NNG_HTTP_STATUS_SEE_OTHER = 303, - NNG_HTTP_STATUS_NOT_MODIFIED = 304, - NNG_HTTP_STATUS_USE_PROXY = 305, - NNG_HTTP_STATUS_TEMPORARY_REDIRECT = 307, - NNG_HTTP_STATUS_PERMANENT_REDIRECT = 308, - NNG_HTTP_STATUS_BAD_REQUEST = 400, - NNG_HTTP_STATUS_UNAUTHORIZED = 401, - NNG_HTTP_STATUS_PAYMENT_REQUIRED = 402, - NNG_HTTP_STATUS_FORBIDDEN = 403, - NNG_HTTP_STATUS_NOT_FOUND = 404, - NNG_HTTP_STATUS_METHOD_NOT_ALLOWED = 405, - NNG_HTTP_STATUS_NOT_ACCEPTABLE = 406, - NNG_HTTP_STATUS_PROXY_AUTH_REQUIRED = 407, - NNG_HTTP_STATUS_REQUEST_TIMEOUT = 408, - NNG_HTTP_STATUS_CONFLICT = 409, - NNG_HTTP_STATUS_GONE = 410, - NNG_HTTP_STATUS_LENGTH_REQUIRED = 411, - NNG_HTTP_STATUS_PRECONDITION_FAILED = 412, - NNG_HTTP_STATUS_PAYLOAD_TOO_LARGE = 413, - NNG_HTTP_STATUS_ENTITY_TOO_LONG = 414, - NNG_HTTP_STATUS_UNSUPPORTED_MEDIA_TYPE = 415, - NNG_HTTP_STATUS_RANGE_NOT_SATISFIABLE = 416, - NNG_HTTP_STATUS_EXPECTATION_FAILED = 417, - NNG_HTTP_STATUS_TEAPOT = 418, - NNG_HTTP_STATUS_UNPROCESSABLE_ENTITY = 422, - NNG_HTTP_STATUS_LOCKED = 423, - NNG_HTTP_STATUS_FAILED_DEPENDENCY = 424, - NNG_HTTP_STATUS_UPGRADE_REQUIRED = 426, - NNG_HTTP_STATUS_PRECONDITION_REQUIRED = 428, - NNG_HTTP_STATUS_TOO_MANY_REQUESTS = 429, - NNG_HTTP_STATUS_HEADERS_TOO_LARGE = 431, - NNG_HTTP_STATUS_UNAVAIL_LEGAL_REASONS = 451, - NNG_HTTP_STATUS_INTERNAL_SERVER_ERROR = 500, - NNG_HTTP_STATUS_NOT_IMPLEMENTED = 501, - NNG_HTTP_STATUS_BAD_GATEWAY = 502, - NNG_HTTP_STATUS_SERVICE_UNAVAILABLE = 503, - NNG_HTTP_STATUS_GATEWAY_TIMEOUT = 504, - NNG_HTTP_STATUS_HTTP_VERSION_NOT_SUPP = 505, - NNG_HTTP_STATUS_VARIANT_ALSO_NEGOTIATES = 506, - NNG_HTTP_STATUS_INSUFFICIENT_STORAGE = 507, - NNG_HTTP_STATUS_LOOP_DETECTED = 508, - NNG_HTTP_STATUS_NOT_EXTENDED = 510, - NNG_HTTP_STATUS_NETWORK_AUTH_REQUIRED = 511, -}; ----- - -Please see the relevant HTTP RFCs for the semantics and correct -use of these status codes. - -TIP: It is a good idea to also set the reason message with -xref:nng_http_res_set_reason.3http.adoc[`nng_http_set_reason()`]. -This will help any humans who may have to diagnose a failure. - -== SEE ALSO - -[.text-left] -xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc(3http)], -xref:nng_http_res_get_status.3http.adoc[nng_http_req_get_status(3http)], -xref:nng_http_res_set_reason.3http.adoc[nng_http_req_set_reason(3http)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_res_set_version.3http.adoc b/docs/man/nng_http_res_set_version.3http.adoc deleted file mode 100644 index 47ce3cd7..00000000 --- a/docs/man/nng_http_res_set_version.3http.adoc +++ /dev/null @@ -1,57 +0,0 @@ -= nng_http_res_set_version(3http) -// -// Copyright 2024 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_res_set_version - set HTTP response protocol version - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -#define NNG_HTTP_VERSION_1_1 "HTTP/1.0" -#define NNG_HTTP_VERSION_1_1 "HTTP/1.1" - -int nng_http_res_set_version(nng_http_res *res, const char *version); ----- - -== DESCRIPTION - -The `nng_http_res_set_version()` sets the HTTP protocol version associated with -the response _res_ to _version_. -The _version_ must be a string containing -a valid HTTP protocol version, such as "HTTP/1.0". -The default value is "HTTP/1.1". - -A local copy of the _version_ is made in the response _res_. - -NOTE: The library does not contain support for versions of HTTP other than -"HTTP/1.0" and "HTTP/1.1". - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory to perform the operation. -`NNG_ENOTSUP`:: No support for HTTP in the library, or no support for the version specified. - -== SEE ALSO - -[.text-left] -xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc(3http)], -xref:nng_http_req_get_version.3http.adoc[nng_http_req_get_version(3http)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_server_add_handler.3http.adoc b/docs/man/nng_http_server_add_handler.3http.adoc index 5b5c474b..dc839c3a 100644 --- a/docs/man/nng_http_server_add_handler.3http.adoc +++ b/docs/man/nng_http_server_add_handler.3http.adoc @@ -18,7 +18,7 @@ nng_http_server_add_handler - add HTTP server handler [source, c] ---- #include <nng/nng.h> -#include <nng/supplemental/http/http.h> +#include <nng/http.h> int nng_http_server_add_handler(nng_http_server *s, nng_http_handler *h); ---- diff --git a/docs/man/nng_http_server_del_handler.3http.adoc b/docs/man/nng_http_server_del_handler.3http.adoc index 4ff89f7d..a4bb203c 100644 --- a/docs/man/nng_http_server_del_handler.3http.adoc +++ b/docs/man/nng_http_server_del_handler.3http.adoc @@ -18,7 +18,7 @@ nng_http_server_del_handler - delete HTTP server handler [source, c] ---- #include <nng/nng.h> -#include <nng/supplemental/http/http.h> +#include <nng/http.h> int nng_http_server_del_handler(nng_http_server *s, nng_http_handler *h); ---- diff --git a/docs/man/nng_http_server_get_addr.3http.adoc b/docs/man/nng_http_server_get_addr.3http.adoc index dc699014..c640c8fa 100644 --- a/docs/man/nng_http_server_get_addr.3http.adoc +++ b/docs/man/nng_http_server_get_addr.3http.adoc @@ -18,7 +18,7 @@ nng_http_server_get_addr - get HTTP server address [source, c] ---- #include <nng/nng.h> -#include <nng/supplemental/http/http.h> +#include <nng/http.h> int nng_http_server_get_addr(nng_http_server *server, nng_sockaddr *sap); ---- diff --git a/docs/man/nng_http_server_get_tls.3http.adoc b/docs/man/nng_http_server_get_tls.3http.adoc index 51bc7218..a6268e77 100644 --- a/docs/man/nng_http_server_get_tls.3http.adoc +++ b/docs/man/nng_http_server_get_tls.3http.adoc @@ -18,7 +18,7 @@ nng_http_server_get_tls - get HTTP server TLS configuration [source, c] ---- #include <nng/nng.h> -#include <nng/supplemental/http/http.h> +#include <nng/http.h> int nng_http_server_get_tls(nng_http_server *s, nng_tls_config **cfgp); ---- diff --git a/docs/man/nng_http_server_hold.3http.adoc b/docs/man/nng_http_server_hold.3http.adoc index 0111d43f..9c0fcf81 100644 --- a/docs/man/nng_http_server_hold.3http.adoc +++ b/docs/man/nng_http_server_hold.3http.adoc @@ -18,7 +18,7 @@ nng_http_server_hold - get and hold HTTP server instance [source, c] ---- #include <nng/nng.h> -#include <nng/supplemental/http/http.h> +#include <nng/http.h> int nng_http_server_hold(nng_http_server **serverp, const nng_url *url); ---- diff --git a/docs/man/nng_http_server_release.3http.adoc b/docs/man/nng_http_server_release.3http.adoc index 0d919191..86471e4c 100644 --- a/docs/man/nng_http_server_release.3http.adoc +++ b/docs/man/nng_http_server_release.3http.adoc @@ -18,7 +18,7 @@ nng_http_server_release - release HTTP server instance [source, c] ---- #include <nng/nng.h> -#include <nng/supplemental/http/http.h> +#include <nng/http.h> void nng_http_server_release(nng_http_server *server); ---- diff --git a/docs/man/nng_http_server_res_error.3http.adoc b/docs/man/nng_http_server_res_error.3http.adoc index b669a061..e3d0271f 100644 --- a/docs/man/nng_http_server_res_error.3http.adoc +++ b/docs/man/nng_http_server_res_error.3http.adoc @@ -18,9 +18,9 @@ nng_http_server_res_error - use HTTP server error page [source, c] ---- #include <nng/nng.h> -#include <nng/supplemental/http/http.h> +#include <nng/http.h> -int nng_http_server_res_error(nng_http_server *server, +int nng_http_server_res_error(nng_http_server *server, nng_http_res *response); ---- @@ -33,10 +33,7 @@ or xref:nng_http_server_set_error_page.3http.adoc[`nng_http_server_error_page()`] functions. -The status code of the _response_ should have already been set, either -implicitly by allocating it with -xref:nng_http_res_alloc_error.3http.adoc[`nng_http_res_alloc_error()`], -or by calling +The status code of the _response_ should have already been set by calling xref:nng_http_res_set_status.3http.adoc[`nng_http_res_set_status()`]. Any content body previously set for _response_ will be overridden by @@ -55,7 +52,6 @@ This function returns 0 on success, and non-zero otherwise. == SEE ALSO [.text-left] -xref:nng_http_res_alloc_error.3http.adoc[nng_http_res_alloc_error(3http)], xref:nng_http_server_hold.3http.adoc[nng_http_server_hold(3http)], xref:nng_http_server_set_error_file.3http.adoc[nng_http_server_set_error_file(3http)], xref:nng_http_server_set_error_page.3http.adoc[nng_http_server_set_error_page(3http)], diff --git a/docs/man/nng_http_server_set_error_file.3http.adoc b/docs/man/nng_http_server_set_error_file.3http.adoc deleted file mode 100644 index ac38f6f9..00000000 --- a/docs/man/nng_http_server_set_error_file.3http.adoc +++ /dev/null @@ -1,73 +0,0 @@ -= nng_http_server_set_error_file(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_server_set_error_file - set custom HTTP error file - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/http/http.h> - -int nng_http_server_set_error_file(nng_http_server *server, - uint16_t code, const char *path); ----- - -== DESCRIPTION - -The `nng_http_server_set_error_file()` sets an error page to be used -for HTTP status _code_ on the server instance _server_. -The body content of the HTTP responses will contain the file contents of -the file located at _path_, which should be an HTML file. - -The custom HTML content will be used when the server is returning an -internally generated error response, or is returning an error response -that was allocated with the -xref:nng_http_res_alloc_error.3http.adoc[`nng_http_res_alloc_error()`] -function. -This HTML content will also be used if the application calls the -xref:nng_http_server_res_error.3http.adoc[`nng_http_server_res_error()`]. -The last custom error page set for _code_ by either this function or -xref:`nng_http_server_set_error_page.3http.adoc[`nng_http_server_error_page()`] -will be used. - -NOTE: Error responses that have their body content changed after allocation, -or that are written directly by the application, will not use the body -content supplied here. - -NOTE: The file contents of _path_ are read when this function is called. -Therefore, if the file contents are changed, then this function should -be called again to update the error page. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOENT`:: The file named by _path_ does not exist. -`NNG_EPERM`:: No permission to read the file named by _path_. -`NNG_ENOMEM`:: Insufficient free memory exists. -`NNG_ENOTSUP`:: HTTP not supported. - -== SEE ALSO - -[.text-left] -xref:nng_http_res_alloc_error.3http.adoc[nng_http_res_alloc_error(3http)], -xref:nng_http_server_hold.3http.adoc[nng_http_server_hold(3http)], -xref:nng_http_server_res_error.3http.adoc[nng_http_server_res_error(3http)], -xref:nng_http_server_set_error_page.3http.adoc[nng_http_server_set_error_page(3http)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_server_set_error_page.3http.adoc b/docs/man/nng_http_server_set_error_page.3http.adoc index d3b136d5..7f414a5a 100644 --- a/docs/man/nng_http_server_set_error_page.3http.adoc +++ b/docs/man/nng_http_server_set_error_page.3http.adoc @@ -18,7 +18,7 @@ nng_http_server_set_error_page - set custom HTTP error page [source, c] ---- #include <nng/nng.h> -#include <nng/supplemental/http/http.h> +#include <nng/http.h> int nng_http_server_set_error_page(nng_http_server *server, uint16_t code, const char *html); @@ -31,10 +31,7 @@ for HTTP status _code_ on the server instance _server_. The body content of the HTTP responses will contain _html_. The custom HTML content will be used when the server is returning an -internally generated error response, or is returning an error response -that was allocated with the -xref:nng_http_res_alloc_error.3http.adoc[`nng_http_res_alloc_error()`] -function. +internally generated error response. This HTML content will also be used if the application calls the xref:nng_http_server_res_error.3http.adoc[`nng_http_server_res_error()`]. The last custom error page set for _code_ by either this function or @@ -61,7 +58,6 @@ This function returns 0 on success, and non-zero otherwise. == SEE ALSO [.text-left] -xref:nng_http_res_alloc_error.3http.adoc[nng_http_res_alloc_error(3http)], xref:nng_http_server_hold.3http.adoc[nng_http_server_hold(3http)], xref:nng_http_server_res_error.3http.adoc[nng_http_server_res_error(3http)], xref:nng_http_server_set_error_file.3http.adoc[nng_http_server_set_error_file(3http)], diff --git a/docs/man/nng_http_server_set_tls.3http.adoc b/docs/man/nng_http_server_set_tls.3http.adoc index 1fe8eaa1..9979c735 100644 --- a/docs/man/nng_http_server_set_tls.3http.adoc +++ b/docs/man/nng_http_server_set_tls.3http.adoc @@ -18,7 +18,7 @@ nng_http_server_set_tls - set HTTP server TLS configuration [source, c] ---- #include <nng/nng.h> -#include <nng/supplemental/http/http.h> +#include <nng/http.h> int nng_http_server_set_tls(nng_http_server *s, nng_tls_config *cfg); ---- diff --git a/docs/man/nng_http_server_start.3http.adoc b/docs/man/nng_http_server_start.3http.adoc index 31e0f325..23e4e376 100644 --- a/docs/man/nng_http_server_start.3http.adoc +++ b/docs/man/nng_http_server_start.3http.adoc @@ -18,7 +18,7 @@ nng_http_server_start - start HTTP server [source, c] ---- #include <nng/nng.h> -#include <nng/supplemental/http/http.h> +#include <nng/http.h> int nng_http_server_start(nng_http_server *server); ---- diff --git a/docs/man/nng_http_server_stop.3http.adoc b/docs/man/nng_http_server_stop.3http.adoc index 098d7bdf..6da3b35a 100644 --- a/docs/man/nng_http_server_stop.3http.adoc +++ b/docs/man/nng_http_server_stop.3http.adoc @@ -18,7 +18,7 @@ nng_http_server_stop - stop HTTP server [source, c] ---- #include <nng/nng.h> -#include <nng/supplemental/http/http.h> +#include <nng/http.h> void nng_http_server_stop(nng_http_server *server); ---- diff --git a/docs/man/nng_http_req_set_method.3http.adoc b/docs/man/nng_http_set_method.3http.adoc index 9cd4f638..893dc875 100644 --- a/docs/man/nng_http_req_set_method.3http.adoc +++ b/docs/man/nng_http_set_method.3http.adoc @@ -1,6 +1,6 @@ -= nng_http_req_set_method(3http) += nng_http_set_method(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> // // This document is supplied under the terms of the MIT License, a @@ -11,7 +11,7 @@ == NAME -nng_http_req_set_method - set HTTP request method +nng_http_set_method - set HTTP request method == SYNOPSIS @@ -20,26 +20,25 @@ nng_http_req_set_method - set HTTP request method #include <nng/nng.h> #include <nng/supplemental/http/http.h> -void nng_http_req_set_method(nng_http_req *req, const char *method); +void nng_http_set_method(nng_http *conn, const char *method); ---- == DESCRIPTION -The `nng_http_req_set_method()` sets the HTTP method associated with -the request _req_ to _method_. The _method_ must be a string, -such as "GET" or "POST", and the HTTP specifications indicate that it must -be upper case. +The `nng_http_set_method()` sets the HTTP method associated with +the connection _conn_ to _method_. The _method_ must be a string, +such as "GET" or "POST". The default value method for newly allocated requests is "GET". If the method is longer than 32 bytes, it may be silently truncated. (There are no methods defined that are this long.) -A local copy of the _method_ is made in the request _req_. +The value _method_ is copied, so the caller may dispose of it after +the call completes. == SEE ALSO [.text-left] -xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc(3http)], -xref:nng_http_req_get_method.3http.adoc[nng_http_req_get_method(3http)], +xref:nng_http_get_method.3http.adoc[nng_http_get_method(3http)], xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_http_res_set_reason.3http.adoc b/docs/man/nng_http_set_reason.3http.adoc index 50699de2..62fb4561 100644 --- a/docs/man/nng_http_res_set_reason.3http.adoc +++ b/docs/man/nng_http_set_reason.3http.adoc @@ -1,6 +1,6 @@ -= nng_http_res_set_reason(3http) += nng_http_set_reason(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> // // This document is supplied under the terms of the MIT License, a @@ -11,26 +11,26 @@ == NAME -nng_http_res_set_reason - set HTTP response reason +nng_http_set_reason - set HTTP response reason == SYNOPSIS [source, c] ---- #include <nng/nng.h> -#include <nng/supplemental/http/http.h> +#include <nng/http.h> -int nng_http_res_set_reason(nng_http_res *res, const char *reason); +int nng_http_set_reason(nng_http *conn, const char *reason); ---- == DESCRIPTION -The `nng_http_res_set_reason()` sets the human readable reason -associated with the response _res_ to _reason_. +The `nng_http_set_reason()` sets the human readable reason +associated with the response for _conn_ to _reason_. If the value of _reason_ is `NULL` (the default), then a default reason phrase is supplied based upon the value of the status code (see -xref:nng_http_res_set_status.3http.adoc[`nng_http_res_set_status()`]). +xref:nng_http_set_status.3http.adoc[`nng_http_set_status()`]). TIP: The _reason_ is never parsed automatically, but it can be a hint for humans to help them understand the nature of any erroneous result. @@ -50,7 +50,5 @@ This function returns 0 on success, and non-zero otherwise. == SEE ALSO [.text-left] -xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc(3http)], -xref:nng_http_res_get_reason.3http.adoc[nng_http_req_get_reason(3http)], -xref:nng_http_res_set_status.3http.adoc[nng_http_req_set_status(3http)], -xref:nng.7.adoc[nng(7)] +xref:nng_http_get_reason.3http.adoc[nng_http_get_reason(3http)], +xref:nng_http_set_status.3http.adoc[nng_http_set_status(3http)] diff --git a/docs/man/nng_ws.7.adoc b/docs/man/nng_ws.7.adoc index 938b16a9..49783920 100644 --- a/docs/man/nng_ws.7.adoc +++ b/docs/man/nng_ws.7.adoc @@ -107,19 +107,12 @@ setting these must be done before the transport is started. NOTE: The TLS specific options (beginning with `NNG_OPT_TLS_`) are only available for `wss://` endpoints. -((`NNG_OPT_WS_REQUEST_HEADERS`)):: +((`NNG_OPT_WS_HEADER`)):: -(string) Concatenation of multiple lines terminated -by CRLF sequences, that can be used to add further headers to the -HTTP request sent when connecting. -This option can be set on dialers, and retrieved from pipes. +The actual option is a prefix string, beginning with the the contents of the +macro `NNG_OPT_WS_HEADER`, followed by the name of header field. -((`NNG_OPT_WS_RESPONSE_HEADERS`)):: - -(string) Concatenation of multiple lines terminated -by CRLF sequences, that can be used to add further headers to the -HTTP response sent when connecting. -This option can be set on listeners, and retrieved from pipes. +Such options can be set on dialers and listener, and retrieved from pipes. ((`NNG_OPT_WS_RECV_TEXT`)):: |