From 51bebe0c6f137d293dbb6f1194ad3f6fca5b79e9 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Tue, 6 Feb 2018 16:07:10 -0800 Subject: Document HTTP server API completely. --- docs/libnng.adoc | 4 ++- docs/nng_aio_set_input.adoc | 2 +- docs/nng_aio_set_output.adoc | 62 ++++++++++++++++++++++++++++++++ docs/nng_http_handler_alloc.adoc | 12 +++++-- docs/nng_http_handler_free.adoc | 50 ++++++++++++++++++++++++++ docs/nng_http_handler_get_data.adoc | 49 ++++++++++++++++++++++++++ docs/nng_http_handler_set_data.adoc | 55 +++++++++++++++++++++++++++++ docs/nng_http_handler_set_host.adoc | 59 +++++++++++++++++++++++++++++++ docs/nng_http_handler_set_method.adoc | 61 ++++++++++++++++++++++++++++++++ docs/nng_http_handler_set_tree.adoc | 52 +++++++++++++++++++++++++++ docs/nng_http_hijack.adoc | 66 +++++++++++++++++++++++++++++++++++ docs/nng_http_server_add_handler.adoc | 61 ++++++++++++++++++++++++++++++++ docs/nng_http_server_del_handler.adoc | 52 +++++++++++++++++++++++++++ docs/nng_http_server_get_tls.adoc | 54 ++++++++++++++++++++++++++++ docs/nng_http_server_hold.adoc | 66 +++++++++++++++++++++++++++++++++++ docs/nng_http_server_release.adoc | 57 ++++++++++++++++++++++++++++++ docs/nng_http_server_set_tls.adoc | 64 +++++++++++++++++++++++++++++++++ docs/nng_http_server_start.adoc | 54 ++++++++++++++++++++++++++++ docs/nng_http_server_stop.adoc | 48 +++++++++++++++++++++++++ 19 files changed, 923 insertions(+), 5 deletions(-) create mode 100644 docs/nng_aio_set_output.adoc create mode 100644 docs/nng_http_handler_free.adoc create mode 100644 docs/nng_http_handler_get_data.adoc create mode 100644 docs/nng_http_handler_set_data.adoc create mode 100644 docs/nng_http_handler_set_host.adoc create mode 100644 docs/nng_http_handler_set_method.adoc create mode 100644 docs/nng_http_handler_set_tree.adoc create mode 100644 docs/nng_http_hijack.adoc create mode 100644 docs/nng_http_server_add_handler.adoc create mode 100644 docs/nng_http_server_del_handler.adoc create mode 100644 docs/nng_http_server_get_tls.adoc create mode 100644 docs/nng_http_server_hold.adoc create mode 100644 docs/nng_http_server_release.adoc create mode 100644 docs/nng_http_server_set_tls.adoc create mode 100644 docs/nng_http_server_start.adoc create mode 100644 docs/nng_http_server_stop.adoc 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: |<>|allocate asynchronous I/O handle |<>|cancel asynchronous I/O operation |<>|return number of bytes transferred +|<>|finish an asynchronous I/O operation |<>|free asynchronous I/O handle |<>|return input parameter |<>|get message from an asynchronous receive @@ -128,6 +129,7 @@ The following functions are used in the asynchronous model: |<>|set input parameter |<>|set scatter/gather vector |<>|set message for an asynchronous send +|<>|set output result |<>|set asynchronous I/O timeout |<>|stop asynchronous I/O operation |<>|wait for asynchronous I/O operation @@ -252,7 +254,7 @@ These functions are intended for use with HTTP server applications. | <>|return extra data for HTTP handler | <>|set extra data for HTTP handler | <>|set host for HTTP handler -| <>|set method for HTTP handler +| <>|set HTTP handler method | <>|set HTTP handler to match trees | <>|hijack HTTP server connection | <>|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 + +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 <> function. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +<>, +<>, +<>, +<>, +<> + +== 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 +< + +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 + +<>, +<>, +<> + +== 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 + +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 +<>. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +<>, +<>, +<>, +<> + +== 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 + +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 +<>. + +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 + +<>, +<>, +<>, +<> + +== 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 + +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 + +<>, +<>, +<> + +== 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 + +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 +<> 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 + +<>, +<>, +<>, +<> + +== 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 + +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 + +<>, +<>, +<>, +<> + +== 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 + +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 <>.) + +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 + +<>, +<>, +<>, +<> + +== 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 + +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 +<> 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 + + +<>, +<>, +<>, +<>, +<> + +== 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 + +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 + +<>, +<>, +<>, +<> + +== 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 + +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 + +<>, +<>, +<>, +<>, +<>, +<> + +== 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 + +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 +<>. + +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 + +<>, +<>, +<>, +<> +<>, +<> + +== 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 + +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 +<>. + +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 + +<>, +<>, +<> + +== 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 + +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 +<>. + +If the server is already running (i.e. it has been started with +<>) then this will +fail with `NNG_EBUSY`. + +TIP: Generally, the _cfg_ must have a configured private key, set with +<> 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 + +<>, +<>, +<>, +<>, +<>, +<> + +== 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 + +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 + +<>, +<>, +<>, +<> +<>, +<> + +== 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 + +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 + +<>, +<>, +<> + +== COPYRIGHT + +{copyright} -- cgit v1.2.3-70-g09d2