diff options
| -rw-r--r-- | docs/libnng.adoc | 4 | ||||
| -rw-r--r-- | docs/nng_aio_set_input.adoc | 2 | ||||
| -rw-r--r-- | docs/nng_aio_set_output.adoc | 62 | ||||
| -rw-r--r-- | docs/nng_http_handler_alloc.adoc | 12 | ||||
| -rw-r--r-- | docs/nng_http_handler_free.adoc | 50 | ||||
| -rw-r--r-- | docs/nng_http_handler_get_data.adoc | 49 | ||||
| -rw-r--r-- | docs/nng_http_handler_set_data.adoc | 55 | ||||
| -rw-r--r-- | docs/nng_http_handler_set_host.adoc | 59 | ||||
| -rw-r--r-- | docs/nng_http_handler_set_method.adoc | 61 | ||||
| -rw-r--r-- | docs/nng_http_handler_set_tree.adoc | 52 | ||||
| -rw-r--r-- | docs/nng_http_hijack.adoc | 66 | ||||
| -rw-r--r-- | docs/nng_http_server_add_handler.adoc | 61 | ||||
| -rw-r--r-- | docs/nng_http_server_del_handler.adoc | 52 | ||||
| -rw-r--r-- | docs/nng_http_server_get_tls.adoc | 54 | ||||
| -rw-r--r-- | docs/nng_http_server_hold.adoc | 66 | ||||
| -rw-r--r-- | docs/nng_http_server_release.adoc | 57 | ||||
| -rw-r--r-- | docs/nng_http_server_set_tls.adoc | 64 | ||||
| -rw-r--r-- | docs/nng_http_server_start.adoc | 54 | ||||
| -rw-r--r-- | docs/nng_http_server_stop.adoc | 48 |
19 files changed, 923 insertions, 5 deletions
diff --git a/docs/libnng.adoc b/docs/libnng.adoc index 6ecf406b..3612b658 100644 --- a/docs/libnng.adoc +++ b/docs/libnng.adoc @@ -120,6 +120,7 @@ The following functions are used in the asynchronous model: |<<nng_aio_alloc#,nng_aio_alloc(3)>>|allocate asynchronous I/O handle |<<nng_aio_cancel#,nng_aio_cancel(3)>>|cancel asynchronous I/O operation |<<nng_aio_count#,nng_aio_count(3)>>|return number of bytes transferred +|<<nng_aio_finish#,nng_aio_finish(3)>>|finish an asynchronous I/O operation |<<nng_aio_free#,nng_aio_free(3)>>|free asynchronous I/O handle |<<nng_aio_get_input#,nng_aio_get_input(3)>>|return input parameter |<<nng_aio_get_msg#,nng_aio_get_msg(3)>>|get message from an asynchronous receive @@ -128,6 +129,7 @@ The following functions are used in the asynchronous model: |<<nng_aio_set_input#,nng_aio_set_input(3)>>|set input parameter |<<nng_aio_set_iov#,nng_aio_set_iov(3)>>|set scatter/gather vector |<<nng_aio_set_msg#,nng_aio_set_msg(3)>>|set message for an asynchronous send +|<<nng_aio_set_output#,nng_aio_set_output(3)>>|set output result |<<nng_aio_set_timeout#,nng_aio_set_timeout(3)>>|set asynchronous I/O timeout |<<nng_aio_stop#,nng_aio_stop(3)>>|stop asynchronous I/O operation |<<nng_aio_wait#,nng_aio_wait(3)>>|wait for asynchronous I/O operation @@ -252,7 +254,7 @@ These functions are intended for use with HTTP server applications. | <<nng_http_handler_get_data#,nng_http_handler_get_data(3)>>|return extra data for HTTP handler | <<nng_http_handler_set_data#,nng_http_handler_set_data(3)>>|set extra data for HTTP handler | <<nng_http_handler_set_host#,nng_http_handler_set_host(3)>>|set host for HTTP handler -| <<nng_http_handler_set_method#,nng_http_handler_set_method(3)>>|set method for HTTP handler +| <<nng_http_handler_set_method#,nng_http_handler_set_method(3)>>|set HTTP handler method | <<nng_http_handler_set_tree#,nng_http_handler_set_tree(3)>>|set HTTP handler to match trees | <<nng_http_hijack#,nng_http_hijack(3)>>|hijack HTTP server connection | <<nng_http_server_add_handler#,nng_http_server_add_handler(3)>>|add HTTP server handler diff --git a/docs/nng_aio_set_input.adoc b/docs/nng_aio_set_input.adoc index 6e0abefe..a6ffa4a7 100644 --- a/docs/nng_aio_set_input.adoc +++ b/docs/nng_aio_set_input.adoc @@ -37,7 +37,7 @@ increase in the future.) NOTE: If the _index_ does not correspond to a defined input for the operation, then this function will have no effect. Note that attempts to set -parameters with an index greater than three (3) will simply be ignored. +parameters with an _index_ greater than three (3) will simply be ignored. CAUTION: It is an error to call this function while the _aio_ is currently in use by an active asynchronous operation. diff --git a/docs/nng_aio_set_output.adoc b/docs/nng_aio_set_output.adoc new file mode 100644 index 00000000..0c0c6cb9 --- /dev/null +++ b/docs/nng_aio_set_output.adoc @@ -0,0 +1,62 @@ += nng_aio_set_output(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + \ + Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + \ + {blank} + \ + This document is supplied under the terms of the \ + https://opensource.org/licenses/MIT[MIT License]. + +== NAME + +nng_aio_set_output - set output result + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +void nng_aio_set_output(nng_aio *aio, unsigned int index, void *result); +----------- + +== DESCRIPTION + +The `nng_aio_set_output()` function sets the output result at _index_ +to _result_ for the asynchronous operation associated with _aio_. + +The type and semantics of output results are determined by specific +operations; the operation must supply appropriate output results when +the operation completes successfully. + +The valid values of _index_ range from zero (0) to three (3), as no operation +currently defined can return more than four results. (This limit could +increase in the future.) + +NOTE: Note that attempts to set results with an _index_ greater than +three (3) will be ignored. + +An output result set with this function may be retrieved later with +the <<nng_aio_get_output#,nng_aio_get_output(3)>> function. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_aio_alloc#,nng_aio_alloc(3)>>, +<<nng_aio_finish#,nng_aio_finish(3)>>, +<<nng_aio_get_output#,nng_aio_get_output(3)>>, +<<nng_aio_result#,nng_aio_result(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +{copyright} diff --git a/docs/nng_http_handler_alloc.adoc b/docs/nng_http_handler_alloc.adoc index cde5b052..45ba7aff 100644 --- a/docs/nng_http_handler_alloc.adoc +++ b/docs/nng_http_handler_alloc.adoc @@ -41,7 +41,13 @@ by _hp_. Every handler has a Request-URI to which it refers, which is determined by the _path_ argument. Only the path component of the Request URI is -considered. +considered when determining whether the handler should be called. + +Additionally each handler has a method it is registered to handle +(the default is "GET", see +<<nng_http_handler_set_method#,nng_http_handler_set_method(3)), and +optionally a 'Host' header it can be matched against (see +<<nng_http_handler_set_host#,nng_http_handler_set_host(3)). In some cases, a handler may reference a logical tree rather (directory) rather than just a single element. @@ -113,9 +119,9 @@ This function returns 0 on success, and non-zero otherwise. == ERRORS -`NNG_ENOMEM`:: Insufficient free memory exists to allocate a message. -`NNG_ENOTSUP`:: HTTP support not configured. `NNG_EINVAL`:: An invalid _path_ was specified. +`NNG_ENOMEM`:: Insufficient free memory exists to allocate a message. +`NNG_ENOTSUP`:: No support for HTTP in the library. == SEE ALSO diff --git a/docs/nng_http_handler_free.adoc b/docs/nng_http_handler_free.adoc new file mode 100644 index 00000000..e86f34f3 --- /dev/null +++ b/docs/nng_http_handler_free.adoc @@ -0,0 +1,50 @@ += nng_http_handler_free(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + \ + Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + \ + {blank} + \ + This document is supplied under the terms of the \ + https://opensource.org/licenses/MIT[MIT License]. + +== NAME + +nng_http_handler_free - free HTTP server handler + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +void nng_http_handler_free(nng_http_handler *h); +----------- + + +== DESCRIPTION + +The `nng_http_handler_free()` function frees an allocated HTTP server handler. + +CAUTION: It is an error to free a handler that is registered with a server. +Any handlers that are registered with servers are automatically freed +when the server itself is deallocated. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_http_handler_alloc#,nng_http_handler_alloc(3)>>, +<<nng_http_server_add_handler#,nng_http_server_add_handler(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +{copyright} diff --git a/docs/nng_http_handler_get_data.adoc b/docs/nng_http_handler_get_data.adoc new file mode 100644 index 00000000..76437f64 --- /dev/null +++ b/docs/nng_http_handler_get_data.adoc @@ -0,0 +1,49 @@ += nng_http_handler_get_data(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + \ + Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + \ + {blank} + \ + This document is supplied under the terms of the \ + https://opensource.org/licenses/MIT[MIT License]. + +== NAME + +nng_http_handler_get_data - return extra data for HTTP handler + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_http_handler_get_data(nng_http_handler *handler, void *data, + void (*dtor)(void *)); +----------- + +== DESCRIPTION + +The `nng_http_handler_get_data()` function returns the data previously +stored on _handler_ using the function +<<nng_http_handler_set_data#,nng_http_handler_set_data(3)>>. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_http_handler_alloc#,nng_http_handler_alloc(3)>>, +<<nng_http_handler_set_data#,nng_http_server_set_data(3)>>, +<<nng_http_server_add_handler#,nng_http_server_add_handler(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +{copyright} diff --git a/docs/nng_http_handler_set_data.adoc b/docs/nng_http_handler_set_data.adoc new file mode 100644 index 00000000..6daac924 --- /dev/null +++ b/docs/nng_http_handler_set_data.adoc @@ -0,0 +1,55 @@ += nng_http_handler_set_data(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + \ + Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + \ + {blank} + \ + This document is supplied under the terms of the \ + https://opensource.org/licenses/MIT[MIT License]. + +== NAME + +nng_http_handler_get_data - set extra data for HTTP handler + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +void *nng_http_handler_get_data(nng_http_handler *handler, void *data, + void (*dtor)(void *)); +----------- + +== DESCRIPTION + +The `nng_http_handler_set_data()` function is used to set an additional +_data_ for the _handler_. The stored _data_ can be retrieved later +in the handler function using +<<nng_http_handler_get_data#,nng_http_handler_get_data(3)>>. + +Additionally, when the handler is deallocated, if _dtor_ is not `NULL`, +then it will be called with _data_ as its argument. The intended use of +this function is deallocate any resources associated with _data_. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +<<nng_http_handler_alloc#,nng_http_handler_alloc(3)>>, +<<nng_http_handler_get_data#,nng_http_server_get_data(3)>>, +<<nng_http_server_add_handler#,nng_http_server_add_handler(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +{copyright} diff --git a/docs/nng_http_handler_set_host.adoc b/docs/nng_http_handler_set_host.adoc new file mode 100644 index 00000000..470cbead --- /dev/null +++ b/docs/nng_http_handler_set_host.adoc @@ -0,0 +1,59 @@ += nng_http_handler_set_host(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + \ + Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + \ + {blank} + \ + This document is supplied under the terms of the \ + https://opensource.org/licenses/MIT[MIT License]. + +== NAME + +nng_http_handler_set_host - set host for HTTP handler + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_http_handler_set_host(nng_http_handler *handler, const char *host); +----------- + +== DESCRIPTION + +The `nng_http_handler_set_host()` function is used to limit the scope of the +_handler_ so that it will only be called when the specified _host_ matches +the value of the `Host:` HTTP header. + +TIP: This can be used to create servers with multiple handlers for virtual +hosting. + +The value of the _host_ can include a colon and port, and should match +exactly the value of the `Host` header sent by the client. (Canonicaliztion +of the host name is performed though.) + +TIP: As the server framework does not support listening on multiple +ports, the port number can be elided. The matching test only considers +the hostname or IP address, and ignores any trailing port number. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +<<nng_http_handler_alloc#,nng_http_handler_alloc(3)>>, +<<nng_http_server_add_handler#,nng_http_server_add_handler(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +{copyright} diff --git a/docs/nng_http_handler_set_method.adoc b/docs/nng_http_handler_set_method.adoc new file mode 100644 index 00000000..a993868e --- /dev/null +++ b/docs/nng_http_handler_set_method.adoc @@ -0,0 +1,61 @@ += nng_http_handler_set_method(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + \ + Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + \ + {blank} + \ + This document is supplied under the terms of the \ + https://opensource.org/licenses/MIT[MIT License]. + +== NAME + +nng_http_handler_set_method - set HTTP handler method + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_http_handler_set_method(nng_http_handler *handler, const char *method); +----------- + +== DESCRIPTION + +The `nng_http_handler_set_method()` function sets the _method_ that the +_handler_ will be called for, such as "GET" or "POST". (By default the +"GET" method is handled.) If _method_ is `NULL`, then the request method +is not examined, and the handler will be executed regardless of the +method. + +NOTE: The server will automatically call "GET" handlers if the client +sends a "HEAD" request, and will suppress HTTP body data in the responses +sent for such requests. + +NOTE: No validation of the _method_ is performed, but HTTP specifications +insist that the actual method sent over the wire be capitalized. + +The handler may always examine the actual method used using the +<<nng_http_req_get_method#,nng_http_req_get_method(3)>> function. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +<<nng_http_handler_alloc#,nng_http_handler_alloc(3)>>, +<<nng_http_server_add_handler#,nng_http_server_add_handler(3)>>, +<<nng_http_req_get_method#,nng_http_req_get_method(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +{copyright} diff --git a/docs/nng_http_handler_set_tree.adoc b/docs/nng_http_handler_set_tree.adoc new file mode 100644 index 00000000..45b998bc --- /dev/null +++ b/docs/nng_http_handler_set_tree.adoc @@ -0,0 +1,52 @@ += nng_http_handler_set_tree(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + \ + Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + \ + {blank} + \ + This document is supplied under the terms of the \ + https://opensource.org/licenses/MIT[MIT License]. + +== NAME + +nng_http_handler_set_tree - set HTTP handler to match trees + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_http_handler_set_tree(nng_http_handler *handler); +----------- + +== DESCRIPTION + +The `nng_http_handler_set_tree()` function causes the _handler_ to be +matched if the Request URI sent by the client is a logical child of +the path for _handler_. + +TIP: This method is useful when constructing API handlers where a single +service address (path) supports dynamically generated children. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +<<nng_http_handler_alloc#,nng_http_handler_alloc(3)>>, +<<nng_http_server_add_handler#,nng_http_server_add_handler(3)>>, +<<nng_http_req_get_method#,nng_http_req_get_method(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +{copyright} diff --git a/docs/nng_http_hijack.adoc b/docs/nng_http_hijack.adoc new file mode 100644 index 00000000..39105c1d --- /dev/null +++ b/docs/nng_http_hijack.adoc @@ -0,0 +1,66 @@ += nng_http_hijack(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + \ + Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + \ + {blank} + \ + This document is supplied under the terms of the \ + https://opensource.org/licenses/MIT[MIT License]. + +== NAME + +nng_http_hijack - hijack HTTP server connection + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +void nng_http_hijack(nng_http_conn *conn); +----------- + +== DESCRIPTION + +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 <<nng_http_alloc_handler#,nng_http_alloc_handler(3).) + +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 +<<nng_http_conn_write_res#,nng_http_conn_write_res(3)>>.) + +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 + +`NNG_ECLOSED`:: The connection was closed. +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ENOTSUP`:: HTTP not supported. + +== SEE ALSO + +<<nng_http_alloc_handler#,nng_http_alloc_handler(3)>>, +<<nng_http_conn_write_res#,nng_http_conn_write_res(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +{copyright} diff --git a/docs/nng_http_server_add_handler.adoc b/docs/nng_http_server_add_handler.adoc new file mode 100644 index 00000000..64645fbf --- /dev/null +++ b/docs/nng_http_server_add_handler.adoc @@ -0,0 +1,61 @@ += nng_http_server_add_handler(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + \ + Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + \ + {blank} + \ + This document is supplied under the terms of the \ + https://opensource.org/licenses/MIT[MIT License]. + +== NAME + +nng_http_server_add_handler - add HTTP server handler + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_http_server_add_handler(nng_http_server *s, nng_http_handler *h); +----------- + + +== DESCRIPTION + +The `nng_http_server_add_handler()` adds the handler _h_ to the server +instance _s_. + +If another handler is already added to the server that would conflict +with handler _h_, then the operation will fail with `NNG_EADDRINUSE`. + +If a handler is added to a server, and the server is subsequently +deallocated, the handler and any of its resources will also be deallocated. + +Handlers that are added to a server may be subsequently removed using the +<<nng_http_server_del_handler#,nng_http_server_del_handler(3)>> function. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_EADDRINUSE`:: Handler conflicts with another handler. +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ENOTSUP`:: HTTP not supported. + +== SEE ALSO + + +<<nng_http_handler_alloc#,nng_http_handler_alloc(3)>>, +<<nng_http_server_del_handler#,nng_http_server_del_handler(3)>>, +<<nng_http_server_hold#,nng_http_server_hold(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +{copyright} diff --git a/docs/nng_http_server_del_handler.adoc b/docs/nng_http_server_del_handler.adoc new file mode 100644 index 00000000..e3b628e8 --- /dev/null +++ b/docs/nng_http_server_del_handler.adoc @@ -0,0 +1,52 @@ += nng_http_server_del_handler(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + \ + Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + \ + {blank} + \ + This document is supplied under the terms of the \ + https://opensource.org/licenses/MIT[MIT License]. + +== NAME + +nng_http_server_del_handler - delete HTTP server handler + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_http_server_del_hanlder(nng_http_server *s, nng_http_handler *h); +----------- + + +== DESCRIPTION + +The `nng_http_server_del_handler()` removes the handler _h_ from the server +instance _s_. + +Once a handler has been deleted from a server, it is the responsibility +of the caller to dispose of the handler, or add it to another server instance. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOENT`:: Handler is not registered with server. +`NNG_ENOTSUP`:: HTTP not supported. + +== SEE ALSO + +<<nng_http_handler_free#,nng_http_handler_free(3)>>, +<<nng_http_server_add_handler#,nng_http_server_add_handler(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +{copyright} diff --git a/docs/nng_http_server_get_tls.adoc b/docs/nng_http_server_get_tls.adoc new file mode 100644 index 00000000..4bd41207 --- /dev/null +++ b/docs/nng_http_server_get_tls.adoc @@ -0,0 +1,54 @@ += nng_http_server_get_tls(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + \ + Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + \ + {blank} + \ + This document is supplied under the terms of the \ + https://opensource.org/licenses/MIT[MIT License]. + +== NAME + +nng_http_server_get_tls - get HTTP server TLS configuration + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_http_server_get_tls(nng_http_server *s, nng_tls_config **cfgp); +----------- + + +== DESCRIPTION + +The `nng_http_server_get_tls()` obtains the TLS configuration of server _s_ and +saves a pointer to it in the address referenced by _cfgp_. + +The configuration will be `NULL` if the HTTP server instance is not enabled +to use HTTPS. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ENOTSUP`:: Either HTTP or TLS not supported. + +== SEE ALSO + +<<nng_http_server_hold#,nng_http_server_hold(3)>>, +<<nng_http_server_set_tls#,nng_http_server_set_tls(3)>>, +<<nng_http_server_start#,nng_http_server_start(3)>>, +<<nng_tls_config_alloc#,nng_tls_config_alloc(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +{copyright} diff --git a/docs/nng_http_server_hold.adoc b/docs/nng_http_server_hold.adoc new file mode 100644 index 00000000..17e6397f --- /dev/null +++ b/docs/nng_http_server_hold.adoc @@ -0,0 +1,66 @@ += nng_http_server_hold(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + \ + Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + \ + {blank} + \ + This document is supplied under the terms of the \ + https://opensource.org/licenses/MIT[MIT License]. + +== NAME + +nng_http_server_hold - get and hold HTTP server instance + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_http_server_hold(nng_http_server **serverp, const nng_url *url); +----------- + + +== DESCRIPTION + +The `nng_http_server_hold()` acquires an instance of an HTTP server suitable +for use in serving the URL identified by _url_, and stores a pointer to it +at the location pointed to by _serverp_. + +This function first looks to see if an existing HTTP server instance exists, +that is suitable for this. If so, it increments the reference count on it +and uses that. Otherwise, it will attempt to create a new server instance +with an initial reference count of one (1). + +The server instance is not started, and can have additional configuration +applied to it before it is later started with +<<nng_http_server_start#,nng_http_server_start(3)>>. + +NOTE: The URL matching logic in determining servers is unable to distinguish +between different aliases for the same local IP address. This may create +problems when using URLs for virtual hosting. It is recommended to use +canonical IP addresses or names in the _url_ to avoid confusion. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ENOTSUP`:: HTTP not supported. + +== SEE ALSO + +<<nng_http_server_add_handler#,nng_http_server_add_handler(3)>>, +<<nng_http_server_release#,nng_http_server_release(3)>>, +<<nng_http_server_stop#,nng_http_server_stop(3)>>, +<<nng_url_parse#,nng_url_parse(3)>> +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +{copyright} diff --git a/docs/nng_http_server_release.adoc b/docs/nng_http_server_release.adoc new file mode 100644 index 00000000..7e293981 --- /dev/null +++ b/docs/nng_http_server_release.adoc @@ -0,0 +1,57 @@ += nng_http_server_release(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + \ + Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + \ + {blank} + \ + This document is supplied under the terms of the \ + https://opensource.org/licenses/MIT[MIT License]. + +== NAME + +nng_http_server_release - release HTTP server instance + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +void nng_http_server_release(nng_http_server *server); +----------- + + +== DESCRIPTION + +The `nng_http_server_release()` releases an instance of an HTTP _server_ +that was previously held with +<<nng_http_server_hold#,nng_http_server_hold(3)>>. + +This effectively drops the reference count on the server instance. When +the reference count drops to zero, then the _server_ and all resources +associated with it (e.g. HTTP handlers, connections, etc.) are deallocated. +(If the server is "running" when this occurs, then the server is stopped.) + +WARNING: It is an error to release an instance of a server that has +not previously been held, or to attempt to release an instance more +times than it has been held. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_http_server_hold#,nng_http_server_hold(3)>>, +<<nng_http_server_stop#,nng_http_server_stop(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +{copyright} diff --git a/docs/nng_http_server_set_tls.adoc b/docs/nng_http_server_set_tls.adoc new file mode 100644 index 00000000..5dda35ed --- /dev/null +++ b/docs/nng_http_server_set_tls.adoc @@ -0,0 +1,64 @@ += nng_http_server_set_tls(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + \ + Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + \ + {blank} + \ + This document is supplied under the terms of the \ + https://opensource.org/licenses/MIT[MIT License]. + +== NAME + +nng_http_server_set_tls - set HTTP server TLS configuration + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_http_server_set_tls(nng_http_server *s, nng_tls_config *cfg); +----------- + + +== DESCRIPTION + +The `nng_http_server_set_tls()` sets the TLS configuration of server _s_ to +instance _s_. + +This change overwrites any previous TLS configuration. + +WARNING: This also invalidates any previously obtained values from +<<nng_http_server_get_tls#,nng_http_server_get_tls(3)>>. + +If the server is already running (i.e. it has been started with +<<nng_http_server_start#,nng_http_server_start(3)>>) then this will +fail with `NNG_EBUSY`. + +TIP: Generally, the _cfg_ must have a configured private key, set with +<<nng_tls_config_own_cert#,nng_tls_config_own_cert(3)>> or similar. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_EBUSY`:: Server instance is running. +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ENOTSUP`:: Either HTTP or TLS not supported. + +== SEE ALSO + +<<nng_http_server_get_tls#,nng_http_server_get_tls(3)>>, +<<nng_http_server_hold#,nng_http_server_hold(3)>>, +<<nng_http_server_start#,nng_http_server_start(3)>>, +<<nng_tls_config_alloc#,nng_tls_config_alloc(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +{copyright} diff --git a/docs/nng_http_server_start.adoc b/docs/nng_http_server_start.adoc new file mode 100644 index 00000000..7de4cb40 --- /dev/null +++ b/docs/nng_http_server_start.adoc @@ -0,0 +1,54 @@ += nng_http_server_start(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + \ + Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + \ + {blank} + \ + This document is supplied under the terms of the \ + https://opensource.org/licenses/MIT[MIT License]. + +== NAME + +nng_http_server_start - start HTTP server + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_http_server_start(nng_http_server *server); +----------- + + +== DESCRIPTION + +The `nng_http_server_start()` starts the HTTP server instance _server_. +This causes it to bind to the appropriate TCP port, and start accepting +connections and handling HTTP requests. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_EADDRINUSE`:: The TCP port is unavaialble. +`NNG_EADDRINVAL`:: The server is configured with an invalid address. +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ENOTSUP`:: HTTP not supported. + +== SEE ALSO + +<<nng_http_server_hold#,nng_http_server_hold(3)>>, +<<nng_http_server_release#,nng_http_server_release(3)>>, +<<nng_http_server_stop#,nng_http_server_stop(3)>>, +<<nng_url_parse#,nng_url_parse(3)>> +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +{copyright} diff --git a/docs/nng_http_server_stop.adoc b/docs/nng_http_server_stop.adoc new file mode 100644 index 00000000..f2577b2e --- /dev/null +++ b/docs/nng_http_server_stop.adoc @@ -0,0 +1,48 @@ += nng_http_server_stop(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + \ + Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + \ + {blank} + \ + This document is supplied under the terms of the \ + https://opensource.org/licenses/MIT[MIT License]. + +== NAME + +nng_http_server_stop - stop HTTP server + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +void nng_http_server_stop(nng_http_server *server); +----------- + + +== DESCRIPTION + +The `nng_http_server_stop()` stops the HTTP server instance _server_. +This will cause it to close any underlying TCP sockets, and to terminate +any HTTP connections associated with it. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_http_server_hold#,nng_http_server_hold(3)>>, +<<nng_http_server_start#,nng_http_server_start(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +{copyright} |