From fc0abbdf71700b2414ba012f9863f7dfaf514b91 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Fri, 2 Feb 2018 12:46:02 -0800 Subject: Document HTTP request/reply structures and handling. --- docs/libnng.adoc | 45 +++++++++++++ docs/nng_http_req_add_header.adoc | 70 ++++++++++++++++++++ docs/nng_http_req_alloc.adoc | 69 +++++++++++++++++++ docs/nng_http_req_copy_data.adoc | 68 +++++++++++++++++++ docs/nng_http_req_del_header.adoc | 60 +++++++++++++++++ docs/nng_http_req_free.adoc | 50 ++++++++++++++ docs/nng_http_req_get_header.adoc | 59 +++++++++++++++++ docs/nng_http_req_get_method.adoc | 53 +++++++++++++++ docs/nng_http_req_get_uri.adoc | 54 +++++++++++++++ docs/nng_http_req_get_version.adoc | 53 +++++++++++++++ docs/nng_http_req_set_data.adoc | 70 ++++++++++++++++++++ docs/nng_http_req_set_header.adoc | 64 ++++++++++++++++++ docs/nng_http_req_set_method.adoc | 59 +++++++++++++++++ docs/nng_http_req_set_uri.adoc | 64 ++++++++++++++++++ docs/nng_http_req_set_version.adoc | 64 ++++++++++++++++++ docs/nng_http_res_add_header.adoc | 70 ++++++++++++++++++++ docs/nng_http_res_alloc.adoc | 73 +++++++++++++++++++++ docs/nng_http_res_alloc_error.adoc | 63 ++++++++++++++++++ docs/nng_http_res_copy_data.adoc | 68 +++++++++++++++++++ docs/nng_http_res_del_header.adoc | 60 +++++++++++++++++ docs/nng_http_res_free.adoc | 50 ++++++++++++++ docs/nng_http_res_get_header.adoc | 59 +++++++++++++++++ docs/nng_http_res_get_reason.adoc | 55 ++++++++++++++++ docs/nng_http_res_get_status.adoc | 125 +++++++++++++++++++++++++++++++++++ docs/nng_http_res_get_version.adoc | 53 +++++++++++++++ docs/nng_http_res_set_data.adoc | 70 ++++++++++++++++++++ docs/nng_http_res_set_header.adoc | 63 ++++++++++++++++++ docs/nng_http_res_set_reason.adoc | 63 ++++++++++++++++++ docs/nng_http_res_set_status.adoc | 131 +++++++++++++++++++++++++++++++++++++ docs/nng_http_res_set_version.adoc | 64 ++++++++++++++++++ 30 files changed, 1969 insertions(+) create mode 100644 docs/nng_http_req_add_header.adoc create mode 100644 docs/nng_http_req_alloc.adoc create mode 100644 docs/nng_http_req_copy_data.adoc create mode 100644 docs/nng_http_req_del_header.adoc create mode 100644 docs/nng_http_req_free.adoc create mode 100644 docs/nng_http_req_get_header.adoc create mode 100644 docs/nng_http_req_get_method.adoc create mode 100644 docs/nng_http_req_get_uri.adoc create mode 100644 docs/nng_http_req_get_version.adoc create mode 100644 docs/nng_http_req_set_data.adoc create mode 100644 docs/nng_http_req_set_header.adoc create mode 100644 docs/nng_http_req_set_method.adoc create mode 100644 docs/nng_http_req_set_uri.adoc create mode 100644 docs/nng_http_req_set_version.adoc create mode 100644 docs/nng_http_res_add_header.adoc create mode 100644 docs/nng_http_res_alloc.adoc create mode 100644 docs/nng_http_res_alloc_error.adoc create mode 100644 docs/nng_http_res_copy_data.adoc create mode 100644 docs/nng_http_res_del_header.adoc create mode 100644 docs/nng_http_res_free.adoc create mode 100644 docs/nng_http_res_get_header.adoc create mode 100644 docs/nng_http_res_get_reason.adoc create mode 100644 docs/nng_http_res_get_status.adoc create mode 100644 docs/nng_http_res_get_version.adoc create mode 100644 docs/nng_http_res_set_data.adoc create mode 100644 docs/nng_http_res_set_header.adoc create mode 100644 docs/nng_http_res_set_reason.adoc create mode 100644 docs/nng_http_res_set_status.adoc create mode 100644 docs/nng_http_res_set_version.adoc (limited to 'docs') diff --git a/docs/libnng.adoc b/docs/libnng.adoc index 57337f47..b23383cc 100644 --- a/docs/libnng.adoc +++ b/docs/libnng.adoc @@ -171,6 +171,51 @@ universal resource locators (URLS). | <>|create URL structure from string |=== + +=== HTTP Support + +The library may be configured with support for HTTP, and this will +be the case if WebSocket support is configured as well. In this case, +it is possible to access functionality to support the creation of +HTTP (and HTTP/S if TLS support is present) servers and clients. + +==== Common HTTP Functions + +The following functions are used to work with HTTP requests, responses, +and connections. + +|=== +| <>|add HTTP request header +| <>|allocate HTTP request structure +| <>|copy HTTP request body +| <>|delete HTTP request header +| <>|free HTTP request structure +| <>|return HTTP request header +| <>|return HTTP request method +| <>|return HTTP request URI +| <>|return HTTP request protocol version +| <>|set HTTP request body +| <>|set HTTP request header +| <>|set HTTP request method +| <>|set HTTP request URI +| <>|set HTTP request protocol version +| <>|add HTTP response header +| <>|allocate HTTP response structure +| <>|allocate HTTP error response +| <>|copy HTTP response body +| <>|delete HTTP response header +| <>|free HTTP response structure +| <>|set HTTP response body +| <>|return HTTP response header +| <>|return HTTP response reason +| <>|return HTTP response status +| <>|return HTTP response protocol version +| <>|set HTTP response header +| <>|set HTTP response reason +| <>|set HTTP response status +| <>|set HTTP response protocol version +|=== + === TLS Configuration Objects The following functions are used to manipulate transport layer security diff --git a/docs/nng_http_req_add_header.adoc b/docs/nng_http_req_add_header.adoc new file mode 100644 index 00000000..beffa97a --- /dev/null +++ b/docs/nng_http_req_add_header.adoc @@ -0,0 +1,70 @@ += nng_http_req_add_header(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. \ + Copyright 2018 Capitar IT Group BV \ + This software 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 + +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 <> 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 + +`NNG_ENOMEM`:: Insufficient memory to perform the operation. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +<>, +<>, +<>, +<>, +<> + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_http_req_alloc.adoc b/docs/nng_http_req_alloc.adoc new file mode 100644 index 00000000..f15772f7 --- /dev/null +++ b/docs/nng_http_req_alloc.adoc @@ -0,0 +1,69 @@ += nng_http_req_alloc(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. \ + Copyright 2018 Capitar IT Group BV \ + This software 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 + +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__. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient free memory exists to allocate a message. +`NNG_ENOTSUP`:: HTTP support not configured. + +== SEE ALSO + +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<> +<>, +<> + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_http_req_copy_data.adoc b/docs/nng_http_req_copy_data.adoc new file mode 100644 index 00000000..0ae54cf0 --- /dev/null +++ b/docs/nng_http_req_copy_data.adoc @@ -0,0 +1,68 @@ += nng_http_req_copy_data(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. \ + Copyright 2018 Capitar IT Group BV \ + This software 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 + +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 <>. + +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 +<> 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 + +`NNG_ENOMEM`:: Insufficient memory to perform the operation. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +<>, +<>, +<>, +<>, +<> + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_http_req_del_header.adoc b/docs/nng_http_req_del_header.adoc new file mode 100644 index 00000000..e58650db --- /dev/null +++ b/docs/nng_http_req_del_header.adoc @@ -0,0 +1,60 @@ += nng_http_req_set_header(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. \ + Copyright 2018 Capitar IT Group BV \ + This software 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 + +int nng_http_req_set_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 + +`NNG_ENOENT`:: No header with the key _key_ was present. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +<>, +<>, +<>, +<>, +<> + + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_http_req_free.adoc b/docs/nng_http_req_free.adoc new file mode 100644 index 00000000..2b4dc840 --- /dev/null +++ b/docs/nng_http_req_free.adoc @@ -0,0 +1,50 @@ += nng_http_req_free(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. \ + Copyright 2018 Capitar IT Group BV \ + This software 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 + +void nng_http_req_free(nng_http_req *req); +----------- + +== DESCRIPTION + +The `nng_http_req_free()` function deallocates the HTTP request structure +_req_ entirely. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +<>, +<> + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_http_req_get_header.adoc b/docs/nng_http_req_get_header.adoc new file mode 100644 index 00000000..9431f597 --- /dev/null +++ b/docs/nng_http_req_get_header.adoc @@ -0,0 +1,59 @@ += nng_http_req_get_header(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. \ + Copyright 2018 Capitar IT Group BV \ + This software 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 + +const char *nng_http_req_get_header(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 + +<>, +<>, +<>, +<> + + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_http_req_get_method.adoc b/docs/nng_http_req_get_method.adoc new file mode 100644 index 00000000..4ae03516 --- /dev/null +++ b/docs/nng_http_req_get_method.adoc @@ -0,0 +1,53 @@ += nng_http_req_get_method(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. \ + Copyright 2018 Capitar IT Group BV \ + This software 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 + +const char *nng_http_req_get_method(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 + +<>, +<>, +<> + + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_http_req_get_uri.adoc b/docs/nng_http_req_get_uri.adoc new file mode 100644 index 00000000..982a28a1 --- /dev/null +++ b/docs/nng_http_req_get_uri.adoc @@ -0,0 +1,54 @@ += nng_http_req_get_method(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. \ + Copyright 2018 Capitar IT Group BV \ + This software 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 + +const char *nng_http_req_get_method(nng_http_req *req); +----------- + +== DESCRIPTION + +The `nng_http_req_get_uri()` returns the URI (path) associated with the HTTP +the request _req_. The value returned includes the path, as well as any +query information or fragment. The value will look like a filesystem path +with those optional components appened, such as `/api/get_info.cgi?name=garrett`. + +== RETURN VALUES + +Request URI as a string. + +== ERRORS + +None. + +== SEE ALSO + +<>, +<>, +<> + + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_http_req_get_version.adoc b/docs/nng_http_req_get_version.adoc new file mode 100644 index 00000000..5aaac194 --- /dev/null +++ b/docs/nng_http_req_get_version.adoc @@ -0,0 +1,53 @@ += nng_http_req_get_version(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. \ + Copyright 2018 Capitar IT Group BV \ + This software 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 + +const char *nng_http_req_get_version(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 + +<>, +<>, +<> + + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_http_req_set_data.adoc b/docs/nng_http_req_set_data.adoc new file mode 100644 index 00000000..e1b5f6f9 --- /dev/null +++ b/docs/nng_http_req_set_data.adoc @@ -0,0 +1,70 @@ += nng_http_req_set_data(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. \ + Copyright 2018 Capitar IT Group BV \ + This software 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 + +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 <>. + +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 <>. + +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 + +`NNG_ENOMEM`:: Insufficient memory to perform the operation. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +<>, +<>, +<>, +<>, +<> + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_http_req_set_header.adoc b/docs/nng_http_req_set_header.adoc new file mode 100644 index 00000000..e4381906 --- /dev/null +++ b/docs/nng_http_req_set_header.adoc @@ -0,0 +1,64 @@ += nng_http_req_set_header(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. \ + Copyright 2018 Capitar IT Group BV \ + This software 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 + +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 <> 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 + +`NNG_ENOMEM`:: Insufficient memory to perform the operation. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +<>, +<>, +<>, +<>, +<> + + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_http_req_set_method.adoc b/docs/nng_http_req_set_method.adoc new file mode 100644 index 00000000..439f9bc5 --- /dev/null +++ b/docs/nng_http_req_set_method.adoc @@ -0,0 +1,59 @@ += nng_http_req_set_method(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. \ + Copyright 2018 Capitar IT Group BV \ + This software 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_method - set HTTP request method + +== SYNOPSIS + +[source, c] +----------- +#include + +int nng_http_req_set_method(nng_http_req *req, 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 default value method for newly allocated requests is "GET". + +A local copy of the _method_ is made in the request _req_. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient memory to perform the operation. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +<>, +<>, +<> + + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_http_req_set_uri.adoc b/docs/nng_http_req_set_uri.adoc new file mode 100644 index 00000000..3208958a --- /dev/null +++ b/docs/nng_http_req_set_uri.adoc @@ -0,0 +1,64 @@ += nng_http_req_set_uri(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. \ + Copyright 2018 Capitar IT Group BV \ + This software 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 + +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 <> 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 + +`NNG_ENOMEM`:: Insufficient memory to perform the operation. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +<>, +<>, +<>, +<> + + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_http_req_set_version.adoc b/docs/nng_http_req_set_version.adoc new file mode 100644 index 00000000..fdfe117c --- /dev/null +++ b/docs/nng_http_req_set_version.adoc @@ -0,0 +1,64 @@ += nng_http_req_set_version(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. \ + Copyright 2018 Capitar IT Group BV \ + This software 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 + +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: No validation of the version supplied is performed. + +NOTE: The library does not contain support for versions of HTTP other than +"HTTP/1.0" and "HTTP/1.1". Specifying any other version may result in +unspecified behavior. + + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient memory to perform the operation. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +<>, +<>, +<> + + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_http_res_add_header.adoc b/docs/nng_http_res_add_header.adoc new file mode 100644 index 00000000..81203de6 --- /dev/null +++ b/docs/nng_http_res_add_header.adoc @@ -0,0 +1,70 @@ += nng_http_res_add_header(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. \ + Copyright 2018 Capitar IT Group BV \ + This software 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 + +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 <> 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 + +`NNG_ENOMEM`:: Insufficient memory to perform the operation. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +<>, +<>, +<>, +<>, +<> + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_http_res_alloc.adoc b/docs/nng_http_res_alloc.adoc new file mode 100644 index 00000000..73dbccf5 --- /dev/null +++ b/docs/nng_http_res_alloc.adoc @@ -0,0 +1,73 @@ += nng_http_res_alloc(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. \ + Copyright 2018 Capitar IT Group BV \ + This software 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 + +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 +<> instead. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient free memory exists to allocate a message. +`NNG_ENOTSUP`:: HTTP support not configured. + +== SEE ALSO + +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<> + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_http_res_alloc_error.adoc b/docs/nng_http_res_alloc_error.adoc new file mode 100644 index 00000000..21a40d5f --- /dev/null +++ b/docs/nng_http_res_alloc_error.adoc @@ -0,0 +1,63 @@ += nng_http_res_alloc_error(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. \ + Copyright 2018 Capitar IT Group BV \ + This software 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 + +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 + +`NNG_ENOMEM`:: Insufficient free memory exists to allocate a message. +`NNG_ENOTSUP`:: HTTP support not configured. + +== SEE ALSO + +<>, +<>, +<>, +<>, +<>, +<> + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_http_res_copy_data.adoc b/docs/nng_http_res_copy_data.adoc new file mode 100644 index 00000000..2034c033 --- /dev/null +++ b/docs/nng_http_res_copy_data.adoc @@ -0,0 +1,68 @@ += nng_http_res_copy_data(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. \ + Copyright 2018 Capitar IT Group BV \ + This software 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 + +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 <>. + +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 +<> 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 + +`NNG_ENOMEM`:: Insufficient memory to perform the operation. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +<>, +<>, +<>, +<>, +<> + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_http_res_del_header.adoc b/docs/nng_http_res_del_header.adoc new file mode 100644 index 00000000..4c9b8719 --- /dev/null +++ b/docs/nng_http_res_del_header.adoc @@ -0,0 +1,60 @@ += nng_http_res_set_header(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. \ + Copyright 2018 Capitar IT Group BV \ + This software 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 + +int nng_http_res_set_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 + +`NNG_ENOENT`:: No header with the key _key_ was present. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +<>, +<>, +<>, +<>, +<> + + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_http_res_free.adoc b/docs/nng_http_res_free.adoc new file mode 100644 index 00000000..102ddb84 --- /dev/null +++ b/docs/nng_http_res_free.adoc @@ -0,0 +1,50 @@ += nng_http_res_free(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. \ + Copyright 2018 Capitar IT Group BV \ + This software 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 + +void nng_http_res_free(nng_http_res *req); +----------- + +== DESCRIPTION + +The `nng_http_res_free()` function deallocates the HTTP response structure +_res_ entirely. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +<>, +<> + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_http_res_get_header.adoc b/docs/nng_http_res_get_header.adoc new file mode 100644 index 00000000..74bb2f9f --- /dev/null +++ b/docs/nng_http_res_get_header.adoc @@ -0,0 +1,59 @@ += nng_http_res_get_header(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. \ + Copyright 2018 Capitar IT Group BV \ + This software 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 + +const char *nng_http_res_get_header(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 + +<>, +<>, +<>, +<> + + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_http_res_get_reason.adoc b/docs/nng_http_res_get_reason.adoc new file mode 100644 index 00000000..12e25352 --- /dev/null +++ b/docs/nng_http_res_get_reason.adoc @@ -0,0 +1,55 @@ += nng_http_res_get_reason(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. \ + Copyright 2018 Capitar IT Group BV \ + This software 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 + +const char *nng_http_res_get_reason(nng_http_res *res); +----------- + +== DESCRIPTION + +The `nng_http_res_get_reason()` returns a string representing the "reason +phrase" associated with the response _res_. This is a human-readable +explanation of the status code that would be obtained from +<>. + +== RETURN VALUES + +Reason as a string. + +== ERRORS + +None. + +== SEE ALSO + +<>, +<>, +<>, +<> + + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_http_res_get_status.adoc b/docs/nng_http_res_get_status.adoc new file mode 100644 index 00000000..5a0db720 --- /dev/null +++ b/docs/nng_http_res_get_status.adoc @@ -0,0 +1,125 @@ += nng_http_res_get_status(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. \ + Copyright 2018 Capitar IT Group BV \ + This software 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 + +uint16_t nng_http_res_get_status(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 phrase" obtained with +<>. + +== RETURN VALUES + +HTTP status code. + +== ERRORS + +None. + +== SEE ALSO + +<>, +<>, +<>, +<> + + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_http_res_get_version.adoc b/docs/nng_http_res_get_version.adoc new file mode 100644 index 00000000..740dd661 --- /dev/null +++ b/docs/nng_http_res_get_version.adoc @@ -0,0 +1,53 @@ += nng_http_res_get_version(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. \ + Copyright 2018 Capitar IT Group BV \ + This software 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 + +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 + +<>, +<>, +<> + + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_http_res_set_data.adoc b/docs/nng_http_res_set_data.adoc new file mode 100644 index 00000000..a2f29ba1 --- /dev/null +++ b/docs/nng_http_res_set_data.adoc @@ -0,0 +1,70 @@ += nng_http_res_set_data(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. \ + Copyright 2018 Capitar IT Group BV \ + This software 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 + +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 <>. + +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 <>. + +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 + +`NNG_ENOMEM`:: Insufficient memory to perform the operation. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +<>, +<>, +<>, +<>, +<> + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_http_res_set_header.adoc b/docs/nng_http_res_set_header.adoc new file mode 100644 index 00000000..630d9fc4 --- /dev/null +++ b/docs/nng_http_res_set_header.adoc @@ -0,0 +1,63 @@ += nng_http_res_set_header(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. \ + Copyright 2018 Capitar IT Group BV \ + This software 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 + +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 <> 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 + +`NNG_ENOMEM`:: Insufficient memory to perform the operation. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +<>, +<>, +<>, +<>, +<> + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_http_res_set_reason.adoc b/docs/nng_http_res_set_reason.adoc new file mode 100644 index 00000000..7321badb --- /dev/null +++ b/docs/nng_http_res_set_reason.adoc @@ -0,0 +1,63 @@ += nng_http_res_set_reason(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. \ + Copyright 2018 Capitar IT Group BV \ + This software 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_reason - set HTTP response reason + +== SYNOPSIS + +[source, c] +----------- +#include + +int nng_http_res_set_reason(nng_http_res *res, const char *reason); +----------- + +== DESCRIPTION + +The `nng_http_res_set_reason()` sets the human readable "reason phrase" +associated with the response _res_ 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 +<>). + +TIP: The _reason_ is never parsed automatically, but it can be a hint for humans + to help them understand the nature of any erroroneous result. + +A local copy of the _reason_ is made in the response _res_. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient memory to perform the operation. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +<>, +<>, +<>, +<> + + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_http_res_set_status.adoc b/docs/nng_http_res_set_status.adoc new file mode 100644 index 00000000..f8a88c8e --- /dev/null +++ b/docs/nng_http_res_set_status.adoc @@ -0,0 +1,131 @@ += nng_http_res_set_status(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. \ + Copyright 2018 Capitar IT Group BV \ + This software 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 + +int 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 phrase" with +<>. This +will help any humans who may have to diagnose any failure. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +<>, +<>, +<>, +<> + + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_http_res_set_version.adoc b/docs/nng_http_res_set_version.adoc new file mode 100644 index 00000000..14ed046d --- /dev/null +++ b/docs/nng_http_res_set_version.adoc @@ -0,0 +1,64 @@ += nng_http_res_set_version(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. \ + Copyright 2018 Capitar IT Group BV \ + This software 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 + +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: No validation of the version supplied is performed. + +NOTE: The library does not contain support for versions of HTTP other than +"HTTP/1.0" and "HTTP/1.1". Specifying any other version may result in +unspecified behavior. + + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient memory to perform the operation. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +<>, +<>, +<> + + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. -- cgit v1.2.3-70-g09d2