diff options
Diffstat (limited to 'docs/man')
139 files changed, 9659 insertions, 0 deletions
diff --git a/docs/man/libnng.adoc b/docs/man/libnng.adoc new file mode 100644 index 00000000..72516705 --- /dev/null +++ b/docs/man/libnng.adoc @@ -0,0 +1,313 @@ += libnng(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +libnng - nanomsg next generation library + +== SYNOPSIS + +*cc* [_flags_] _files_ *-lnng* [_libraries_] + +== DESCRIPTION + +The <<nng#,nng(7)>> library provides a common messaging framework +intended to solve common communication problems in distributed applications. + +It provides a C language API. + +=== Common Functions + +The following common functions exist in _libnng_. + +|=== +|<<nng_alloc#,nng_alloc(3)>>|allocate memory +|<<nng_free#,nng_free(3)>>|free memory +|<<nng_strerror#,nng_strerror(3)>>|return an error description +|=== + +=== Socket Functions + +The following functions operate on sockets. + +|=== +|<<nng_close#,nng_close(3)>>|close socket +|<<nng_dial#,nng_dial(3)>>|create and start dialer +|<<nng_getopt#,nng_getopt(3)>>|get socket option +|<<nng_listen#,nng_listen(3)>>|create and start listener +|<<nng_recv#,nng_recv(3)>>|receive data +|<<nng_send#,nng_send(3)>>|send data +|<<nng_setopt#,nng_setopt(3)>>|set socket option +|=== + +=== Connection Management + +The following functions are used with either listeners, or dialers. +Listeners accept incoming connection requets, and dialers make them. + +|=== +|<<nng_dial#,nng_dial(3)>>|create and start dialer +|<<nng_dialer_close#,nng_dialer_close(3)>>|close dialer +|<<nng_dialer_create#,nng_dialer_create(3)>>|create dialer +|<<nng_dialer_getopt#,nng_dialer_getopt(3)>>|get dialer option +|<<nng_dialer_setopt#,nng_dialer_setopt(3)>>|set dialer option +|<<nng_dialer_start#,nng_dialer_start(3)>>|start dialer +|<<nng_listen#,nng_listen(3)>>|create and start listener +|<<nng_listener_close#,nng_listener_close(3)>>|close listener +|<<nng_listener_create#,nng_listener_create(3)>>|create listener +|<<nng_listener_getopt#,nng_listener_getopt(3)>>|get listener option +|<<nng_listener_setopt#,nng_listener_setopt(3)>>|set listener option +|<<nng_listener_start#,nng_listener_start(3)>>|start listener +|=== + +=== Message Handling Functions + +Applications desiring to use the richest part of _libnng_ will want to +use the message API, where a message structure is passed between functions. +This API provides the most power support for zero-copy. + +Messages are divided into a header and body, where the body generally carries +user-payload and the header carries protocol specific header information. +Most applications will only interact with the body. + +|=== +|<<nng_msg_alloc#,nng_msg_alloc(3)>>|allocate a message +|<<nng_msg_append#,nng_msg_append(3)>>|append to message body +|<<nng_msg_body#,nng_msg_body(3)>>|return message body +|<<nng_msg_chop#,nng_msg_chop(3)>>|remove data from end of message body +|<<nng_msg_clear#,nng_msg_clear(3)>>|clear message body +|<<nng_msg_dup#,nng_msg_len(3)>>|duplicate a message +|<<nng_msg_free#,nng_msg_free(3)>>|free a message +|<<nng_msg_insert#,nng_msg_insert(3)>>|prepend to message body +|<<nng_msg_len#,nng_msg_len(3)>>|return the message body length +|<<nng_msg_realloc#,nng_msg_realloc(3)>>|reallocate a message +|<<nng_msg_trim#,nng_msg_trim(3)>>|remove data from start of message body +|<<nng_recv_msg#,nng_recvmsg(3)>>|receive a message +|<<nng_sendmsg#,nng_sendmsg(3)>>|send a message +|=== + +==== Message Header Handling + +TIP: Few applications will need these functions, as message headers are only +used to carry protocol-specific content. However, applications which use raw +mode may need to access the header of messages. + +|=== +|<<nng_msg_header#,nng_msg_header(3)>>|return message header +|<<nng_msg_header_append#,nng_msg_header_append(3)>>|append to message header +|<<nng_msg_header_chop#,nng_msg_header_chop(3)>>|remove data from end of message header +|<<nng_msg_header_clear#,nng_msg_header_clear(3)>>|clear message header +|<<nng_msg_header_insert#,nng_msg_header_insert(3)>>|prepend to message header +|<<nng_msg_header_len#,nng_msg_header_len(3)>>|return the message header length +|<<nng_msg_header_trim#,nng_msg_header_trim(3)>>|remove data from start of message header +|=== + +=== Asynchronous Operations + +Most applications will interact with _nng_ synchronously; that is that +functions such as <<nng_send#,nng_send()>> will block the calling +thread until the operation has completed. + +NOTE: Synchronous operations which send messages may return before the +message has actually been received, or even transmitted. Instead, These +functions return as soon as the message was successfully queued for +delivery. + +Asynchronous operations behave differently. These operations are +initiated by the calling thread, but control returns immediately to +the calling thread. When the operation is subsequently completed (regardless +of whether this was successful or not), then a user supplied function +("callback") is executed. + +A context structure, called an _aio_, is allocated and associated for +each asynchronous operation. Only a single asynchronous operation may +be associated with an _aio_ at any time. + +The following functions are used in the asynchronous model: + +|=== +|<<nng_aio_abort#,nng_aio_abort(3)>>|abort asynchronous I/O operation +|<<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 +|<<nng_aio_get_output#,nng_aio_get_output(3)>>|return output result +|<<nng_aio_result#,nng_aio_result(3)>>|return result of asynchronous operation +|<<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 +|<<nng_recv_aio#,nng_recv_aio(3)>>|receive message asynchronously +|<<nng_send_aio#,nng_send_aio(3)>>|send message asynchronously +|=== + +=== Protocols + +The following functions are used to construct a socket with a specific +protocol: + +|=== +|<<nng_bus#,nng_bus_open(3)>>|open a bus socket +|<<nng_pair#,nng_pair_open(3)>>|open a pair socket +|<<nng_pub#,nng_pub_open(3)>>|open a pub socket +|<<nng_pull#,nng_pull_open(3)>>|open a pull socket +|<<nng_push#,nng_push_open(3)>>|open a push socket +|<<nng_rep#,nng_rep_open(3)>>|open a rep socket +|<<nng_req#,nng_req_open(3)>>|open a req socket +|<<nng_respondent#,nng_respondent_open(3)>>|open a respondent socket +|<<nng_sub#,nng_sub_open(3)>>|open a sub socket +|<<nng_surveyor#,nng_surveyor_open(3)>>|open a surveyor socket +|=== + +=== Transports + +The following functions are used to register a transport for use. + +|=== +| <<nng_inproc#,nng_inproc_register(3)>>|register inproc transport +| <<nng_ipc#,nng_ipc_register(3)>>|register IPC transport +| <<nng_tcp#,nng_tcp_register(3)>>|register TCP transport +| <<nng_tls#,nng_tls_register(3)>>|register TLS transport +| <<nng_ws#,nng_ws_register(3)>>|register WebSocket transport +| <<nng_wss#,nng_wss_register(3)>>|register WebSocket Secure transport +| <<nng_zerotier#,nng_zerotier_register(3)>>|register ZeroTier transport +|=== + +=== URL Object + +Common functionality is supplied for parsing and handling +universal resource locators (URLS). + +|=== +|<<nng_url_clone#,nng_url_clone(3)>>|clone URL structure +|<<nng_url_free#,nng_url_free(3)>>|free URL structure +|<<nng_url_parse#,nng_url_parse(3)>>|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. + +|=== +|<<nng_http_conn_close#,nng_http_conn_close(3)>>|close HTTP connection +|<<nng_http_conn_read#,nng_http_conn_read(3)>>|read from HTTP connection +|<<nng_http_conn_read_all#,nng_http_conn_read_all(3)>>|read all from HTTP connection +|<<nng_http_conn_read_req#,nng_http_conn_read_req(3)>>|read HTTP request +|<<nng_http_conn_read_res#,nng_http_conn_read_req(3)>>|read HTTP response +|<<nng_http_conn_write#,nng_http_conn_write(3)>>|write to HTTP connection +|<<nng_http_conn_write_all#,nng_http_conn_write_all(3)>>|write all to HTTP connection +|<<nng_http_conn_write_req#,nng_http_conn_write(3)>>|write HTTP request +|<<nng_http_conn_write_res#,nng_http_conn_write(3)>>|write HTTP response +|<<nng_http_req_add_header#,nng_http_req_add_header(3)>>|add HTTP request header +|<<nng_http_req_alloc#,nng_http_req_alloc(3)>>|allocate HTTP request structure +|<<nng_http_req_copy_data#,nng_http_req_copy_data(3)>>|copy HTTP request body +|<<nng_http_req_del_header#,nng_http_req_del_header(3)>>|delete HTTP request header +|<<nng_http_req_free#,nng_http_req_free(3)>>|free HTTP request structure +|<<nng_http_req_get_header#,nng_http_req_get_header(3)>>|return HTTP request header +|<<nng_http_req_get_method#,nng_http_req_get_method(3)>>|return HTTP request method +|<<nng_http_req_get_uri#,nng_http_req_get_uri(3)>>|return HTTP request URI +|<<nng_http_req_get_version#,nng_http_req_get_version(3)>>|return HTTP request protocol version +|<<nng_http_req_set_data#,nng_http_req_set_data(3)>>|set HTTP request body +|<<nng_http_req_set_header#,nng_http_req_set_header(3)>>|set HTTP request header +|<<nng_http_req_set_method#,nng_http_req_set_method(3)>>|set HTTP request method +|<<nng_http_req_set_uri#,nng_http_req_set_uri(3)>>|set HTTP request URI +|<<nng_http_req_set_version#,nng_http_req_set_version(3)>>|set HTTP request protocol version +|<<nng_http_res_add_header#,nng_http_res_add_header(3)>>|add HTTP response header +|<<nng_http_res_alloc#,nng_http_res_alloc(3)>>|allocate HTTP response structure +|<<nng_http_res_alloc_error#,nng_http_res_alloc_error(3)>>|allocate HTTP error response +|<<nng_http_res_copy_data#,nng_http_res_copy_data(3)>>|copy HTTP response body +|<<nng_http_res_del_header#,nng_http_res_del_header(3)>>|delete HTTP response header +|<<nng_http_res_free#,nng_http_res_free(3)>>|free HTTP response structure +|<<nng_http_res_set_data#,nng_http_res_set_data(3)>>|set HTTP response body +|<<nng_http_res_get_header#,nng_http_res_get_header(3)>>|return HTTP response header +|<<nng_http_res_get_reason#,nng_http_res_get_reason(3)>>|return HTTP response reason +|<<nng_http_res_get_status#,nng_http_res_get_status(3)>>|return HTTP response status +|<<nng_http_res_get_version#,nng_http_res_get_version(3)>>|return HTTP response protocol version +|<<nng_http_res_set_header#,nng_http_res_set_header(3)>>|set HTTP response header +|<<nng_http_res_set_reason#,nng_http_res_set_reason(3)>>|set HTTP response reason +|<<nng_http_res_set_status#,nng_http_res_set_status(3)>>|set HTTP response status +|<<nng_http_res_set_version#,nng_http_res_set_version(3)>>|set HTTP response protocol version +|=== + +==== HTTP Client Functions + +These functions are intended for use with HTTP client applications. + +|=== +| <<nng_http_client_alloc#,nng_http_client_alloc(3)>>|allocate HTTP client +| <<nng_http_client_connect#,nng_http_client_connect(3)>>|establish HTTP client connection +| <<nng_http_client_free#,nng_http_client_free(3)>>|free HTTP client +| <<nng_http_client_get_tls#,nng_http_client_get_tls(3)>>|get HTTP client TLS configuration +| <<nng_http_client_set_tls#,nng_http_client_set_tls(3)>>|set HTTP client TLS configuration +|=== + +==== HTTP Server Functions + +These functions are intended for use with HTTP server applications. + +|=== +|<<nng_http_handler_alloc#,nng_http_handler_alloc(3)>>|allocate HTTP server handler +|<<nng_http_handler_free#,nng_http_handler_free(3)>>|free HTTP server handler +|<<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 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 +|<<nng_http_server_del_handler#,nng_http_server_del_handler(3)>>|delete HTTP server handler +|<<nng_http_server_get_tls#,nng_http_server_get_tls(3)>>|get HTTP server TLS configuration +|<<nng_http_server_hold#,nng_http_server_get_tls(3)>>|get and hold HTTP server instance +|<<nng_http_server_release#,nng_http_server_get_tls(3)>>|release HTTP server instance +|<<nng_http_server_set_tls#,nng_http_server_set_tls(3)>>|set HTTP server TLS configuration +|<<nng_http_server_start#,nng_http_server_start(3)>>|start HTTP server +|<<nng_http_server_stop#,nng_http_server_stop(3)>>|stop HTTP server +|=== + +=== TLS Configuration Objects + +The following functions are used to manipulate transport layer security +(TLS) configuration objects. + +NOTE: These functions will only be present if the library has been built +with TLS support. + +|=== +|<<nng_tls_config_auth_alloc#,nng_tls_config_alloc(3)>>|allocate TLS configuration +|<<nng_tls_config_auth_mode#,nng_tls_config_auth_mode(3)>>|set authentication mode +|<<nng_tls_config_ca_chain#,nng_tls_config_ca_chain(3)>>|set certificate authority chain +|<<nng_tls_config_ca_file#,nng_tls_config_ca_file(3)>>|load certificate authority from file +|<<nng_tls_config_cert_key_file#,nng_tls_config_cert_key_file_cert(3)>>|load own certificate and key from file +|<<nng_tls_config_own_cert#,nng_tls_config_own_cert(3)>>|set own certificate and key +|<<nng_tls_config_free#,nng_tls_config_free(3)>>|free TLS configuration +|<<nng_tls_config_server_name#,nng_tls_config_server_name(3)>>|set remote server name +|=== + + +== SEE ALSO + +<<nng#,nng(7)>>, +<<nng_compat#,nng_compat(3)>> diff --git a/docs/man/nng.adoc b/docs/man/nng.adoc new file mode 100644 index 00000000..2d0f6567 --- /dev/null +++ b/docs/man/nng.adoc @@ -0,0 +1,154 @@ += nng(7) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng - nanomsg next generation + +== SYNOPSIS + +*cc* ['flags'] 'files' *-lnng* ['libraries'] + +== DESCRIPTION + +The _nng_ library provides a common messaging framework intended to +solve common communication problems in distributed applications. +It offers a number of _protocols_, and also a number of _transports_. + +The _protocols_ implement the semantics associated with particular +communications scenarios, such as RPC style services, service discovery, +publish/subscribe, and so forth. + +The _transports_ provide support for underlying transport methods, such +as TCP, IPC, websockets, and so forth. + +The _nng_ library is designed to permit easy creation of new _transports_ and, +to a lesser extent, new _protocols_. + +The _nng_ library is wire compatible with the SP protocols described in +the nanomsg project; projects using +https://github.com/nanomsg/nanomsg[_libnanomsg_] can inter-operate with +nng as well as other conforming implementations. (One such implementation +is https://github.com/go-mangos/mangos[_mangos_].) Applications using _nng_ +which wish to communicate with older libraries must ensure that they only +use protocols or transports offered by the earlier library. + +The _nng_ library also offers a compatible API, permitting legacy code to +be recompiled or relinked against _nng_. When doing this, support for +certain enhancements or features will likely be absent, requiring the +application developer to use the new-style API. + +The _nng_ library is implemented in pure C; if you need bindings for +other languages please check the http://nanomsg.org/[website]. + +== Protocols + +* <<nng_bus#,nng_bus(7)>> - Bus protocol +* <<nng_pair#,nng_pair(7)>> - Pair protocol +* <<nng_pub#,nng_pub(7)>> - Publisher side of publish/subscribe protocol +* <<nng_pull#,nng_pull(7)>> - Pull side of pipeline protocol +* <<nng_push#,nng_push(7)>> - Push side of pipeline protocol +* <<nng_sub#,nng_sub(7)>> - Subscriber side of publish/subscribe protocol +* <<nng_rep#,nng_rep(7)>> - Reply side of request/reply protocol +* <<nng_req#,nng_req(7)>> - Request side of request/reply protocol +* <<nng_respondent#,nng_respondent(7)>> - Respondent side of survey protocol +* <<nng_surveyor#,nng_surveyor(7)>> - Surveyor side of survey protocol + +== Transports + +* <<nng_inproc#,nng_inproc(7)>> - Intra-process transport +* <<nng_ipc#,nng_ipc(7)>> - Inter-process transport +* <<nng_tls#,nng_tls(7)>> - TLSv1.2 over TCP transport +* <<nng_tcp#,nng_tcp(7)>> - TCP (and TCPv6) transport +* <<nng_ws#,nng_ws(7)>> - WebSocket transport +* <<nng_zerotier#,nng_zerotier(7)>> - ZeroTier transport + +== Conceptual Overview + +_nng_ presents a _socket_ view of networking. The sockets are constructed +using protocol-specific functions, as a given socket implements precisely +one _nng_ protocol. + +Each socket can be used to send and receive messages (if the protocol) +supports it, and implements the appropriate protocol semantics. For +example, <<nng_sub#,nng_sub(7)>> sockets automatically filter incoming +messages to discard those for topics that have not been subscribed. + +_nng_ sockets are message oriented, so that messages are either delivered +wholly, or not at all. Partial delivery is not possible. Furthermore, +_nng_ does not provide any other delivery or ordering guarantees; +messages may be dropped or reordered. (Some protocols, such as +<<nng_req#,nng_req(7)>> may offer stronger guarantees by +performing their own retry and validation schemes.) + +Each socket can have zero, one, or many "endpoints", which are either +_listeners_ or _dialers_. (A given socket may freely choose whether it uses +listeners, dialers, or both.) These "endpoints" provide access to +underlying transports, such as TCP, etc. + +Each endpoint is associated with a URL, which is a service address. For +dialers, this will be the service address that will be contacted, whereas +for listeners this is where the listener will bind and watch for new +connections. + +Endpoints do not themselves transport data. They are instead responsible +for the creation of _pipes_, which can be thought of as message-oriented, +connected, streams. Pipes frequently correspond to a single underlying +byte stream -- for example both IPC and TCP transports implement their +pipes using a 1:1 relationship with a connected socket. + +Endpoints create pipes as needed. Listeners will create them when a new +client connection request arrives, and dialers will generally create one, +then wait for it to disconnect before reconnecting. + +Most applications should not have to worry about endpoints or pipes at +all; the socket abstraction should provide all the functionality needed +other than in a few specific circumstances. + +=== URLs + +The _nng_ library uses universal resource locators (URLs) +following the format specified in +https://tools.ietf.org/html/rfc3986[RFC 3986], +including some schemes that are unique +to SP. +The URLs used in _nng_ are canonicalized as follows, mostly in +accordance with +https://tools.ietf.org/html/rfc3986#section-6.2.2[RFC 3986 6.2.2]: + + . The URL is parsed into scheme, userinfo, host, port, path, query and + fragment components. (Not all of these members are necessarily present.) + . The scheme, hostname, and port if present, are converted to lower case. + . Percent-encoded values for + https://tools.ietf.org/html/rfc3986#section-2.3[unreserved characters] + converted to their unencoded forms. + . Additionally URL percent-encoded values for characters in the path + and with numeric values larger than 127 (i.e. not ASCII) are decoded. + . The resulting path is checked for invalid UTF-8 sequences, consisting + of surrogate pairs, illegal byte sequences, or overlong encodings. + If this check fails, then the entire URL is considered invalid. + . Path segments consisting of `.` and `..` are resolved as per + https://tools.ietf.org/html/rfc3986#section-6.2.2.3[RFC 3986 6.2.2.3]. + . Further, empty path segments are removed, meaning that duplicate + slash (`/`) separators are removed from the path. + +Note that steps 4, 5, and 7 are not specified by RFC 3986, but performing +them is believed to improve both the usability and security of _nng_ +applications, without violating RFC 3986 itself. + +== API + +The library API is documented at <<libnng#,libnng(3)>>. + +== SEE ALSO + +<<libnng#,libnng(3)>>, +<<nng_compat#,nng_compat(3)>> diff --git a/docs/man/nng_aio_abort.adoc b/docs/man/nng_aio_abort.adoc new file mode 100644 index 00000000..51e1533d --- /dev/null +++ b/docs/man/nng_aio_abort.adoc @@ -0,0 +1,52 @@ += nng_aio_abort(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_aio_abort - abort asynchronous I/O operation + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +void nng_aio_abort(nng_aio *aio, int err); +----------- + +== DESCRIPTION + +The `nng_aio_abort()` function aborts an operation previously started +with the handle _aio_. If the operation is aborted, then the callback +for the handle will be called, and the function +<<nng_aio_result#,nng_aio_result(3)>> will return the error _err_. + +This function does not wait for the operation to be fully aborted, but +returns immediately. + +If no operation is currently in progress (either because it has already +finished, or no operation has been started yet), then this function +has no effect. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_aio_alloc#,nng_aio_alloc(3)>>, +<<nng_aio_cancel#,nng_aio_cancel(3)>>, +<<nng_aio_result#,nng_aio_result(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_aio_alloc.adoc b/docs/man/nng_aio_alloc.adoc new file mode 100644 index 00000000..57054e04 --- /dev/null +++ b/docs/man/nng_aio_alloc.adoc @@ -0,0 +1,73 @@ += nng_aio_alloc(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_aio_alloc - allocate asynchronous I/O handle + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_aio_alloc(nng_aio **aiop, void (*callb)(void *), void *arg); +----------- + +== DESCRIPTION + +The `nng_aio_alloc()` function allocates a handle for asynchronous I/O +operations, and stores a pointer to it in __aiop__. The handle is initialized +with a completion callback of _callb_, which will be executed when an +associated asynchronous operation finishes. It will be called with the +argument _arg_. + +Asynchronous I/O operations all take an "aio" handle such as allocated by +this function. Such operations are usually started by a function that returns +immediately. The operation is then run asynchronously, and completes sometime +later. When that operation is complete, the callback supplied here is called, +and that callback is able to determine the result of the operation using +<<nng_aio_result#,nng_aio_result(3)>>, <<nng_aio_count#,nng_aio_count(3)>>, +and <<nng_aio_get_output#,nng_aio_get_output(3)>>. + +It is possible to wait synchronously for an otherwise asynchronous operation +by using the function <<nng_aio_wait#,nng_aio_wait(3)>>. In that case, +it is permissible for _callb_ and _arg_ to both be `NULL`. Note that if +these are `NULL`, then it will not be possible to determine when the +operation is complete except by calling the aforementioned +<<nng_aio_wait#,nng_aio_wait(3)>>. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. + +== SEE ALSO + +<<nng_aio_abort#,nng_aio_abort(3)>>, +<<nng_aio_cancel#,nng_aio_cancel(3)>>, +<<nng_aio_count#,nng_aio_count(3)>>, +<<nng_aio_free#,nng_aio_free(3)>>, +<<nng_aio_get_input#,nng_aio_get_input(3)>>, +<<nng_aio_get_msg#,nng_aio_get_msg(3)>>, +<<nng_aio_get_output#,nng_aio_get_output(3)>>, +<<nng_aio_result#,nng_aio_result(3)>>, +<<nng_aio_set_input#,nng_aio_set_input(3)>>, +<<nng_aio_set_iov#,nng_aio_set_iov(3)>>, +<<nng_aio_set_msg#,nng_aio_set_msg(3)>>, +<<nng_aio_set_timeout#,nng_aio_set_timeout(3)>>, +<<nng_aio_stop#,nng_aio_stop(3)>>, +<<nng_aio_wait#,nng_aio_wait(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_aio_cancel.adoc b/docs/man/nng_aio_cancel.adoc new file mode 100644 index 00000000..22ef0166 --- /dev/null +++ b/docs/man/nng_aio_cancel.adoc @@ -0,0 +1,55 @@ += nng_aio_cancel(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_aio_cancel - cancel asynchronous I/O operation + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +void nng_aio_cancel(nng_aio *aio); +----------- + +== DESCRIPTION + +The `nng_aio_cancel()` function aborts an operation previously started +with the handle _aio_. If the operation is aborted, then the callback +for the handle will be called, and the function +<<nng_aio_result#,nng_aio_result(3)>> will return the error `NNG_ECANCELED`. + +This function does not wait for the operation to be fully aborted, but +returns immediately. + +If no operation is currently in progress (either because it has already +finished, or no operation has been started yet), then this function +has no effect. + +NOTE: This function is the same as calling <<nng_aio_abort#,nng_aio_abort()>> +with the error `NNG_ECANCELED`. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_aio_abort#,nng_aio_abort(3)>>, +<<nng_aio_alloc#,nng_aio_alloc(3)>>, +<<nng_aio_result#,nng_aio_result(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_aio_count.adoc b/docs/man/nng_aio_count.adoc new file mode 100644 index 00000000..6ea42bf9 --- /dev/null +++ b/docs/man/nng_aio_count.adoc @@ -0,0 +1,58 @@ += nng_aio_count(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_aio_count - return number of bytes transferred + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +size_t nng_aio_count(nng_aio *aio); +----------- + +== DESCRIPTION + +The `nng_aio_count()` returns the number of bytes transferred by the +asynchronous operation associated with the handle _aio_. + +Some asynchronous operations do not provide meaningful data for this +function; for example operations that establish connections do not +transfer user data (they may transfer protocol data though) -- in this case +this function will generally return zero. + +This function is most useful when used with operations that make use of +of a scatter/gather vector (set by <<nng_aio_set_iov#,nng_aio_set_iov(3)>>). + +NOTE: The return value from this function is undefined if the operation +has not completed yet. Either call this from the handle's completion +callback, or after waiting for the operation to complete with +<<nng_aio_wait#,nng_aio_wait(3)>>. + +== RETURN VALUES + +The number of bytes transferred by the operation. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_aio_alloc#,nng_aio_alloc(3)>>, +<<nng_aio_result#,nng_aio_result(3)>>, +<<nng_aio_set_iov#,nng_aio_set_iov(3)>>, +<<nng_aio_wait#,nng_aio_wait(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_aio_finish.adoc b/docs/man/nng_aio_finish.adoc new file mode 100644 index 00000000..42c51970 --- /dev/null +++ b/docs/man/nng_aio_finish.adoc @@ -0,0 +1,54 @@ += nng_aio_finish(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_aio_finish - finish asynchronous I/O operation + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +void nng_aio_finish(nng_aio *aio, int err); +----------- + +== DESCRIPTION + +The `nng_aio_finish()` function marks operation associated with _aio_ as +complete, with the status _err_. This will be the result returned by +<<nng_aio_result#,nng_aio_result(3)>>. + +This function causes the callback associated with the _aio_ to called. + +WARNING: It is mandatory that operation "providers" call this function +*EXACTLY ONCE* when they are finished with the operation. After calling this +function they *MUST NOT* perform any further accesses the _aio_. + +WARNING: This function is only for I/O providers (those actually performing +the operation such as HTTP handler function or a transport provider); ordinary +users of the _aio_ should not have any need for this function. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_aio_alloc#,nng_aio_alloc(3)>>, +<<nng_aio_cancel#,nng_aio_cancel(3)>>, +<<nng_aio_result#,nng_aio_result(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_aio_free.adoc b/docs/man/nng_aio_free.adoc new file mode 100644 index 00000000..20ece8ae --- /dev/null +++ b/docs/man/nng_aio_free.adoc @@ -0,0 +1,45 @@ += nng_aio_free(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_aio_free - free asynchronous I/O handle + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +void nng_aio_free(nng_aio *aio); +----------- + +== DESCRIPTION + +The `nng_aio_free()` function frees an allocated asynchronous I/O handle. +If any operation is in progress, the operation is canceled, and the +caller is blocked until the operation is completely canceled, to ensure +that it is safe to deallocate the handle and any associated resources. +(This is done by implicitly calling <<nng_aio_stop#,nng_aio_stop(3)>>.) + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_aio_alloc#,nng_aio_alloc(3)>>, +<<nng_aio_stop#,nng_aio_stop(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_aio_get_input.adoc b/docs/man/nng_aio_get_input.adoc new file mode 100644 index 00000000..73b0acd2 --- /dev/null +++ b/docs/man/nng_aio_get_input.adoc @@ -0,0 +1,50 @@ += nng_aio_get_input(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_aio_set_input - return input parameter + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +void *nng_aio_get_input(nng_aio *aio, unsigned int index); +----------- + +== DESCRIPTION + +The `nng_aio_get_input()` function returns the value of the input parameter +previously set at _index_ on _aio_ with the +<<nng_aio_set_input#,nng_aio_set_input(3)>> function. + +The valid values of _index_ range from zero (0) to three (3), as no operation +currently defined can accept more than four parameters. (This limit could +increase in the future.) If the index supplied is outside of this range, +or of the input parameter was not previously set, then `NULL` is returned. + +== RETURN VALUES + +Value previously set, or `NULL`. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_aio_alloc#,nng_aio_alloc(3)>>, +<<nng_aio_get_output#,nng_aio_get_output(3)>>, +<<nng_aio_set_input#,nng_aio_set_input(3)>>, +<<nng_aio_result#,nng_aio_result(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_aio_get_output.adoc b/docs/man/nng_aio_get_output.adoc new file mode 100644 index 00000000..a362e0ae --- /dev/null +++ b/docs/man/nng_aio_get_output.adoc @@ -0,0 +1,54 @@ += nng_aio_get_output(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_aio_get_output - return output result + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +void *nng_aio_get_output(nng_aio *aio, unsigned int index); +----------- + +== DESCRIPTION + +The `nng_aio_get_output()` function returns the output result at _index_ +resulting from the asynchronous operation associated with _aio_. + +The type and semantics of output parameters are determined by specific +operations. + +NOTE: If the _index_ does not correspond to a defined output for the operation, +or the operation did not succeed, then the return value will be `NULL`. + +CAUTION: It is an error to call this function while the _aio_ is currently +in use by an active asynchronous operation, or if no operation has been +performed using the _aio_ yet. + +== RETURN VALUES + +The __index__th result of the operation, or `NULL`. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_aio_alloc#,nng_aio_alloc(3)>>, +<<nng_aio_get_output#,nng_aio_get_output(3)>>, +<<nng_aio_set_input#,nng_aio_set_input(3)>>, +<<nng_aio_result#,nng_aio_result(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_aio_result.adoc b/docs/man/nng_aio_result.adoc new file mode 100644 index 00000000..1b55dc0e --- /dev/null +++ b/docs/man/nng_aio_result.adoc @@ -0,0 +1,56 @@ += nng_aio_result(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_aio_result - return result of asynchronous operation + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_aio_wait(nng_aio *aio); +----------- + + +== DESCRIPTION + +The `nng_aio_result()` returns the result of the operation associated +with the handle _aio_. +If the operation was successful, then 0 is returned. Otherwise a non-zero +error code is returned. + +NOTE: The return value from this function is undefined if the operation +has not completed yet. Either call this from the handle's completion +callback, or after waiting for the operation to complete with +<<nng_aio_wait#,nng_aio_wait(3)>>. + +== RETURN VALUES + +The result of the operation, either zero on success, or an error +number on failure. + +== ERRORS + +`NNG_ETIMEDOUT`:: The operation timed out. +`NNG_ECANCELED`:: The operation was canceled. + +Various other return values are possible dependending on the operation. + +== SEE ALSO + +<<nng_aio_abort#,nng_aio_abort(3)>>, +<<nng_aio_alloc#,nng_aio_alloc(3)>>, +<<nng_aio_wait#,nng_aio_wait(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_aio_set_input.adoc b/docs/man/nng_aio_set_input.adoc new file mode 100644 index 00000000..3a240c6a --- /dev/null +++ b/docs/man/nng_aio_set_input.adoc @@ -0,0 +1,62 @@ += nng_aio_set_input(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_aio_set_input - set input parameter + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +void nng_aio_set_input(nng_aio *aio, unsigned int index, void *param); +----------- + +== DESCRIPTION + +The `nng_aio_set_input()` function sets the input parameter at _index_ +to _param_ for the asynchronous operation associated with _aio_. + +The type and semantics of input parameters are determined by specific +operations; the caller must supply appropriate inputs for the operation +to be performed. + +The valid values of _index_ range from zero (0) to three (3), as no operation +currently defined can accept more than four parameters. (This limit could +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. + +CAUTION: It is an error to call this function while the _aio_ is currently +in use by an active asynchronous operation. + +An input parameter set with this function may be retrieved later with +the <<nng_aio_get_input#,nng_aio_get_input(3)>> function. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_aio_alloc#,nng_aio_alloc(3)>>, +<<nng_aio_get_input#,nng_aio_get_input(3)>>, +<<nng_aio_get_output#,nng_aio_get_output(3)>>, +<<nng_aio_result#,nng_aio_result(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_aio_set_iov.adoc b/docs/man/nng_aio_set_iov.adoc new file mode 100644 index 00000000..d5991ed6 --- /dev/null +++ b/docs/man/nng_aio_set_iov.adoc @@ -0,0 +1,71 @@ += nng_aio_set_iov(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_aio_set_iov - set scatter/gather vector + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_aio_set_iov(nng_aio *aio, unsigned int niov, nng_iov *iov); +----------- + +== DESCRIPTION + +The `nng_aio_set_iov()` function sets a scatter/gather vector _iov_ on the +handle _aio_. + +The _iov_ is a pointer to an array of _niov_ `nng_iov` structures, which have +the following definition: + +[source, c] +---- + typedef struct nng_iov { + void * iov_buf; + size_t iov_len; + }; +---- + +The _iov_ is copied into storage in the _aio_ itself, so that callers +may use stack allocated `nng_iov` structures. The values pointed to +by the `iov_buf` members are *not* copied by this function though. + +Up to four `nng_iov` members may be supplied without causing any +allocations, and thus this operation is guaranteed to succeed for +values of _niov_ less than four. + +More than four (4) `nng_iov` members may be supplied, but this may require +heap allocations, and so the operation may fail with `NNG_ENOMEM`. +Additionally, not every operation can support longer vectors; the +actual limit is determined by the system, but is generally at least +sixteen (16). Furthermore, values for _niov_ larger than sixty-four (64) will +generally result in `NNG_EINVAL`. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient free memory to perform operation. +`NNG_EINVAL`:: Value of specified _niov_ is too large. + +== SEE ALSO + +<<nng_aio_alloc#,nng_aio_alloc(3)>>, +<<nng_aio_cancel#,nng_aio_cancel(3)>>, +<<nng_aio_count#,nng_aio_count(3)>>, +<<nng_aio_result#,nng_aio_result(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_aio_set_output.adoc b/docs/man/nng_aio_set_output.adoc new file mode 100644 index 00000000..4c3d4a21 --- /dev/null +++ b/docs/man/nng_aio_set_output.adoc @@ -0,0 +1,58 @@ += nng_aio_set_output(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_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)>> diff --git a/docs/man/nng_aio_set_timeout.adoc b/docs/man/nng_aio_set_timeout.adoc new file mode 100644 index 00000000..ff1244d5 --- /dev/null +++ b/docs/man/nng_aio_set_timeout.adoc @@ -0,0 +1,60 @@ += nng_aio_set_timeout(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_aio_set_timeout - set asynchronous I/O timeout + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +typedef int nng_duration; +void nng_aio_set_timeout(nng_aio *aio, nng_duration timeout); +----------- + +== DESCRIPTION + +The `nng_aio_set_timeout()` function sets a _timeout_ for the asynchronous +operation associated with _aio_. This causes a timer to be started when the operation is actually +started. If the timer expires before the operation is completed, then it is +aborted with an error of `NNG_ETIMEDOUT`. The _timeout_ is specified as a +relative number of milliseconds. + +If the timeout is `NNG_DURATION_INFINITE`, then no timeout is used. +If the timeout is `NNG_DURATION_DEFAULT`, then a "default" or socket-specific +timeout is used. (This is frequently the same as `NNG_DURATION_INFINITE`.) + +TIP: As most operations involve some context switching, it is usually a good +idea to allow at least a few tens of milliseconds before timing them out -- +a too small timeout might not allow the operation to properly begin before +giving up! + +The value of _timeout_ set for the _aio_ is persistent, so that if the +handle is reused for multiple operations, they will have the same relative +timeout. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_aio_alloc#,nng_aio_alloc(3)>>, +<<nng_aio_cancel#,nng_aio_cancel(3)>>, +<<nng_aio_result#,nng_aio_result(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_aio_stop.adoc b/docs/man/nng_aio_stop.adoc new file mode 100644 index 00000000..ae5c5bda --- /dev/null +++ b/docs/man/nng_aio_stop.adoc @@ -0,0 +1,54 @@ += nng_aio_stop(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_aio_stop - stop asynchronous I/O operation + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +void nng_aio_stop(nng_aio *aio); +----------- + +== DESCRIPTION + +The `nng_aio_stop()` function stops the asynchronous I/O operation +associated with _aio_ by aborting with `NNG_ECANCELED`, and then waits +for it to complete or to be completely aborted. + +This is logically the equivalent of <<nng_aio_cancel#,nng_aio_cancel(3)>> +followed by <<nng_aio_wait#,nng_aio_wait(3)>>, except that the asynchronous +I/O handle may not be used for any further operations. + +TIP: When multiple asynchronous I/O handles are in use and need to be +shut down, it is safest to stop all of them, before deallocating any of +this with <<nng_aio_free#,nng_aio_free(3)>>, particularly if the callbacks +might attempt to reschedule additional operations. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_aio_cancel#,nng_aio_cancel(3)>>, +<<nng_aio_free#,nng_aio_free(3)>>, +<<nng_aio_wait#,nng_aio_wait(3)>>, +<<nng_aio_alloc#,nng_aio_alloc(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_aio_wait.adoc b/docs/man/nng_aio_wait.adoc new file mode 100644 index 00000000..fb0dad87 --- /dev/null +++ b/docs/man/nng_aio_wait.adoc @@ -0,0 +1,46 @@ += nng_aio_wait(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_aio_wait - wait for asynchronous I/O operation + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +void nng_aio_wait(nng_aio *aio); +----------- + +== DESCRIPTION + +The `nng_aio_wait()` function waits for an asynchronous I/O operation +to complete. If the operation has not been started, or has already +completed, then it returns immediately. + +If the a callback was set with _aio_ when it was allocated, then this +function will not be called until the callback has completed. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_aio_abort#,nng_aio_abort(3)>>, +<<nng_aio_alloc#,nng_aio_alloc(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_bus.adoc b/docs/man/nng_bus.adoc new file mode 100644 index 00000000..18ba4664 --- /dev/null +++ b/docs/man/nng_bus.adoc @@ -0,0 +1,71 @@ += nng_bus(7) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_bus - bus protocol + +== SYNOPSIS + +[source,c] +---------- +#include <nng/protocol/bus0/bus.h> + +int nng_bus0_open(nng_socket *s); +---------- + +== DESCRIPTION + +The _nng_bus_ protocol provides for building mesh networks where +every peer is connected to every other peer. In this protocol, +each message sent by a node is sent to every one of its directly +connected peers. + +TIP: Messages are only sent to directly connected peers. This means +that in the event that a peer is connected indirectly, it will not +receive messages. When using this protocol to build mesh networks, it +is therefore important that a _fully-connected_ mesh network be +constructed. + +All message delivery in this pattern is best-effort, which means that +peers may not receive messages. Furthermore, delivery may occur to some, +all, or none of the directly connected peers. (Messages are not delivered +when peer nodes are unable to receive.) Hence, send operations will never +block; instead if the message cannot be delivered for any reason it is +discarded. + +TIP: In order to minimize the likelihood of message loss, this protocol +should not be used for high throughput communications. Furthermore, the +more traffic _in aggregate_ that occurs across the topology, the more +likely that message loss is to occur. + +=== Socket Operations + +The `nng_bus0_open()` call creates a bus socket. This socket +may be used to send and receive messages. Sending messages will +attempt to deliver to each directly connected peer. + +=== Protocol Versions + +Only version 0 of this protocol is supported. (At the time of writing, +no other versions of this protocol have been defined.) + +=== Protocol Options + +The _nng_bus_ protocol has no protocol-specific options. + +=== Protocol Headers + +The _nng_bus_ protocol has no protocol-specific headers. + +== SEE ALSO + +<<nng#,nng(7)>> diff --git a/docs/man/nng_close.adoc b/docs/man/nng_close.adoc new file mode 100644 index 00000000..dfc1b0a6 --- /dev/null +++ b/docs/man/nng_close.adoc @@ -0,0 +1,48 @@ += nng_close(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_close - close socket + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_close(nng_socket s); +----------- + +== DESCRIPTION + +The `nng_close()` function closes the supplied socket, _s_. Messages +that have been submitted for sending may be flushed or delivered, +depending upon the transport and the setting of the `NNG_OPT_LINGER` +option. + +Further attempts to use the socket after this call returns will result +in `NNG_EBADF`. Threads waiting for operations on the socket when this +call is executed may also return with an `NNG_EBADF` result. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_EBADF`:: The socket _s_ is already closed or was never opened. + +== SEE ALSO + +<<nng_setopt#,nng_setopt(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_dial.adoc b/docs/man/nng_dial.adoc new file mode 100644 index 00000000..18d55137 --- /dev/null +++ b/docs/man/nng_dial.adoc @@ -0,0 +1,87 @@ += nng_dial(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_dial - create and start dialer + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_dial(nng_socket s, const char *url, nng_dialer *dp, int flags); +----------- + +== DESCRIPTION + +The `nng_dialer()` function creates a newly initialized +dialer, associated with socket _s_, and configured to listen at the +address specified by _url_. If the value of _dp_ is not `NULL`, then +the newly created dialer is stored at the address indicated by _dp_. + +Dialers initiate a remote connection to a listener. Upon a successful +connection being established, they create a pipe, add it to the socket, +and then wait for that pipe to be closed. When the pipe is closed, +they will re-initiate the connection. Dialer's will also periodically +retry a connection automatically if an attempt to connect asynchronously +fails. + +TIP: While it is convenient to think of dialers as "clients", the relationship +between the listener or dialer is orthogonal to any server or client status +that might be associated with a given protocol. For example, a <<nng_req#,REQ>> +socket might have associated dialers, but might also have associated listeners. +It may even have some of each at the same time! + +Normally, the first attempt to connect to the address indicated by _url_ is done +synchronously, including any necessary name resolution. As a result, +a failure, such as if the connection is refused, will be returned +immediately, and no further action will be taken. + +However, if the special value `NNG_FLAG_NONBLOCK` is +supplied in _flags_, then the connection attempt is made asynchronously. + +Furthermore, if the connection was closed for a synchronously dialed +connection, the dialer will still attempt to redial asynchronously. + +TIP: While `NNG_FLAG_NONBLOCK` can help an application be more resilient, +it also generally makes diagnosing failures somewhat more difficult. + +Because the dialer is started immediately, it is generally not possible +to apply extra configuration; if that is needed applications should consider +using <<nng_dialer_create#,nng_dialer_create(3)>> and +<<nng_dialer_start#,nng_dialer_start(3)>> instead. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_EADDRINVAL`:: An invalid _url_ was specified. +`NNG_ECLOSED`:: The socket _s_ is not open. +`NNG_ECONNREFUSED`:: The remote peer refused the connection. +`NNG_ECONNRESET`:: The remote peer reset the connection. +`NNG_EINVAL`:: An invalid set of _flags_ was specified. +`NNG_ENOMEM`:: Insufficient memory is available. +`NNG_EPEERAUTH`:: Authentication or authorization failure. +`NNG_EPROTO`:: A protocol error occurred. +`NNG_EUNREACHABLE`:: The remote address is not reachable. + +== SEE ALSO + +<<nng_dialer_close#,nng_dialer_close(3)>>, +<<nng_dialer_create#,nng_dialer_create(3)>> +<<nng_dialer_start#,nng_dialer_start(3)>>, +<<nng_listen#,nng_listen(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_dialer_close.adoc b/docs/man/nng_dialer_close.adoc new file mode 100644 index 00000000..82ca6fc3 --- /dev/null +++ b/docs/man/nng_dialer_close.adoc @@ -0,0 +1,52 @@ += nng_dialer_close(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_listener_close - close listener + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_dialer_close(nng_dialer d); +----------- + +== DESCRIPTION + +The `nng_dialer_close()` function closes the listener _d_. +This also closes any pipe that has been created by the dialer. + +Once this function returns, the dialer _d_ and any of its resources +are deallocated. Therefore it is an error to attempt to access _d_ +after this function has returned. (Attempts to do so will result in +`NNG_ECLOSED` errors.) + +Dialers are implicitly closed when the socket they are associated with +is closed. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ECLOSED`:: Parameter _d_ does not refer to an open listener. + +== SEE ALSO + +<<nng_close#,nng_close(3)>>, +<<nng_dial#,nng_dial(3)>>, +<<nng_dialer_create#,nng_dialer_create(3)>> +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_dialer_create.adoc b/docs/man/nng_dialer_create.adoc new file mode 100644 index 00000000..02b7796b --- /dev/null +++ b/docs/man/nng_dialer_create.adoc @@ -0,0 +1,74 @@ += nng_dialer_create(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_dialer_create - create dialer + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_dialer_create(nng_dialer *dialerp, nng_socket s, const char *url); +----------- + +== DESCRIPTION + +The `nng_dialer_create()` function creates a newly initialized +dialer, associated with socket _s_, and configured to connect to the +address specified by _url_, and stores a pointer to at the location +referenced by _dialerp_. + +Dialers initiate a remote connection to a listener. Upon a successful +connection being established, they create a pipe, add it to the socket, +and then wait for that pipe to be closed. When the pipe is closed, +they will re-initiate the connection. Dialer's will also periodically +retry a connection automatically if an attempt to connect asynchronously +fails. + +TIP: While it is convenient to think of dialers as "clients", the relationship +between the listener or dialer is orthogonal to any server or client status +that might be associated with a given protocol. For example, a <<nng_req#,REQ>> +socket might have associated dialers, but might also have associated listeners. +It may even have some of each at the same time! + +The dialer is not started, but may be further configured with +the <<nng_dialer_setopt#,nng_dialer_setopt(3)>> family of +functions. + +Once it is fully configured, the dialer may be started using the +<<nng_dialer_start#,nng_dialer_start(3)>> function. + +TIP: If no specific configuration is required, consider using the +simpler <<nng_dial#,nng_dial(3)>> function instead. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_EADDRINVAL`:: An invalid _url_ was specified. +`NNG_ECLOSED`:: The socket _s_ is not open. +`NNG_ENOMEM`:: Insufficient memory is available. + +== SEE ALSO + +<<nng_dial#,nng_dial(3)>>, +<<nng_dialer_close#,nng_dialer_close(3)>>, +<<nng_dialer_getopt#,nng_dialer_getopt(3)>>, +<<nng_dialer_setopt#,nng_dialer_setopt(3)>>, +<<nng_dialer_start#,nng_dialer_start(3)>>, +<<nng_listener_create#,nng_listener_create(3)>> +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_dialer_getopt.adoc b/docs/man/nng_dialer_getopt.adoc new file mode 100644 index 00000000..7c6fc3ad --- /dev/null +++ b/docs/man/nng_dialer_getopt.adoc @@ -0,0 +1,105 @@ += nng_dialer_getopt(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_dialer_getopt - get dialer option + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_dialer_getopt(nng_dialer d, const char *opt, void *val, size_t *valszp); +int nng_dialer_getopt_int(nng_dialer d, const char *opt, int *ivalp); +int nng_dialer_getopt_ms(nng_dialer d, const char *opt, nng_duration *durp); +int nng_dialer_getopt_ptr(nng_dialer d, const char *opt, void **ptr); +int nng_dialer_setopt_size(nng_dialer d, const char *opt, size_t *zp); +int nng_dialer_getopt_uint64(nng_dialer d, const char *opt, uint64_t *u64p); +----------- + +== DESCRIPTION + +The `nng_dialer_getopt()` functions are used to retrieve option values for +the dialer _d_. The actual options that may be retrieved in this way +vary, and are documented in the <<nng_getopt#,nng_getopt(3)>> manual. +Additionally some transport-specific options are documented with the +transports themselves. + +In all of these forms, the option _opt_ is retrieved from the dialer _d_. + +The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself. + +The first form of this function, `nng_dialer_getopt()`, can be used to +retrieve the value of any option. It is untyped. The caller must store +a pointer to a buffer to receive the value in _val_, and the size of the +buffer shall be stored at the location referenced by _valszp_. + +When the function returns, the actual size of the data copied (or that +would have been copied if sufficient space were present) is stored at +the location referened by _valszp_. If the caller's buffer is not large +enough to hold the entire object, then the copy is truncated. Therefore +the caller should validate that the returned size in _valszp_ does not +exceed the original buffer size to check for truncation. + +It is acceptable to pass `NULL` for _val_ if the value in _valszp_ is zero. +This can be used to determine the size of the buffer needed to receive +the object. + +Generally, it will be easier to use one of the typed forms instead. Note +however that no validation that the option is actually of the associated +type is performed, so the caller must take care to use the *correct* typed +form. + +The second form, `nng_dialer_getopt_int()`, +is for options which take an integer (or boolean). The value will +be stored at _ivalp_. For booleans the value will be eiher 0 (false) or 1 (true). + +The third form, `nng_dialer_getopt_ms()`, is used to retrieve time durations +(such as timeouts), stored in _durp_ as a number of milliseconds. +(The special value `NNG_DUR_INFINITE` means an infinite amount of time, and +the special value `NNG_DUR_DEFAULT` means a context-specific default.) + +The fourth form, `nng_dialer_getopt_ptr()`, is used to retrieve a +pointer _ptr_ to structured data. The data referenced by _ptr_ is +generally managed using other functions. +Note that this form is somewhat special in that the object is generally +not copied, but instead the *pointer* to the object is copied. + +The fifth form, `nng_dialer_getopt_size()`, is used to retrieve a size +into the pointer _zp_, typically for buffer sizes, message maximum sizes, and +similar options. + +The sixth form, `nng_diale_getopt_uint64()`, is used to retrieve a +64-bit unsigned value into the value referenced by _u64p_. +This is typically used for options +related to identifiers, network numbers, and similar. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ECLOSED`:: Parameter _d_ does not refer to an open dialer. +`NNG_ENOTSUP`:: The option _opt_ is not supported. +`NNG_EWRITEONLY`:: The option _opt_ is write-only. + +== SEE ALSO + +<<nng_listen#,nng_listen(3)>>, +<<nng_dialer_create#,nng_dialer_create(3)>> +<<nng_dialer_setopt#,nng_dialer_setopt(3)>> +<<nng_getopt#,nng_getopt(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_dialer_setopt.adoc b/docs/man/nng_dialer_setopt.adoc new file mode 100644 index 00000000..8bd6a04b --- /dev/null +++ b/docs/man/nng_dialer_setopt.adoc @@ -0,0 +1,104 @@ += nng_dialer_setopt(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_dialer_setopt - set dialer option + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_dialer_setopt(nng_dialer d, const char *opt, const void *val, + size_t valsz); +int nng_dialer_setopt_int(nng_dialer d, const char *opt, int ival); +int nng_dialer_setopt_ms(nng_dialer d, const char *opt, nng_duration dur); +int nng_dialer_setopt_ptr(nng_dialer d, const char *opt, void *ptr); +int nng_dialer_setopt_size(nng_dialer d, const char *opt, size_t z); +int nng_dialer_setopt_string(nng_dialer d, const char *opt, const char *str); +int nng_dialer_setopt_uint64(nng_dialer d, const char *opt, uint64_t u64); +----------- + +== DESCRIPTION + +The `nng_dialer_setopt()` functions are used to configure options for +the dialer _d_. The actual options that may be configured in this way +vary, and are documented in the <<nng_setopt#,nng_setopt(3)>> manual. +Additionally some transport-specific options are documented with the +transports themselves. + +In all of these forms, the option _opt_ is configured on the dialer _d_. + +The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself. + +The first form of this function, `nng_dialer_setopt()`, can be used to +configure any arbitrary data. +The _val_ pointer addresses the data to copy, and _valsz_ is the +size of the objected located at _val_. + +Generally, it will be easier to use one of the typed forms instead. + +The second form, `nng_dialer_setopt_int()`, +is for options which take an integer (or boolean). The _ival_ +is passed to the option. For booleans pass either 0 (false) or 1 (true). + +The third form, `nng_dialer_setopt_ms()`, is used to configure time durations +(such as timeouts). +The duration _dur_ is an integer number of milliseconds. (The special value +`NNG_DUR_INFINITE` means an infinite amount of time.) + +The fourth form, `nng_dialer_setopt_ptr()`, is used to pass a +pointer _ptr_ to structured data. The data referenced by _ptr_ is +generally managed by other functions. +For example, TLS configuration objects +(<<nng_tls_config_alloc#,nng_tls_config_alloc(3)>>) can be passed this way. +Note that this form is somewhat special in that the object is generally +not copied, but instead the *pointer* to the object is copied. + +The fifth form, `nng_dialer_setopt_size()`, is used to pass a size +specified by _z_, typically for buffer sizes, message maximum sizes, and +similar options. + +The sixth form, `nng_dialer_setopt_string()`, is used to pass a string +_str_. Strings passed this way must be legal UTF-8 or ASCII strings, terminated +with a `NUL` (`\0`) byte. (Other constraints may apply as well, see the +documentation for _opt_ for details.) + +The seventh form, `nng_dialer_setopt_uint64()`, is used to configure +the 64-bit unsigned value in _u64_. This is typically used for options +related to identifiers, network numbers, and similar. + +NOTE: Once a dialer has started, it is generally not possible to change +it's configuration. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ECLOSED`:: Parameter _d_ does not refer to an open dialer. +`NNG_EINVAL`:: The value being passed is invalid. +`NNG_ENOTSUP`:: The option _opt_ is not supported. +`NNG_EREADONLY`:: The option _opt_ is read-only. +`NNG_ESTATE`:: The dialer _d_ is already started. + +== SEE ALSO + +<<nng_dial#,nng_dial(3)>>, +<<nng_dialer_create#,nng_dialer_create(3)>> +<<nng_dialer_getopt#,nng_dialer_getopt(3)>> +<<nng_setopt#,nng_setopt(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_dialer_start.adoc b/docs/man/nng_dialer_start.adoc new file mode 100644 index 00000000..db6d7c07 --- /dev/null +++ b/docs/man/nng_dialer_start.adoc @@ -0,0 +1,74 @@ += nng_dialer_start(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_dialer_start - start dialer + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_dialer_start(nng_dialer d, int flags); +----------- + +== DESCRIPTION + +The `nng_dialer_start()` function starts the dialer _d_. + +This causes the dialer to start connecting to the address with which it was +created. + +When a connection is established, it results in a pipe being created, +which will be attached to the dialer's socket. + +Normally, the first attempt to connect to the dialer's address is done +synchronously, including any necessary name resolution. As a result, +a failure, such as if the connection is refused, will be returned +immediately, and no further action will be taken. + +However, if the special value `NNG_FLAG_NONBLOCK` is +supplied in _flags_, then the connection attempt is made asynchronously. + +Furthermore, if the connection was closed for a synchronously dialed +connection, the dialer will still attempt to redial asynchronously. + +TIP: While `NNG_FLAG_NONBLOCK` can help an application be more resilient, +it also generally makes diagnosing failures somewhat more difficult. + +Once a dialer has started, it is generally not possible to change +it's configuration. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_EADDRINVAL`:: An invalid _url_ was specified. +`NNG_ECLOSED`:: The socket _s_ is not open. +`NNG_ECONNREFUSED`:: The remote peer refused the connection. +`NNG_ECONNRESET`:: The remote peer reset the connection. +`NNG_EINVAL`:: An invalid set of _flags_ was specified. +`NNG_ENOMEM`:: Insufficient memory is available. +`NNG_EPEERAUTH`:: Authentication or authorization failure. +`NNG_EPROTO`:: A protocol error occurred. +`NNG_ESTATE`:: The dialer _d_ is already started. +`NNG_EUNREACHABLE`:: The remote address is not reachable. + +== SEE ALSO + +<<nng_dial#,nng_dial(3)>>, +<<nng_dialer_create#,nng_dialer_create(3)>> +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_client_alloc.adoc b/docs/man/nng_http_client_alloc.adoc new file mode 100644 index 00000000..40499862 --- /dev/null +++ b/docs/man/nng_http_client_alloc.adoc @@ -0,0 +1,47 @@ += nng_http_client_alloc(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_client_alloc - allocate HTTP client + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +int nng_http_client_alloc(nng_http_client *clientp, const nng_url *url); +----------- + +== DESCRIPTION + +The `nng_http_client_alloc()` allocates an HTTP client suitable for +connecting to the server identifyed by _url_ and stores a pointer to +it in the location referenced by _clientp_. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ENOTSUP`:: HTTP not supported. + +== SEE ALSO + +<<nng_http_client_connect#,nng_http_client_connect(3)>>, +<<nng_http_client_free#,nng_http_client_free(3)>>, +<<nng_url_parse#,nng_url_parse(3)>> +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_client_connect.adoc b/docs/man/nng_http_client_connect.adoc new file mode 100644 index 00000000..f5fef4eb --- /dev/null +++ b/docs/man/nng_http_client_connect.adoc @@ -0,0 +1,96 @@ += nng_http_client_connect(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_client_connect - establish HTTP client connection + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +void nng_http_client_connect(nng_http_client *client, nng_aio *aio); +----------- + +== DESCRIPTION + +The `nng_http_client_connect()` starts the process of establishing an HTTP +connection from _client_ to the server that was indicated in the URL that +_client_ was configured with. + +The result of the operation will be stored in the _aio_ when the operation +is complete, and will be obtainable via +<<nng_aio_result#,nng_aio_result(3)>>. + +On success, a pointer to the underlying HTTP client (type `nng_http_conn *`) +will be stored in the first output result of the _aio_, and can be +obtained by +<<nng_aio_get_output#,nng_aio_get_output(3)>> with an _index_ of zero (0). + +== RETURN VALUES + +None. + +== ERRORS + +`NNG_EADDRINVAL`:: The server is configured with an invalid address. +`NNG_ECANCELED`:: The operation was aborted. +`NNG_ECONNREFUSED`:: The TCP connection was refused by the server. +`NNG_ECONNRESET`:: The TCP connection was reset by the server. +`NNG_ENOMEM`:: Insufficient free memory exists. + +== EXAMPLE + +[source, c] +---- + nng_aio *aio; + nng_url *url; + nng_http_client *client; + nng_http_conn *conn; + int rv; + + // Error checks elided for clarity. + nng_url_parse(&url, "http://www.google.com"); + nng_aio_alloc(&aio, NULL, NULL); + nng_http_client_alloc(&client, url); + + nng_http_client_connect(client, aio); + + // Wait for connection to establish (or attempt to fail). + nng_aio_wait(aio); + + if ((rv = nng_aio_result(aio)) != 0) { + printf("Connection failed: %s\n", nng_strerror(rv)); + } else { + // Connection established, get it. + conn = nng_aio_get_output(aio, 0); + + // ... do something with it here + + // Close the connection when done to avoid leaking it. + nng_http_conn_close(conn); + } +---- + +== SEE ALSO + +<<nng_aio_get_output#,nng_aio_get_output(3)>>, +<<nng_aio_result#,nng_aio_result(3)>>, +<<nng_aio_wait#,nng_aio_wait(3)>>, +<<nng_http_client_alloc#,nng_http_client_alloc(3)>>, +<<nng_http_conn_close#,nng_http_conn_close(3)>>, +<<nng_http_conn_read#,nng_http_conn_read(3)>>, +<<nng_http_conn_write#,nng_http_conn_write(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_client_free.adoc b/docs/man/nng_http_client_free.adoc new file mode 100644 index 00000000..e54c7bd5 --- /dev/null +++ b/docs/man/nng_http_client_free.adoc @@ -0,0 +1,47 @@ += nng_http_client_free(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_client_free - free HTTP client + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +void nng_http_client_free(nng_http_client *client); +----------- + +== DESCRIPTION + +The `nng_http_client_free()` frees the HTTP client and any associated +resources referenced by _client_. + +NOTE: Any connections created by +<<nng_http_client_connect#,nng_http_client_connect(3)>> are unaffected, +and so the caller must close those explicitly if desired. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_http_client_alloc#,nng_http_client_alloc(3)>>, +<<nng_http_client_connect#,nng_http_client_connect(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_client_get_tls.adoc b/docs/man/nng_http_client_get_tls.adoc new file mode 100644 index 00000000..7aa5fd27 --- /dev/null +++ b/docs/man/nng_http_client_get_tls.adoc @@ -0,0 +1,50 @@ += nng_http_client_get_tls(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_client_get_tls - get HTTP client TLS configuration + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +int nng_http_client_get_tls(nng_http_client *client, nng_tls_config **cfgp); +----------- + +== DESCRIPTION + +The `nng_http_client_get_tls()` obtains the TLS configuration of _client_ and +saves a pointer to it in the address referenced by _cfgp_. + +The configuration will be `NULL` if the HTTP client 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_client_alloc#,nng_http_client_alloc(3)>>, +<<nng_http_client_connect#,nng_http_client_connect(3)>>, +<<nng_http_client_set_tls#,nng_http_client_set_tls(3)>>, +<<nng_tls_config_alloc#,nng_tls_config_alloc(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_client_set_tls.adoc b/docs/man/nng_http_client_set_tls.adoc new file mode 100644 index 00000000..deed7e57 --- /dev/null +++ b/docs/man/nng_http_client_set_tls.adoc @@ -0,0 +1,56 @@ += nng_http_client_set_tls(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_client_set_tls - set HTTP client TLS configuration + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +int nng_http_client_set_tls(nng_http_client *client, nng_tls_config *cfg); +----------- + +== DESCRIPTION + +The `nng_http_client_set_tls()` sets the TLS configuration of _client_ to +_cfg_. + +This change overwrites any previous TLS configuration. + +WARNING: This also invalidates any previously obtained values from +<<nng_http_client_get_tls#,nng_http_client_get_tls(3)>>. + +NOTE: Any connections established with +<<nng_http_client_connect#,nng_http_client_connect(3)>> +will continue to use any TLS configuration that they were started with. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ENOTSUP`:: Either HTTP or TLS not supported. + +== SEE ALSO + +<<nng_http_client_alloc#,nng_http_client_alloc(3)>>, +<<nng_http_client_connect#,nng_http_client_connect(3)>>, +<<nng_http_client_get_tls#,nng_http_client_get_tls(3)>>, +<<nng_tls_config_alloc#,nng_tls_config_alloc(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_conn_close.adoc b/docs/man/nng_http_conn_close.adoc new file mode 100644 index 00000000..0c512815 --- /dev/null +++ b/docs/man/nng_http_conn_close.adoc @@ -0,0 +1,46 @@ += nng_http_conn_close(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_conn_close - close HTTP connection + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +void nng_http_conn_close(nng_http_conn *conn); +----------- + +== DESCRIPTION + +The `nng_http_conn_close()` function closes the supplied HTTP connection _conn_, +including any disposing of any underlying file descriptors or related resources. + +Once this function, no further access to the _conn_ structure may be made. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_http_client_connect#,nng_http_client_connect(3)>>, +<<nng_http_alloc_handler#,nng_http_alloc_handler(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_conn_read.adoc b/docs/man/nng_http_conn_read.adoc new file mode 100644 index 00000000..92826682 --- /dev/null +++ b/docs/man/nng_http_conn_read.adoc @@ -0,0 +1,73 @@ += nng_http_conn_read(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_conn_read - read from HTTP connection + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +void nng_http_conn_read(nng_http_conn *conn, nng_aio *aio); +----------- + +== DESCRIPTION + +The `nng_http_conn_read()` function starts an asynchronous read from the +HTTP connection _conn_, into the scatter/gather vector located in the +asynchronous I/O structure _aio_. + +NOTE: The <<nng_aio_set_iov#,nng_aio_set_iov(3)>> function must have been +called first, to set the scatter/gather vector for _aio_. + +This function returns immediately, with no return value. Completion of +the operation is signaled via the _aio_, and the final result may be +obtained via <<nng_aio_result#,nng_aio_result>>. That result will +either be zero or an error code. + +The I/O operation completes as soon as at least one byte has been +read, or an error has occurred. +Therefore, the number of bytes read may be less than requested. The actual +number of bytes read can be determined with <<nng_aio_count#,nng_aio_count(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_ECANCELED`:: The operation was canceled. +`NNG_ECLOSED`:: The connection was closed. +`NNG_ECONNRESET`:: The peer closed the connection. +`NNG_EINVAL`:: The _aio_ does not contain a valid scatter/gather vector. +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. +`NNG_ENOTSUP`:: HTTP operations are not supported. +`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. + +== SEE ALSO + +<<nng_aio_alloc#,nng_aio_alloc(3)>>, +<<nng_aio_count#,nng_aio_count(3)>>, +<<nng_aio_result#,nng_aio_result(3)>>, +<<nng_aio_set_iov#,nng_aio_set_iov(3)>>, +<<nng_http_alloc_handler#,nng_http_alloc_handler(3)>>, +<<nng_http_client_connect#,nng_http_client_connect(3)>>, +<<nng_http_conn_read_all#,nng_http_conn_read_all(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_conn_read_all.adoc b/docs/man/nng_http_conn_read_all.adoc new file mode 100644 index 00000000..e5f89389 --- /dev/null +++ b/docs/man/nng_http_conn_read_all.adoc @@ -0,0 +1,76 @@ += nng_http_conn_read_all(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_conn_read_all - read all from HTTP connection + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +void nng_http_conn_read_all(nng_http_conn *conn, nng_aio *aio); +----------- + +== DESCRIPTION + +The `nng_http_conn_read_all()` function starts an asynchronous read from the +HTTP connection _conn_, into the scatter/gather vector located in the +asynchronous I/O structure _aio_. + +NOTE: The <<nng_aio_set_iov#,nng_aio_set_iov(3)>> function must have been +called first, to set the scatter/gather vector for _aio_. + +This function returns immediately, with no return value. Completion of +the operation is signaled via the _aio_, and the final result may be +obtained via <<nng_aio_result#,nng_aio_result>>. That result will +either be zero or an error code. + +The I/O operation completes only when the entire amount of data +requested has been read, or an error has occurred. If the operation +completes successfully, then the entire requested data has been read. + +It is still possible for a partial read to complete in the event of an +error. The actual number of bytes read can be determined with +<<nng_aio_count#,nng_aio_count(3)>>. + +TIP: The main purpose for this function is to faciliate reading HTTP +body content, after first determining the length of the body content +from the relevant HTTP headers (typically `Content-Length`). + +== RETURN VALUES + +None. + +== ERRORS + +`NNG_ECANCELED`:: The operation was canceled. +`NNG_ECLOSED`:: The connection was closed. +`NNG_ECONNRESET`:: The peer closed the connection. +`NNG_EINVAL`:: The _aio_ does not contain a valid scatter/gather vector. +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. +`NNG_ENOTSUP`:: HTTP operations are not supported. +`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. + +== SEE ALSO + +<<nng_aio_alloc#,nng_aio_alloc(3)>>, +<<nng_aio_count#,nng_aio_count(3)>>, +<<nng_aio_result#,nng_aio_result(3)>>, +<<nng_aio_set_iov#,nng_aio_set_iov(3)>>, +<<nng_http_alloc_handler#,nng_http_alloc_handler(3)>>, +<<nng_http_client_connect#,nng_http_client_connect(3)>>, +<<nng_http_conn_read#,nng_http_conn_read(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_conn_read_req.adoc b/docs/man/nng_http_conn_read_req.adoc new file mode 100644 index 00000000..bf1c1289 --- /dev/null +++ b/docs/man/nng_http_conn_read_req.adoc @@ -0,0 +1,64 @@ += nng_http_conn_read_req(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_conn_read_req - read HTTP request + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +void nng_http_conn_read_req(nng_http_conn *conn, nng_http_req *req, + nng_aio *aio); +----------- + +== DESCRIPTION + +The `nng_http_conn_read_req()` function starts an asynchronous read from the +HTTP connection _conn_, reading an HTTP request into the _req_, including all +of the related headers. + +NOTE: Any HTTP entity/body data associated with the request is *not* read +automatically. The caller should use +<<nng_http_conn_read_all#,nng_http_conn_read_all(3)>> to read the entity +data, based on the details of the request itself. + +This function returns immediately, with no return value. Completion of +the operation is signaled via the _aio_, and the final result may be +obtained via <<nng_aio_result#,nng_aio_result>>. That result will +either be zero or an error code. + +== RETURN VALUES + +None. + +== ERRORS + +`NNG_ECANCELED`:: The operation was canceled. +`NNG_ECLOSED`:: The connection was closed. +`NNG_ECONNRESET`:: The peer closed the connection. +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. +`NNG_ENOTSUP`:: HTTP operations are not supported. +`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. + +== SEE ALSO + +<<nng_aio_alloc#,nng_aio_alloc(3)>>, +<<nng_aio_result#,nng_aio_result(3)>>, +<<nng_http_alloc_handler#,nng_http_alloc_handler(3)>>, +<<nng_http_client_connect#,nng_http_client_connect(3)>>, +<<nng_http_conn_read_all#,nng_http_conn_read_all(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_conn_read_res.adoc b/docs/man/nng_http_conn_read_res.adoc new file mode 100644 index 00000000..4a1f6aaa --- /dev/null +++ b/docs/man/nng_http_conn_read_res.adoc @@ -0,0 +1,64 @@ += nng_http_conn_read_res(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_conn_read_res - read HTTP response + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +void nng_http_conn_read_res(nng_http_conn *conn, nng_http_res *res, + nng_aio *aio); +----------- + +== DESCRIPTION + +The `nng_http_conn_read_res()` function starts an asynchronous read from the +HTTP connection _conn_, reading an HTTP response into the _res_, including all +of the related headers. + +NOTE: Any HTTP entity/body data associated with the response is *not* read +automatically. The caller should use +<<nng_http_conn_read_all#,nng_http_conn_read_all(3)>> to read the entity +data, based on the details of the response itself. + +This function returns immediately, with no return value. Completion of +the operation is signaled via the _aio_, and the final result may be +obtained via <<nng_aio_result#,nng_aio_result>>. That result will +either be zero or an error code. + +== RETURN VALUES + +None. + +== ERRORS + +`NNG_ECANCELED`:: The operation was canceled. +`NNG_ECLOSED`:: The connection was closed. +`NNG_ECONNRESET`:: The peer closed the connection. +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. +`NNG_ENOTSUP`:: HTTP operations are not supported. +`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. + +== SEE ALSO + +<<nng_aio_alloc#,nng_aio_alloc(3)>>, +<<nng_aio_result#,nng_aio_result(3)>>, +<<nng_http_alloc_handler#,nng_http_alloc_handler(3)>>, +<<nng_http_client_connect#,nng_http_client_connect(3)>>, +<<nng_http_conn_read_all#,nng_http_conn_read_all(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_conn_write.adoc b/docs/man/nng_http_conn_write.adoc new file mode 100644 index 00000000..df9be033 --- /dev/null +++ b/docs/man/nng_http_conn_write.adoc @@ -0,0 +1,74 @@ += nng_http_conn_write(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_conn_write - write to HTTP connection + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +void nng_http_conn_write(nng_http_conn *conn, nng_aio *aio); +----------- + +== DESCRIPTION + +The `nng_http_conn_write()` function starts an asynchronous write to the +HTTP connection _conn_ from the scatter/gather vector located in the +asynchronous I/O structure _aio_. + +NOTE: The <<nng_aio_set_iov#,nng_aio_set_iov(3)>> function must have been +called first, to set the scatter/gather vector for _aio_. + +This function returns immediately, with no return value. Completion of +the operation is signaled via the _aio_, and the final result may be +obtained via <<nng_aio_result#,nng_aio_result>>. That result will +either be zero or an error code. + +The I/O operation completes as soon as at least one byte has been +written, or an error has occurred. +Therefore, the number of bytes written may be less than requested. The actual +number of bytes written can be determined with +<<nng_aio_count#,nng_aio_count(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_ECANCELED`:: The operation was canceled. +`NNG_ECLOSED`:: The connection was closed. +`NNG_ECONNRESET`:: The peer closed the connection. +`NNG_EINVAL`:: The _aio_ does not contain a valid scatter/gather vector. +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. +`NNG_ENOTSUP`:: HTTP operations are not supported. +`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. + +== SEE ALSO + +<<nng_aio_alloc#,nng_aio_alloc(3)>>, +<<nng_aio_count#,nng_aio_count(3)>>, +<<nng_aio_result#,nng_aio_result(3)>>, +<<nng_aio_set_iov#,nng_aio_set_iov(3)>>, +<<nng_http_alloc_handler#,nng_http_alloc_handler(3)>>, +<<nng_http_client_connect#,nng_http_client_connect(3)>>, +<<nng_http_conn_write_all#,nng_http_conn_write_all(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_conn_write_all.adoc b/docs/man/nng_http_conn_write_all.adoc new file mode 100644 index 00000000..3f112540 --- /dev/null +++ b/docs/man/nng_http_conn_write_all.adoc @@ -0,0 +1,94 @@ += nng_http_conn_write_all(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_conn_write_all - write all to HTTP connection + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +void nng_http_conn_write_all(nng_http_conn *conn, nng_aio *aio); +----------- + +== DESCRIPTION + +The `nng_http_conn_write_all()` function starts an asynchronous write to the +HTTP connection _conn_, into the scatter/gather vector located in the +asynchronous I/O structure _aio_. + +NOTE: The <<nng_aio_set_iov#,nng_aio_set_iov(3)>> function must have been +called first, to set the scatter/gather vector for _aio_. + +This function returns immediately, with no return value. Completion of +the operation is signaled via the _aio_, and the final result may be +obtained via <<nng_aio_result#,nng_aio_result>>. That result will +either be zero or an error code. + +The I/O operation completes only when the entire amount of data +requested has been written, or an error has occurred. If the operation +completes successfully, then the entire requested data has been written. + +It is still possible for a partial write to complete in the event of an +error. The actual number of bytes written can be determined with +<<nng_aio_count#,nng_aio_count(3)>>. + +TIP: The main purpose for this function is to faciliate writing HTTP +body content. + +TIP: Usually an HTTP request or response will have been written immediately +prior to this with <<nng_http_conn_write_req#,http_conn_write_req(3)>> or +<<nng_http_conn_write_res#,http_conn_write_res(3)>>. In that case the +request or response should have also contained an `Content-Length` header, +and possibly a `Content-Type` header. + +TIP: An easier solution to sending HTTP content data, is to include the +conten with the request or reply using a function like +<<nng_http_req_copy_data#,nng_http_req_copy_data(3)>>. In that case, +the body data will be written automatically by the +<<nng_http_conn_write_req#,http_conn_write_req(3)>> or +<<nng_http_conn_write_req#,http_conn_write_res(3)>> function. + +== RETURN VALUES + +None. + +== ERRORS + +`NNG_ECANCELED`:: The operation was canceled. +`NNG_ECLOSED`:: The connection was closed. +`NNG_ECONNRESET`:: The peer closed the connection. +`NNG_EINVAL`:: The _aio_ does not contain a valid scatter/gather vector. +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. +`NNG_ENOTSUP`:: HTTP operations are not supported. +`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. + +== SEE ALSO + +<<nng_aio_alloc#,nng_aio_alloc(3)>>, +<<nng_aio_count#,nng_aio_count(3)>>, +<<nng_aio_result#,nng_aio_result(3)>>, +<<nng_aio_set_iov#,nng_aio_set_iov(3)>>, +<<nng_http_alloc_handler#,nng_http_alloc_handler(3)>>, +<<nng_http_client_connect#,nng_http_client_connect(3)>>, +<<nng_http_conn_write#,nng_http_conn_write(3)>>, +<<nng_http_conn_write_req#,http_conn_write_req(3)>>, +<<nng_http_conn_write_res#,http_conn_write_res(3)>>, +<<nng_http_req_copy_data#,nng_http_req_copy_data(3)>>, +<<nng_http_req_set_data#,nng_http_req_set_data(3)>>, +<<nng_http_res_copy_data#,nng_http_res_copy_data(3)>>, +<<nng_http_res_set_data#,nng_http_res_set_data(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_conn_write_req.adoc b/docs/man/nng_http_conn_write_req.adoc new file mode 100644 index 00000000..040764ca --- /dev/null +++ b/docs/man/nng_http_conn_write_req.adoc @@ -0,0 +1,62 @@ += nng_http_conn_write_req(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_conn_write_req - write HTTP request + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +void nng_http_conn_write_req(nng_http_conn *conn, nng_http_req *req, + nng_aio *aio); +----------- + +== DESCRIPTION + +The `nng_http_conn_write_req()` function starts an asynchronous write of +the HTTP request _req_ to the connection _conn_. The entire request is sent, +including headers, and if present, the request body data. (The +request body can be set with +<<nng_http_req_set_data#,nng_http_req_set_data>> or +<<nng_http_req_copy_data#,nng_http_req_copy_data>>.) + +This function returns immediately, with no return value. Completion of +the operation is signaled via the _aio_, and the final result may be +obtained via <<nng_aio_result#,nng_aio_result>>. That result will +either be zero or an error code. + +== RETURN VALUES + +None. + +== ERRORS + +`NNG_ECANCELED`:: The operation was canceled. +`NNG_ECLOSED`:: The connection was closed. +`NNG_ECONNRESET`:: The peer closed the connection. +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. +`NNG_ENOTSUP`:: HTTP operations are not supported. +`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. + +== SEE ALSO + +<<nng_aio_alloc#,nng_aio_alloc(3)>>, +<<nng_aio_result#,nng_aio_result(3)>>, +<<nng_http_alloc_handler#,nng_http_alloc_handler(3)>>, +<<nng_http_client_connect#,nng_http_client_connect(3)>>, +<<nng_http_conn_read_all#,nng_http_conn_read_all(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_conn_write_res.adoc b/docs/man/nng_http_conn_write_res.adoc new file mode 100644 index 00000000..f2df3c72 --- /dev/null +++ b/docs/man/nng_http_conn_write_res.adoc @@ -0,0 +1,71 @@ += nng_http_conn_write_res(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_conn_write_res - write HTTP response + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +void nng_http_conn_write_res(nng_http_conn *conn, nng_http_res *res, + nng_aio *aio); +----------- + +== DESCRIPTION + +The `nng_http_conn_write_res()` function starts an asynchronous write of +the HTTP response _res_ to the connection _conn_. The entire response is sent, +including headers, and if present, the response body data. (The +response body can be set with +<<nng_http_res_set_data#,nng_http_res_set_data>> or +<<nng_http_res_copy_data#,nng_http_res_copy_data>>.) + +This function returns immediately, with no return value. Completion of +the operation is signaled via the _aio_, and the final result may be +obtained via <<nng_aio_result#,nng_aio_result>>. That result will +either be zero or an error code. + +=== Persistent Connections + +By default, for `HTTP/1.1` connections, the connection is kept open, and +will be reused to receive new requests. + +If however the _res_ contains a header of `Connection:` with a value +of `Close` (case-insensitive) or the response corresponds to `HTTP/1.0`, +then the connection is immediately after sending the response. + +== RETURN VALUES + +None. + +== ERRORS + +`NNG_ECANCELED`:: The operation was canceled. +`NNG_ECLOSED`:: The connection was closed. +`NNG_ECONNRESET`:: The peer closed the connection. +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. +`NNG_ENOTSUP`:: HTTP operations are not supported. +`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. + +== SEE ALSO + +<<nng_aio_alloc#,nng_aio_alloc(3)>>, +<<nng_aio_result#,nng_aio_result(3)>>, +<<nng_http_alloc_handler#,nng_http_alloc_handler(3)>>, +<<nng_http_client_connect#,nng_http_client_connect(3)>>, +<<nng_http_conn_read_all#,nng_http_conn_read_all(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_handler_alloc.adoc b/docs/man/nng_http_handler_alloc.adoc new file mode 100644 index 00000000..023d0400 --- /dev/null +++ b/docs/man/nng_http_handler_alloc.adoc @@ -0,0 +1,139 @@ += nng_http_handler_alloc(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_handler_alloc - allocate HTTP server handler + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +typedef struct nng_http_handler nng_http_handler; + +int nng_http_handler_alloc(nng_http_handler **hp, const char *path, + void (*func)(nng_aio *); +int nng_http_handler_alloc_directory(nng_http_handler **hp, const char *path, + const char *dirname); +int nng_http_handler_alloc_file(nng_http_handler **hp, const char *path, + const char *filename); +int nng_http_handler_alloc_static(nng_http_handler **hp, const char *path, + const void *data, size_t size, const char *content_type); +----------- + +== DESCRIPTION + +The `nng_http_handler_alloc()` family of functions allocate a handler +which will be used to process requests coming into an HTTP server. +On success, a pointer to the handler is stored at the located pointed to +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 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. +(See <<nng_http_handler_set_tree#,nng_http_handler_set_tree(3)>>). + +=== Custom Handler + +The generic (first) form of this creates a handler that uses a user-supplied +function to process HTTP requests. This function uses the asynchronous I/O +framework. The function takes a pointer to an `nng_aio` structure. That +structure will be passed with the following input values (retrieved with +<<nng_aio_get_input#,nng_aio_get_input(3)>>): + + 0: ``nng_http_req *`` __request__:: The client's HTTP request. + 1: ``nng_http_handler *``__handler__:: Pointer to the handler object. + 2: ``nng_http_conn *``__conn__:: The underlying HTTP connection. + +The handler should create an `nng_http_res *` response (such as via +<<nng_http_res_alloc#,nng_http_res_alloc(3)>> or +<<nng_http_res_alloc_error#,nng_http_res_alloc_error(3)>>) and store that +in as the first output (index 0) with +<<nng_aio_set_output#,nng_aio_set_output(3)>>. + +Alternatively, the handler may send the HTTP response (and any associated +body data) itself using the connection. In that case the output at index +0 of the _aio_ should be NULL. + +Finally, using the <<nng_aio_finish#,nng_aio_finish(3)>> function, the +_aio_ should be completed successfully. If any non-zero status is returned +back to the caller instead, then a generic 500 response will be created and +sent, if possible, and the connection will be closed. + +=== Directory Handler + +The second member of this family, `nng_http_handler_alloc_directory()`, creates +a handler configured to serve a directory tree. The _uri_ is taken as +the root, and files are served from the directory tree rooted at _path_. + +When the client Request-URI resolves to a directory in the filesystem, +the handler looks first for a file named `index.html` or `index.htm`. If +one is found, then that file is returned back to the client. If no such +index file exists, then an `NNG_HTTP_STATUS_NOT_FOUND` (404) error is +sent back to the client. + +The `Content-Type` will be set automatically based upon the extension +of the requsted file name. If a content type cannot be determined from +the extension, then `application/octet-stream` is used. + +=== File Handler + +The third member of this family, `nng_http_handler_alloc_file()`, creates +a handler to serve up a single file; it does not traverse directories +or search for `index.html` or `index.htm` files. + +The `Content-Type` will be set automatically based upon the extension +of the requsted file name. If a content type cannot be determined from +the extension, then `application/octet-stream` is used. + +=== Static Handler + +The fourth member of this family, `nng_http_handler_alloc_static()`, creates +a handler to serve up fixed content located in program data. The client is +sent the _data_, with `Content-Length` of _size_ bytes, and `Content-Type` of +__content_type__. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`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 + +<<nng_aio_finish#,nng_aio_finish(3)>>, +<<nng_aio_get_input#,nng_aio_get_input(3)>>, +<<nng_aio_set_output#,nng_aio_set_output(3)>>, +<<nng_http_handler_free#,nng_http_handler_free(3)>>, +<<nng_http_handler_set_host#,nng_http_handler_set_host(3)>>, +<<nng_http_handler_set_method#,nng_http_handler_set_method(3)>>, +<<nng_http_handler_set_tree#,nng_http_handler_set_tree(3)>>, +<<nng_http_res_alloc#,nng_http_res_alloc(3)>>, +<<nng_http_res_alloc_error#,nng_http_res_alloc_error(3)>>, +<<nng_http_server_add_handler#,nng_http_server_add_handler(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_handler_free.adoc b/docs/man/nng_http_handler_free.adoc new file mode 100644 index 00000000..fe568513 --- /dev/null +++ b/docs/man/nng_http_handler_free.adoc @@ -0,0 +1,46 @@ += nng_http_handler_free(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_handler_free - free HTTP server handler + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.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)>> diff --git a/docs/man/nng_http_handler_get_data.adoc b/docs/man/nng_http_handler_get_data.adoc new file mode 100644 index 00000000..de139053 --- /dev/null +++ b/docs/man/nng_http_handler_get_data.adoc @@ -0,0 +1,46 @@ += nng_http_handler_get_data(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_handler_get_data - return extra data for HTTP handler + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.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)>> diff --git a/docs/man/nng_http_handler_set_data.adoc b/docs/man/nng_http_handler_set_data.adoc new file mode 100644 index 00000000..f1b74211 --- /dev/null +++ b/docs/man/nng_http_handler_set_data.adoc @@ -0,0 +1,52 @@ += nng_http_handler_set_data(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_handler_get_data - set extra data for HTTP handler + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.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)>> diff --git a/docs/man/nng_http_handler_set_host.adoc b/docs/man/nng_http_handler_set_host.adoc new file mode 100644 index 00000000..d3e464e3 --- /dev/null +++ b/docs/man/nng_http_handler_set_host.adoc @@ -0,0 +1,56 @@ += nng_http_handler_set_host(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_handler_set_host - set host for HTTP handler + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.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)>> diff --git a/docs/man/nng_http_handler_set_method.adoc b/docs/man/nng_http_handler_set_method.adoc new file mode 100644 index 00000000..8769ffc8 --- /dev/null +++ b/docs/man/nng_http_handler_set_method.adoc @@ -0,0 +1,58 @@ += nng_http_handler_set_method(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_handler_set_method - set HTTP handler method + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.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)>> diff --git a/docs/man/nng_http_handler_set_tree.adoc b/docs/man/nng_http_handler_set_tree.adoc new file mode 100644 index 00000000..a21a6681 --- /dev/null +++ b/docs/man/nng_http_handler_set_tree.adoc @@ -0,0 +1,49 @@ += nng_http_handler_set_tree(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_handler_set_tree - set HTTP handler to match trees + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.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)>> diff --git a/docs/man/nng_http_hijack.adoc b/docs/man/nng_http_hijack.adoc new file mode 100644 index 00000000..8a08751f --- /dev/null +++ b/docs/man/nng_http_hijack.adoc @@ -0,0 +1,63 @@ += nng_http_hijack(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_hijack - hijack HTTP server connection + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +void nng_http_hijack(nng_http_conn *conn); +----------- + +== DESCRIPTION + +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)>> diff --git a/docs/man/nng_http_req_add_header.adoc b/docs/man/nng_http_req_add_header.adoc new file mode 100644 index 00000000..eb403334 --- /dev/null +++ b/docs/man/nng_http_req_add_header.adoc @@ -0,0 +1,62 @@ += nng_http_req_add_header(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_req_add_header - add HTTP request header + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +int nng_http_req_add_header(nng_http_req *req, const char *key, + const char *val); +----------- + +== DESCRIPTION + +The `nng_http_req_add_header()` adds an HTTP header for the request +_req_ and the _key_ to the _val_. The _key_ and _val_ are copied. + +If a header with the value of _key_ already exists, then a comma +and whitespace separate are appended to it, followed by _val_. + +If no such header already exists, then one is created with the value _val_. + +TIP: The HTTP specification requires that duplicate headers be treated +identically to a single header with multiple comma-delimited values. + +TIP: See <<nng_http_req_set_header#,nng_http_req_set_header(3)>> 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 + +<<nng_http_req_alloc#,nng_http_req_alloc(3)>>, +<<nng_http_req_del_header#,nng_http_req_del_header(3)>>, +<<nng_http_req_get_header#,nng_http_req_get_header(3)>>, +<<nng_http_req_set_header#,nng_http_req_set_header(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_req_alloc.adoc b/docs/man/nng_http_req_alloc.adoc new file mode 100644 index 00000000..f3aead52 --- /dev/null +++ b/docs/man/nng_http_req_alloc.adoc @@ -0,0 +1,60 @@ += nng_http_req_alloc(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_req_alloc - allocate HTTP request structure + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +int nng_http_req_alloc(nng_http_req **reqp, const nng_url *url); +----------- + +== DESCRIPTION + +The `nng_http_req_alloc()` function allocates a new HTTP request structure +and stores a pointer to it in __reqp__. The request will be initialized +to perform an HTTP/1.1 `GET` operation using the URL specified in __url__. + +== 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 + +<<nng_http_conn_read_req#,nng_http_conn_read_req(3)>>, +<<nng_http_conn_write_req#,nng_http_conn_write_req(3)>>, +<<nng_http_req_add_header#,nng_http_req_add_header(3)>>, +<<nng_http_req_copy_data#,nng_http_req_copy_data(3)>>, +<<nng_http_req_del_header#,nng_http_req_del_header(3)>>, +<<nng_http_req_free#,nng_http_req_free(3)>>, +<<nng_http_req_get_header#,nng_http_req_get_header(3)>>, +<<nng_http_req_get_method#,nng_http_req_get_method(3)>>, +<<nng_http_req_get_uri#,nng_http_req_get_uri(3)>>, +<<nng_http_req_get_version#,nng_http_req_get_version(3)>>, +<<nng_http_req_set_data#,nng_http_req_set_data(3)>>, +<<nng_http_req_set_method#,nng_http_req_set_method(3)>>, +<<nng_http_req_set_uri#,nng_http_req_set_uri(3)>>, +<<nng_http_req_set_version#,nng_http_req_set_version(3)>>, +<<nng_http_res_alloc#,nng_http_res_alloc(3)>>, +<<nng_url_parse#,nng_url_parse(3)>> +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_req_copy_data.adoc b/docs/man/nng_http_req_copy_data.adoc new file mode 100644 index 00000000..184eaaa5 --- /dev/null +++ b/docs/man/nng_http_req_copy_data.adoc @@ -0,0 +1,60 @@ += nng_http_req_copy_data(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_req_copy_data - copy HTTP request body + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +int nng_http_req_copy_data(nng_http_req *req, const void *body, size_t size); +----------- + +== DESCRIPTION + +The `nng_http_req_copy_data()` makes a copy of _body_ (of size __size__) +and sets the HTTP body for the request _req_ to it. The copy will be +deallocated automatically when _req_ is freed. + +The copied body data will be automatically sent with the request when it +is sent using <<nng_http_conn_write_req#,nni_http_conn_write_req(3)>>. + +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 +<<nng_http_req_set_data#,nng_http_req_set_data(3)>> 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 + +<<nng_http_conn_write_req#,nng_http_conn_write_req(3)>>, +<<nng_http_req_alloc#,nng_http_req_alloc(3)>>, +<<nng_http_req_set_data#,nng_http_req_set_data(3)>>, +<<nng_http_req_set_header#,nng_http_req_set_header(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_req_del_header.adoc b/docs/man/nng_http_req_del_header.adoc new file mode 100644 index 00000000..3306e8c9 --- /dev/null +++ b/docs/man/nng_http_req_del_header.adoc @@ -0,0 +1,50 @@ += nng_http_req_set_header(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_req_set_header - set HTTP request header + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +int nng_http_req_set_header(nng_http_req *req, const char *key); +----------- + +== 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 + +<<nng_http_req_alloc#,nng_http_req_alloc(3)>>, +<<nng_http_req_add_header#,nng_http_req_add_header(3)>>, +<<nng_http_req_del_header#,nng_http_req_del_header(3)>>, +<<nng_http_req_get_header#,nng_http_req_get_header(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_req_free.adoc b/docs/man/nng_http_req_free.adoc new file mode 100644 index 00000000..8fe0b31c --- /dev/null +++ b/docs/man/nng_http_req_free.adoc @@ -0,0 +1,42 @@ += nng_http_req_free(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_req_free - free HTTP request structure + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +void nng_http_req_free(nng_http_req *req); +----------- + +== DESCRIPTION + +The `nng_http_req_free()` function deallocates the HTTP request structure +_req_ entirely. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_http_req_alloc#,nng_http_req_alloc(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_req_get_header.adoc b/docs/man/nng_http_req_get_header.adoc new file mode 100644 index 00000000..b8ddafd3 --- /dev/null +++ b/docs/man/nng_http_req_get_header.adoc @@ -0,0 +1,50 @@ += nng_http_req_get_header(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_req_get_header - return HTTP request header + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +const char *nng_http_req_get_header(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 + +<<nng_http_req_alloc#,nng_http_req_alloc(3)>>, +<<nng_http_req_add_header#,nng_http_req_add_header(3)>>, +<<nng_http_req_set_header#,nng_http_req_set_header(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_req_get_method.adoc b/docs/man/nng_http_req_get_method.adoc new file mode 100644 index 00000000..2788a39d --- /dev/null +++ b/docs/man/nng_http_req_get_method.adoc @@ -0,0 +1,44 @@ += nng_http_req_get_method(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_req_get_method - return HTTP request method + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +const char *nng_http_req_get_method(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 + +<<nng_http_req_alloc#,nng_http_req_alloc(3)>>, +<<nng_http_req_set_method#,nng_http_req_set_method(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_req_get_uri.adoc b/docs/man/nng_http_req_get_uri.adoc new file mode 100644 index 00000000..a5d7f46a --- /dev/null +++ b/docs/man/nng_http_req_get_uri.adoc @@ -0,0 +1,45 @@ += nng_http_req_get_method(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_req_get_uri - return HTTP request URI + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +const char *nng_http_req_get_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 + +<<nng_http_req_alloc#,nng_http_req_alloc(3)>>, +<<nng_http_req_set_uri#,nng_http_req_set_uri(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_req_get_version.adoc b/docs/man/nng_http_req_get_version.adoc new file mode 100644 index 00000000..958fd2c5 --- /dev/null +++ b/docs/man/nng_http_req_get_version.adoc @@ -0,0 +1,44 @@ += nng_http_req_get_version(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_req_get_version - return HTTP request protocol version + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +const char *nng_http_req_get_version(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 + +<<nng_http_req_alloc#,nng_http_req_alloc(3)>>, +<<nng_http_req_set_version#,nng_http_req_set_version(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_req_set_data.adoc b/docs/man/nng_http_req_set_data.adoc new file mode 100644 index 00000000..005106a0 --- /dev/null +++ b/docs/man/nng_http_req_set_data.adoc @@ -0,0 +1,62 @@ += nng_http_req_set_data(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_req_set_data - set HTTP request body + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +int nng_http_req_set_data(nng_http_req *req, const void *body, size_t size); +----------- + +== DESCRIPTION + +The `nng_http_req_set_data()` sets the HTTP body associated with +the request _req_ to _body_, and the size of the body to _size_. +This body data will be automatically sent with the request when it +is sent using <<nng_http_conn_write_req#,nni_http_conn_write_req(3)>>. + +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 <<nng_http_req_copy_data#,nng_http_req_copy_data(3)>>. + +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 + +<<nng_http_conn_write_req#,nng_http_conn_write_req(3)>>, +<<nng_http_req_alloc#,nng_http_req_alloc(3)>>, +<<nng_http_req_copy_data#,nng_http_req_copy_data(3)>>, +<<nng_http_req_set_header#,nng_http_req_set_header(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_req_set_header.adoc b/docs/man/nng_http_req_set_header.adoc new file mode 100644 index 00000000..8d125c4a --- /dev/null +++ b/docs/man/nng_http_req_set_header.adoc @@ -0,0 +1,55 @@ += nng_http_req_set_header(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_req_set_header - set HTTP request header + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +int nng_http_req_set_header(nng_http_req *req, const char *key, + const char *val); +----------- + +== DESCRIPTION + +The `nng_http_req_set_header()` sets the HTTP header for the request +_req_ and the _key_ to the _val_. The _key_ and _val_ are copied. +Any previous header with the same _key_ is replaced. + +TIP: See <<nng_http_req_add_header#,nng_http_req_add_header(3)>> 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 + +<<nng_http_req_alloc#,nng_http_req_alloc(3)>>, +<<nng_http_req_add_header#,nng_http_req_add_header(3)>>, +<<nng_http_req_del_header#,nng_http_req_del_header(3)>>, +<<nng_http_req_get_header#,nng_http_req_get_header(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_req_set_method.adoc b/docs/man/nng_http_req_set_method.adoc new file mode 100644 index 00000000..76a6a18d --- /dev/null +++ b/docs/man/nng_http_req_set_method.adoc @@ -0,0 +1,50 @@ += nng_http_req_set_method(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_req_set_method - set HTTP request method + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +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 + +<<nng_http_req_alloc#,nng_http_req_alloc(3)>>, +<<nng_http_req_get_method#,nng_http_req_get_method(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_req_set_uri.adoc b/docs/man/nng_http_req_set_uri.adoc new file mode 100644 index 00000000..9431b1da --- /dev/null +++ b/docs/man/nng_http_req_set_uri.adoc @@ -0,0 +1,55 @@ += nng_http_req_set_uri(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_req_set_uri - set HTTP request URI + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +int nng_http_req_set_uri(nng_http_req *req, const char *uri); +----------- + +== DESCRIPTION + +The `nng_http_req_set_uri()` sets the Request-URI associated with +the request _req_ to _uri_. The _uri_ should contain precisely the +string that will be sent to the HTTP server in the request, including +any query information or fragment. + +A local copy of the _uri_ is made in the request _req_. + +NOTE: No validation or canonicalization of the _uri_ is performed. + +TIP: The <<nng_url_parse#,nng_url_parse(3)>> 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 + +<<nng_http_req_alloc#,nng_http_req_alloc(3)>>, +<<nng_http_req_get_uri#,nng_http_req_get_uri(3)>>, +<<nng_url_parse#,nng_url_parse(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_req_set_version.adoc b/docs/man/nng_http_req_set_version.adoc new file mode 100644 index 00000000..969e8afa --- /dev/null +++ b/docs/man/nng_http_req_set_version.adoc @@ -0,0 +1,55 @@ += nng_http_req_set_version(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_req_set_version - set HTTP request protocol version + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +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 + +<<nng_http_req_alloc#,nng_http_req_alloc(3)>>, +<<nng_http_req_get_version#,nng_http_req_get_version(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_res_add_header.adoc b/docs/man/nng_http_res_add_header.adoc new file mode 100644 index 00000000..75a4f206 --- /dev/null +++ b/docs/man/nng_http_res_add_header.adoc @@ -0,0 +1,62 @@ += nng_http_res_add_header(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_res_add_header - add HTTP response header + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +int nng_http_res_add_header(nng_http_res *res, const char *key, + const char *val); +----------- + +== DESCRIPTION + +The `nng_http_res_add_header()` adds an HTTP header for the response +_res_ and the _key_ to the _val_. The _key_ and _val_ are copied. + +If a header with the value of _key_ already exists, then a comma +and whitespace separate are appended to it, followed by _val_. + +If no such header already exists, then one is created with the value _val_. + +TIP: The HTTP specification requires that duplicate headers be treated +identically to a single header with multiple comma-delimited values. + +TIP: See <<nng_http_res_set_header#,nng_http_res_set_header(3)>> 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 + +<<nng_http_res_alloc#,nng_http_res_alloc(3)>>, +<<nng_http_res_del_header#,nng_http_res_del_header(3)>>, +<<nng_http_res_get_header#,nng_http_res_get_header(3)>>, +<<nng_http_res_set_header#,nng_http_res_set_header(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_res_alloc.adoc b/docs/man/nng_http_res_alloc.adoc new file mode 100644 index 00000000..9de3d012 --- /dev/null +++ b/docs/man/nng_http_res_alloc.adoc @@ -0,0 +1,64 @@ += nng_http_res_alloc(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_res_alloc - allocate HTTP response structure + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +int nng_http_res_alloc(nng_http_res **resp); +----------- + +== DESCRIPTION + +The `nng_http_res_alloc()` function allocates a new HTTP response structure +and stores a pointer to it in __resp__. The response will be initialized +with status code 200 (`NNG_HTTP_STATUS_OK`), and a reason phrase of "OK", +and HTTP protocol version "HTTP/1.1". + +TIP: When an error response is needed, consider using +<<nng_http_res_alloc_error#,nng_http_res_alloc_error(3)>> 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 + +<<nng_http_conn_read_res#,nng_http_conn_read_res(3)>>, +<<nng_http_conn_write_res#,nng_http_conn_write_res(3)>>, +<<nng_http_req_alloc#,nng_http_req_alloc(3)>>, +<<nng_http_res_alloc_errror#,nng_http_res_alloc_error(3)>>, +<<nng_http_res_add_header#,nng_http_res_add_header(3)>>, +<<nng_http_res_copy_data#,nng_http_res_copy_data(3)>>, +<<nng_http_res_del_header#,nng_http_res_del_header(3)>>, +<<nng_http_res_free#,nng_http_res_free(3)>>, +<<nng_http_res_get_header#,nng_http_res_get_header(3)>>, +<<nng_http_res_get_reason#,nng_http_res_get_reason(3)>>, +<<nng_http_res_get_status#,nng_http_res_get_status(3)>>, +<<nng_http_res_get_version#,nng_http_res_get_version(3)>>, +<<nng_http_res_set_data#,nng_http_res_set_data(3)>>, +<<nng_http_res_set_reason#,nng_http_res_set_reason(3)>>, +<<nng_http_res_set_status#,nng_http_res_set_status(3)>>, +<<nng_http_res_set_version#,nng_http_res_set_version(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_res_alloc_error.adoc b/docs/man/nng_http_res_alloc_error.adoc new file mode 100644 index 00000000..720871b1 --- /dev/null +++ b/docs/man/nng_http_res_alloc_error.adoc @@ -0,0 +1,54 @@ += nng_http_res_alloc_error(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_res_alloc_error - allocate HTTP error response + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +int nng_http_res_alloc_error(nng_http_res **resp, uint16_t status); +----------- + +== DESCRIPTION + +The `nng_http_res_alloc_error()` function allocates a new HTTP response structure +and stores a pointer to it in __resp__. The response will be initialized +with the status code _status_, a corresponding reason phrase, and +a simple HTML page containing the same information will be generated and +attached to the response. (Relevant HTTP headers will be set as well, +such as `Content-Type` and `Content-Length`.) The HTTP protocol version +is also set to "HTTP/1.1". + +TIP: This is the simplest way to generate an error response. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient free memory exists to allocate a message. +`NNG_ENOTSUP`:: HTTP support not configured. + +== SEE ALSO + +<<nng_http_res_alloc#,nng_http_res_alloc(3)>>, +<<nng_http_res_free#,nng_http_res_free(3)>>, +<<nng_http_res_set_reason#,nng_http_res_set_reason(3)>>, +<<nng_http_res_set_status#,nng_http_res_set_status(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_res_copy_data.adoc b/docs/man/nng_http_res_copy_data.adoc new file mode 100644 index 00000000..56d10222 --- /dev/null +++ b/docs/man/nng_http_res_copy_data.adoc @@ -0,0 +1,60 @@ += nng_http_res_copy_data(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_res_copy_data - copy HTTP response body + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +int nng_http_res_copy_data(nng_http_res *res, const void *body, size_t size); +----------- + +== DESCRIPTION + +The `nng_http_res_copy_data()` makes a copy of _body_ (of size __size__) +and sets the HTTP body for the response _res_ to it. The copy will be +deallocated automatically when _res_ is freed. + +The copied body data will be automatically sent with the response when it +is sent using <<nng_http_conn_write_res#,nni_http_conn_write_res(3)>>. + +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 +<<nng_http_res_set_data#,nng_http_res_set_data(3)>> 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 + +<<nng_http_conn_write_res#,nng_http_conn_write_res(3)>>, +<<nng_http_res_alloc#,nng_http_res_alloc(3)>>, +<<nng_http_res_set_data#,nng_http_res_set_data(3)>>, +<<nng_http_res_set_header#,nng_http_res_set_header(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_res_del_header.adoc b/docs/man/nng_http_res_del_header.adoc new file mode 100644 index 00000000..82a2387e --- /dev/null +++ b/docs/man/nng_http_res_del_header.adoc @@ -0,0 +1,50 @@ += nng_http_res_set_header(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_res_set_header - set HTTP response header + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +int nng_http_res_set_header(nng_http_res *res, const char *key); +----------- + +== 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 + +<<nng_http_res_alloc#,nng_http_res_alloc(3)>>, +<<nng_http_res_add_header#,nng_http_res_add_header(3)>>, +<<nng_http_res_del_header#,nng_http_res_del_header(3)>>, +<<nng_http_res_get_header#,nng_http_res_get_header(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_res_free.adoc b/docs/man/nng_http_res_free.adoc new file mode 100644 index 00000000..ade3e151 --- /dev/null +++ b/docs/man/nng_http_res_free.adoc @@ -0,0 +1,42 @@ += nng_http_res_free(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_res_free - free HTTP response structure + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +void nng_http_res_free(nng_http_res *req); +----------- + +== DESCRIPTION + +The `nng_http_res_free()` function deallocates the HTTP response structure +_res_ entirely. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_http_res_alloc#,nng_http_req_alloc(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_res_get_header.adoc b/docs/man/nng_http_res_get_header.adoc new file mode 100644 index 00000000..0d3afbd6 --- /dev/null +++ b/docs/man/nng_http_res_get_header.adoc @@ -0,0 +1,50 @@ += nng_http_res_get_header(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_res_get_header - return HTTP response header + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +const char *nng_http_res_get_header(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 + +<<nng_http_res_alloc#,nng_http_res_alloc(3)>>, +<<nng_http_res_add_header#,nng_http_res_add_header(3)>>, +<<nng_http_res_set_header#,nng_http_res_set_header(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_res_get_reason.adoc b/docs/man/nng_http_res_get_reason.adoc new file mode 100644 index 00000000..7fe1f079 --- /dev/null +++ b/docs/man/nng_http_res_get_reason.adoc @@ -0,0 +1,46 @@ += nng_http_res_get_reason(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_res_get_reason - return HTTP response reason + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +const char *nng_http_res_get_reason(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 +<<nng_http_res_get_status#,nng_http_res_get_status(3)>>. + +== RETURN VALUES + +Reason as a string. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_http_res_alloc#,nng_http_res_alloc(3)>>, +<<nng_http_res_get_status#,nng_http_res_get_status(3)>>, +<<nng_http_res_set_reason#,nng_http_res_set_reason(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_res_get_status.adoc b/docs/man/nng_http_res_get_status.adoc new file mode 100644 index 00000000..2056e2ce --- /dev/null +++ b/docs/man/nng_http_res_get_status.adoc @@ -0,0 +1,116 @@ += nng_http_res_get_status(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_res_get_status - return HTTP status code + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +uint16_t nng_http_res_get_status(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 +<<nng_http_res_get_reason#,nng_http_res_get_reason(3)>>. + +== RETURN VALUES + +HTTP status code. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_http_res_alloc#,nng_http_res_alloc(3)>>, +<<nng_http_res_get_reason#,nng_http_res_get_reason(3)>>, +<<nng_http_res_set_status#,nng_http_res_set_status(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_res_get_version.adoc b/docs/man/nng_http_res_get_version.adoc new file mode 100644 index 00000000..199bd95c --- /dev/null +++ b/docs/man/nng_http_res_get_version.adoc @@ -0,0 +1,44 @@ += nng_http_res_get_version(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_res_get_version - return HTTP response protocol version + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +const char *nng_http_res_get_version(nng_http_res *res); +----------- + +== DESCRIPTION + +The `nng_http_res_get_version()` returns a string representing the HTTP +protocol version associated with the request _res_, such as "HTTP/1.1". + + +== RETURN VALUES + +Response version as a string. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_http_res_alloc#,nng_http_res_alloc(3)>>, +<<nng_http_res_set_version#,nng_http_res_set_version(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_res_set_data.adoc b/docs/man/nng_http_res_set_data.adoc new file mode 100644 index 00000000..aae0d076 --- /dev/null +++ b/docs/man/nng_http_res_set_data.adoc @@ -0,0 +1,62 @@ += nng_http_res_set_data(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_res_set_data - set HTTP response body + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +int nng_http_res_set_data(nng_http_res *res, const void *body, size_t size); +----------- + +== DESCRIPTION + +The `nng_http_res_set_data()` sets the HTTP body associated with +the response _res_ to _body_, and the size of the body to _size_. +This body data will be automatically sent with the response when it +is sent using <<nng_http_conn_write_res#,nni_http_conn_write_res(3)>>. + +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 <<nng_http_res_copy_data#,nng_http_res_copy_data(3)>>. + +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 + +<<nng_http_conn_write_res#,nng_http_conn_write_res(3)>>, +<<nng_http_res_alloc#,nng_http_res_alloc(3)>>, +<<nng_http_res_copy_data#,nng_http_res_copy_data(3)>>, +<<nng_http_res_set_header#,nng_http_res_set_header(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_res_set_header.adoc b/docs/man/nng_http_res_set_header.adoc new file mode 100644 index 00000000..7c2a649e --- /dev/null +++ b/docs/man/nng_http_res_set_header.adoc @@ -0,0 +1,55 @@ += nng_http_res_set_header(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_res_set_header - set HTTP response header + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +int nng_http_res_set_header(nng_http_res *res, const char *key, + const char *val); +----------- + +== DESCRIPTION + +The `nng_http_res_set_header()` sets the HTTP header for the response +_res_ and the _key_ to the _val_. The _key_ and _val_ are copied. +Any previous header with the same _key_ is replaced. + +TIP: See <<nng_http_res_add_header#,nng_http_res_add_header(3)>> 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 + +<<nng_http_res_alloc#,nng_http_res_alloc(3)>>, +<<nng_http_res_add_header#,nng_http_res_add_header(3)>>, +<<nng_http_res_del_header#,nng_http_res_del_header(3)>>, +<<nng_http_res_get_header#,nng_http_res_get_header(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_res_set_reason.adoc b/docs/man/nng_http_res_set_reason.adoc new file mode 100644 index 00000000..150b8166 --- /dev/null +++ b/docs/man/nng_http_res_set_reason.adoc @@ -0,0 +1,54 @@ += nng_http_res_set_reason(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_res_set_reason - set HTTP response reason + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +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 +<<nng_http_res_set_status#,nng_http_res_set_status(3)>>). + +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 + +<<nng_http_res_alloc#,nng_http_res_alloc(3)>>, +<<nng_http_res_get_reason#,nng_http_req_get_reason(3)>>, +<<nng_http_res_set_status#,nng_http_req_set_status(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_res_set_status.adoc b/docs/man/nng_http_res_set_status.adoc new file mode 100644 index 00000000..f5e45cc4 --- /dev/null +++ b/docs/man/nng_http_res_set_status.adoc @@ -0,0 +1,122 @@ += nng_http_res_set_status(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_res_set_status - set HTTP response status + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +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 +<<nng_http_res_set_reason#,nng_http_set_reason(3)>>. 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 + +<<nng_http_res_alloc#,nng_http_res_alloc(3)>>, +<<nng_http_res_get_status#,nng_http_req_get_status(3)>>, +<<nng_http_res_set_reason#,nng_http_req_set_reason(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_res_set_version.adoc b/docs/man/nng_http_res_set_version.adoc new file mode 100644 index 00000000..cb8f29a7 --- /dev/null +++ b/docs/man/nng_http_res_set_version.adoc @@ -0,0 +1,55 @@ += nng_http_res_set_version(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_res_set_version - set HTTP response protocol version + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.h> + +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 + +<<nng_http_res_alloc#,nng_http_res_alloc(3)>>, +<<nng_http_req_get_version#,nng_http_req_get_version(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_http_server_add_handler.adoc b/docs/man/nng_http_server_add_handler.adoc new file mode 100644 index 00000000..333187a7 --- /dev/null +++ b/docs/man/nng_http_server_add_handler.adoc @@ -0,0 +1,57 @@ += nng_http_server_add_handler(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_server_add_handler - add HTTP server handler + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.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)>> diff --git a/docs/man/nng_http_server_del_handler.adoc b/docs/man/nng_http_server_del_handler.adoc new file mode 100644 index 00000000..6dd72d8a --- /dev/null +++ b/docs/man/nng_http_server_del_handler.adoc @@ -0,0 +1,48 @@ += nng_http_server_del_handler(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_server_del_handler - delete HTTP server handler + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.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)>> diff --git a/docs/man/nng_http_server_get_tls.adoc b/docs/man/nng_http_server_get_tls.adoc new file mode 100644 index 00000000..c19fb4d9 --- /dev/null +++ b/docs/man/nng_http_server_get_tls.adoc @@ -0,0 +1,50 @@ += nng_http_server_get_tls(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_server_get_tls - get HTTP server TLS configuration + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.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)>> diff --git a/docs/man/nng_http_server_hold.adoc b/docs/man/nng_http_server_hold.adoc new file mode 100644 index 00000000..61e5b068 --- /dev/null +++ b/docs/man/nng_http_server_hold.adoc @@ -0,0 +1,62 @@ += nng_http_server_hold(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_server_hold - get and hold HTTP server instance + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.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)>> diff --git a/docs/man/nng_http_server_release.adoc b/docs/man/nng_http_server_release.adoc new file mode 100644 index 00000000..16c28227 --- /dev/null +++ b/docs/man/nng_http_server_release.adoc @@ -0,0 +1,53 @@ += nng_http_server_release(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_server_release - release HTTP server instance + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.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)>> diff --git a/docs/man/nng_http_server_set_tls.adoc b/docs/man/nng_http_server_set_tls.adoc new file mode 100644 index 00000000..50039e49 --- /dev/null +++ b/docs/man/nng_http_server_set_tls.adoc @@ -0,0 +1,60 @@ += nng_http_server_set_tls(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_server_set_tls - set HTTP server TLS configuration + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.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 +_cfg_. + +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)>> diff --git a/docs/man/nng_http_server_start.adoc b/docs/man/nng_http_server_start.adoc new file mode 100644 index 00000000..4b7b1a4f --- /dev/null +++ b/docs/man/nng_http_server_start.adoc @@ -0,0 +1,50 @@ += nng_http_server_start(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_server_start - start HTTP server + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.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)>> diff --git a/docs/man/nng_http_server_stop.adoc b/docs/man/nng_http_server_stop.adoc new file mode 100644 index 00000000..8b2e0884 --- /dev/null +++ b/docs/man/nng_http_server_stop.adoc @@ -0,0 +1,44 @@ += nng_http_server_stop(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_http_server_stop - stop HTTP server + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> +#include <nng/supplemental/http/http.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)>> diff --git a/docs/man/nng_inproc.adoc b/docs/man/nng_inproc.adoc new file mode 100644 index 00000000..c0dc270d --- /dev/null +++ b/docs/man/nng_inproc.adoc @@ -0,0 +1,84 @@ += nng_inproc(7) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_inproc - intra-process transport for nng + +== SYNOPSIS + +[source,c] +---------- +#include <nng/transport/inproc/inproc.h> + +int nng_inproc_register(void); +---------- + +== DESCRIPTION + +The _nng_inproc_ transport provides communication support between +_nng_ sockets within the same process. This may be used as an alternative +to slower transports when data must be moved within the same process. + +This transport tries hard to avoid copying data, and thus is very +light-weight. + +Registration +~~~~~~~~~~~~ + +The _inproc_ transport is generally built-in to the _nng_ core, so +no extra steps to use it should be necessary. + +=== URI Format + +This transport uses URIs using the scheme `inproc://`, followed by +an arbitrary string of text, terminated by a `NUL` byte. + +Multiple URIs can be used within the +same application, and they will not interfere with one another. + +Two applications may also use the same URI without interfering with each +other, and they will be unable to communicate with each other using +that URI. + +=== Socket Address + +When using an `nng_sockaddr` structure, the actual structure is of type +`struct nng_sockaddr_inproc`. This type has the following definition: + +[source,c] +-------- +#define NNG_AF_INPROC 1 <1> +#define NNG_MAXADDRLEN 128 + +typedef nng_sockaddr_inproc { + // <2> + uint16_t sa_family; // must be NNG_AF_INPROC + char sa_path[NNG_MAXADDRLEN]; // arbitrary "path" + // +} +-------- +<1> The values of these macros may change, so applications +should avoid depending upon their values and instead use them symbolically. +<2> Other members may be present, but only those listed here +are suitable for application use. + +The `sa_family` member will have the value `NNG_AF_INPROC`. +The `sa_path` member is an ASCIIZ string, and may contain any characters, +terminated by a `NUL` byte. + +=== Transport Options + +The _inproc_ transport has no special options. + +== SEE ALSO + +<<nng#,nng(7)>> diff --git a/docs/man/nng_ipc.adoc b/docs/man/nng_ipc.adoc new file mode 100644 index 00000000..e212cf0f --- /dev/null +++ b/docs/man/nng_ipc.adoc @@ -0,0 +1,83 @@ += nng_ipc(7) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_ipc - IPC transport for nng + +== SYNOPSIS + +[source,c] +---------- +#include <nng/transport/ipc/ipc.h> + +int nng_ipc_register(void); +---------- + +== DESCRIPTION + +The _nng_ipc_ transport provides communication support between +_nng_ sockets within different processes on the same host. For POSIX +platforms, this is implemented using UNIX domain sockets. For Windows, +this is implemented using Windows Named Pipes. Other platforms may +have different implementation strategies. + +// We need to insert a reference to the nanomsg RFC. + +=== Registration + +The _ipc_ transport is generally built-in to the _nng_ core, so +no extra steps to use it should be necessary. + +=== URI Format + +This transport uses URIs using the scheme `ipc://`, followed by +a an absolute path name in the file system where the socket or named pipe +should be created. + +TIP: On Windows, all names are prefixed by `\.\pipe\` and do not +occupy the normal file system. On POSIX platforms, the path is +taken literally, and is relative to the root directory. + +=== Socket Address + +When using an `nng_sockaddr` structure, the actual structure is of type +`nng_sockaddr_ipc`. This is a `struct` type with the following definition: + +[source,c] +-------- +#define NNG_AF_IPC 2 <1> +#define NNG_MAXADDRLEN 128 + +typedef struct { + // ... <2> + uint16_t sa_family; // must be NNG_AF_IPC + char sa_path[NNG_MAXADDRLEN]; // arbitrary "path" + // ... +} nng_sockaddr_ipc; +-------- +<1> The values of these macros may change, so applications +should avoid depending upon their values and instead use them symbolically. +<2> Other members may be present, but only those listed here +are suitable for application use. + +The `sa_family` member will have the value `NNG_AF_IPC`. +The `sa_path` member is an ASCIIZ string, and may contain any legal +path name (platform-dependent), terminated by a `NUL` byte. + +=== Transport Options + +The _ipc_ transport has no special +options.footnote:[Options for security attributes and credentials are planned.] + +== SEE ALSO + +<<nng#,nng(7)>> diff --git a/docs/man/nng_listen.adoc b/docs/man/nng_listen.adoc new file mode 100644 index 00000000..4e403f3f --- /dev/null +++ b/docs/man/nng_listen.adoc @@ -0,0 +1,80 @@ += nng_listen(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_listen - create and start listener + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_listen(nng_socket s, const char *url, nng_listener *lp, int flags); +----------- + +== DESCRIPTION + +The `nng_listener()` function creates a newly initialized +listener, associated with socket _s_, and configured to listen at the +address specified by _url_. If the value of _lp_ is not `NULL`, then +the newly created listener is stored at the address indicated by _lp_. + +Listeners are used to accept connections initiated by remote dialers. An +incoming connection generally results in a pipe being created and attached +to the socket _s_. Unlike dialers, listeners generally can create many +pipes, which may be open concurrently. + +TIP: While it is convenient to think of listeners as "servers", the relationship +between the listener or dialer is orthogonal to any server or client status +that might be associated with a given protocol. For example, a <<nng_req#,REQ>> +socket might have associated dialers, but might also have associated listeners. +It may even have some of each at the same time! + +Normally, the act of "binding" to the address indicated by _url_ is done +synchronously, including any necessary name resolution. As a result, +a failure, such as if the address is already in use, will be returned +immediately. However, if the special value `NNG_FLAG_NONBLOCK` is +supplied in _flags_, then this is done asynchronously; furthermore any +failure to bind will be periodically reattempted in the background. + +TIP: While `NNG_FLAG_NONBLOCK` can help an application be more resilient, +it also generally makes diagnosing failures somewhat more difficult. + +Because the listener is started immediately, it is generally not possible +to apply extra configuration; if that is needed applications should consider +using <<nng_listener_create#,nng_listener_create(3)>> and +<<nng_listener_start#,nng_listener_start(3)>> instead. + +The created listener will continue to accept new connections, associating +their pipes with the socket, until either it or the socket _s_ is closed. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_EADDRINUSE`:: The address specified by _url_ is already in use. +`NNG_EADDRINVAL`:: An invalid _url_ was specified. +`NNG_ECLOSED`:: The socket _s_ is not open. +`NNG_EINVAL`:: An invalid set of _flags_ was specified. +`NNG_ENOMEM`:: Insufficient memory is available. + +== SEE ALSO + +<<nng_dial#,nng_dial(3)>>, +<<nng_listener_close#,nng_listener_close(3)>>, +<<nng_listener_create#,nng_listener_create(3)>> +<<nng_listener_start#,nng_listener_start(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_listener_close.adoc b/docs/man/nng_listener_close.adoc new file mode 100644 index 00000000..396a354d --- /dev/null +++ b/docs/man/nng_listener_close.adoc @@ -0,0 +1,52 @@ += nng_listener_close(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_listener_close - close listener + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_listener_close(nng_listener l); +----------- + +== DESCRIPTION + +The `nng_listener_close()` function closes the listener _l_. +This also closes any pipes that have been created by the listener. + +Once this function returns, the listener _l_ and any of its resources +are deallocated. Therefore it is an error to attempt to access _l_ +after this function has returned. (Attempts to do so will result in +`NNG_ECLOSED` errors.) + +Listeners are implicitly closed when the socket they are associated with +is closed. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ECLOSED`:: Parameter _l_ does not refer to an open listener. + +== SEE ALSO + +<<nng_close#,nng_close(3)>>, +<<nng_listen#,nng_listen(3)>>, +<<nng_listener_create#,nng_listener_create(3)>> +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_listener_create.adoc b/docs/man/nng_listener_create.adoc new file mode 100644 index 00000000..0ddcd685 --- /dev/null +++ b/docs/man/nng_listener_create.adoc @@ -0,0 +1,72 @@ += nng_listener_create(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_listener_create - create listener + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_listener_create(nng_listener *listenerp, nng_socket s, const char *url); +----------- + +== DESCRIPTION + +The `nng_listener_create()` function creates a newly initialized +listener, associated with socket _s_, and configured to listen at the +address specified by _url_, and stores a pointer to at the location +referenced by _listenerp_. + +Listeners are used to accept connections initiated by remote dialers. An +incoming connection generally results in a pipe being created and attached +to the socket _s_. Unlike dialers, listeners generally can create many +pipes, which may be open concurrently. + +TIP: While it is convenient to think of listeners as "servers", the relationship +between the listener or dialer is orthogonal to any server or client status +that might be associated with a given protocol. For example, a <<nng_req#,REQ>> +socket might have associated dialers, but might also have associated listeners. +It may even have some of each at the same time! + +The listener is not started, but may be further configured with +the <<nng_listener_setopt#,nng_listener_setopt(3)>> family of +functions. + +Once it is fully configured, the listener may be started using the +<<nng_listener_start#,nng_listener_start(3)>> function. + +TIP: If no specific configuration is required, consider using the +simpler <<nng_listen#,nng_listen(3)>> function instead. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_EADDRINVAL`:: An invalid _url_ was specified. +`NNG_ECLOSED`:: The socket _s_ is not open. +`NNG_ENOMEM`:: Insufficient memory is available. + +== SEE ALSO + +<<nng_dialer_create#,nng_dialer_create(3)>> +<<nng_listen#,nng_listen(3)>>, +<<nng_listener_close#,nng_listener_close(3)>>, +<<nng_listener_getopt#,nng_listener_getopt(3)>>, +<<nng_listener_setopt#,nng_listener_setopt(3)>>, +<<nng_listener_start#,nng_listener_start(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_listener_getopt.adoc b/docs/man/nng_listener_getopt.adoc new file mode 100644 index 00000000..1218feeb --- /dev/null +++ b/docs/man/nng_listener_getopt.adoc @@ -0,0 +1,106 @@ += nng_listener_getopt(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_listener_getopt - get listener option + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_listener_getopt(nng_listener l, const char *opt, void *val, + size_t *valszp); +int nng_listener_getopt_int(nng_listener l, const char *opt, int *ivalp); +int nng_listener_getopt_ms(nng_listener l, const char *opt, nng_duration *durp); +int nng_listener_getopt_ptr(nng_listener l, const char *opt, void **ptr); +int nng_listener_setopt_size(nng_listener l, const char *opt, size_t *zp); +int nng_listener_getopt_uint64(nng_listener l, const char *opt, uint64_t *u64p); +----------- + +== DESCRIPTION + +The `nng_listener_getopt()` functions are used to retrieve option values for +the listener _l_. The actual options that may be retrieved in this way +vary, and are documented in the <<nng_getopt#,nng_getopt(3)>> manual. +Additionally some transport-specific options are documented with the +transports themselves. + +In all of these forms, the option _opt_ is retrieved from the listener _l_. + +The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself. + +The first form of this function, `nng_listener_getopt()`, can be used to +retrieve the value of any option. It is untyped. The caller must store +a pointer to a buffer to receive the value in _val_, and the size of the +buffer shall be stored at the location referenced by _valszp_. + +When the function returns, the actual size of the data copied (or that +would have been copied if sufficient space were present) is stored at +the location referened by _valszp_. If the caller's buffer is not large +enough to hold the entire object, then the copy is truncated. Therefore +the caller should validate that the returned size in _valszp_ does not +exceed the original buffer size to check for truncation. + +It is acceptable to pass `NULL` for _val_ if the value in _valszp_ is zero. +This can be used to determine the size of the buffer needed to receive +the object. + +Generally, it will be easier to use one of the typed forms instead. Note +however that no validation that the option is actually of the associated +type is performed, so the caller must take care to use the *correct* typed +form. + +The second form, `nng_listener_getopt_int()`, +is for options which take an integer (or boolean). The value will +be stored at _ivalp_. For booleans the value will be eiher 0 (false) or 1 (true). + +The third form, `nng_listener_getopt_ms()`, is used to retrieve time durations +(such as timeouts), stored in _durp_ as a number of milliseconds. +(The special value `NNG_DUR_INFINITE` means an infinite amount of time, and +the special value `NNG_DUR_DEFAULT` means a context-specific default.) + +The fourth form, `nng_listener_getopt_ptr()`, is used to retrieve a +pointer _ptr_ to structured data. The data referenced by _ptr_ is +generally managed using other functions. +Note that this form is somewhat special in that the object is generally +not copied, but instead the *pointer* to the object is copied. + +The fifth form, `nng_listener_getopt_size()`, is used to retrieve a size +into the pointer _zp_, typically for buffer sizes, message maximum sizes, and +similar options. + +The sixth form, `nng_listener_getopt_uint64()`, is used to retrieve a +64-bit unsigned value into the value referenced by _u64p_. +This is typically used for options +related to identifiers, network numbers, and similar. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ECLOSED`:: Parameter _l_ does not refer to an open listener. +`NNG_ENOTSUP`:: The option _opt_ is not supported. +`NNG_EWRITEONLY`:: The option _opt_ is write-only. + +== SEE ALSO + +<<nng_listen#,nng_listen(3)>>, +<<nng_listener_create#,nng_listener_create(3)>> +<<nng_listener_setopt#,nng_listener_setopt(3)>> +<<nng_getopt#,nng_getopt(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_listener_setopt.adoc b/docs/man/nng_listener_setopt.adoc new file mode 100644 index 00000000..c231070e --- /dev/null +++ b/docs/man/nng_listener_setopt.adoc @@ -0,0 +1,104 @@ += nng_listener_setopt(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_listener_setopt - set listener option + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_listener_setopt(nng_listener l, const char *opt, const void *val, + size_t valsz); +int nng_listener_setopt_int(nng_listener l, const char *opt, int ival); +int nng_listener_setopt_ms(nng_listener l, const char *opt, nng_duration dur); +int nng_listener_setopt_ptr(nng_listener l, const char *opt, void *ptr); +int nng_listener_setopt_size(nng_listener l, const char *opt, size_t z); +int nng_listener_setopt_string(nng_listener l, const char *opt, const char *str); +int nng_listener_setopt_uint64(nng_listener l, const char *opt, uint64_t u64); +----------- + +== DESCRIPTION + +The `nng_listener_setopt()` functions are used to configure options for +the listener _l_. The actual options that may be configured in this way +vary, and are documented in the <<nng_setopt#,nng_setopt(3)>> manual. +Additionally some transport-specific options are documented with the +transports themselves. + +In all of these forms, the option _opt_ is configured on the listener _l_. + +The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself. + +The first form of this function, `nng_listener_setopt()`, can be used to +configure any arbitrary data. +The _val_ pointer addresses the data to copy, and _valsz_ is the +size of the objected located at _val_. + +Generally, it will be easier to use one of the typed forms instead. + +The second form, `nng_listener_setopt_int()`, +is for options which take an integer (or boolean). The _ival_ +is passed to the option. For booleans pass either 0 (false) or 1 (true). + +The third form, `nng_listener_setopt_ms()`, is used to configure time durations +(such as timeouts). +The duration _dur_ is an integer number of milliseconds. (The special value +`NNG_DUR_INFINITE` means an infinite amount of time.) + +The fourth form, `nng_listener_setopt_ptr()`, is used to pass a +pointer _ptr_ to structured data. The data referenced by _ptr_ is +generally managed by other functions. +For example, TLS configuration objects +(<<nng_tls_config_alloc#,nng_tls_config_alloc(3)>>) can be passed this way. +Note that this form is somewhat special in that the object is generally +not copied, but instead the *pointer* to the object is copied. + +The fifth form, `nng_listener_setopt_size()`, is used to pass a size +specified by _z_, typically for buffer sizes, message maximum sizes, and +similar options. + +The sixth form, `nng_listener_setopt_string()`, is used to pass a string +_str_. Strings passed this way must be legal UTF-8 or ASCII strings, terminated +with a `NUL` (`\0`) byte. (Other constraints may apply as well, see the +documentation for _opt_ for details.) + +The seventh form, `nng_listener_setopt_uint64()`, is used to configure +the 64-bit unsigned value in _u64_. This is typically used for options +related to identifiers, network numbers, and similar. + +NOTE: Once a listener has started, it is generally not possible to change +it's configuration. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ECLOSED`:: Parameter _l_ does not refer to an open listener. +`NNG_EINVAL`:: The value being passed is invalid. +`NNG_ENOTSUP`:: The option _opt_ is not supported. +`NNG_EREADONLY`:: The option _opt_ is read-only. +`NNG_ESTATE`:: The listener _l_ is already started. + +== SEE ALSO + +<<nng_listen#,nng_listen(3)>>, +<<nng_listener_create#,nng_listener_create(3)>> +<<nng_listener_getopt#,nng_listener_getopt(3)>> +<<nng_setopt#,nng_setopt(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_listener_start.adoc b/docs/man/nng_listener_start.adoc new file mode 100644 index 00000000..42175598 --- /dev/null +++ b/docs/man/nng_listener_start.adoc @@ -0,0 +1,61 @@ += nng_listener_start(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_listener_start - start listener + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_listener_start(nng_listener l, int flags); +----------- + +== DESCRIPTION + +The `nng_listener_start()` function starts the listener _l_. + +This causes the listener to bind to the address it was created with, +and to start accepting connections from remote +dialers. Each new connection results in a pipe, which will be attached +to the listener's socket. + +Normally, the act of "binding" to it's address is done +synchronously, including any necessary name resolution. As a result, +a failure, such as if the address is already in use, will be returned +immediately. However, if the special value `NNG_FLAG_NONBLOCK` is +supplied in _flags_, then this is done asynchronously; furthermore any +failure to bind will be periodically reattempted in the background. + +TIP: While `NNG_FLAG_NONBLOCK` can help an application be more resilient, +it also generally makes diagnosing failures somewhat more difficult. + +Once a listener has started, it is generally not possible to change +it's configuration. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ECLOSED`:: Parameter _l_ does not refer to an open listener. +`NNG_ESTATE`:: The listener _l_ is already started. + +== SEE ALSO + +<<nng_listen#,nng_listen(3)>>, +<<nng_listener_create#,nng_listener_create(3)>> +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_msg_alloc.adoc b/docs/man/nng_msg_alloc.adoc new file mode 100644 index 00000000..40f31552 --- /dev/null +++ b/docs/man/nng_msg_alloc.adoc @@ -0,0 +1,50 @@ += nng_msg_alloc(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_msg_alloc - allocate a message + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_msg_alloc(nng_msg **msgp, size_t size); +----------- + +== DESCRIPTION + +The `nng_msg_alloc()` function allocates a new message with body length _size_ +and stores the result in __msgp__. +Messages allocated with this function contain a body and optionally a header. +They are used with receive and transmit functions. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient free memory exists to allocate a message. + +== SEE ALSO + +<<nng_msg_free#,nng_msg_free(3)>>, +<<nng_msg_body#,nng_msg_body(3)>>, +<<nng_msg_dup#,nng_msg_dup(3)>>, +<<nng_msg_header#,nng_msg_header(3)>>, +<<nng_msg_header_len#,nng_msg_header_len(3)>>, +<<nng_msg_len#,nng_msg_len(3)>>, +<<nng_msg_realloc#,nng_msg_realloc(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_msg_append.adoc b/docs/man/nng_msg_append.adoc new file mode 100644 index 00000000..6bdf689d --- /dev/null +++ b/docs/man/nng_msg_append.adoc @@ -0,0 +1,52 @@ += nng_msg_append(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_msg_append, nng_msg_append_u32 - append to message body + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_msg_append(nng_msg *msg, const void *val, size_t size); +int nng_msg_append_u32(nng_msg *msg, uint32_t val32); +----------- + +== DESCRIPTION + +The `nng_msg_append()` and `nng_msg_append_u32()` functions append data to +the end of the body of message _msg_, reallocating it if necessary. +The first function appends _size_ bytes, copying them from _val_. The +second function appends the value _val32_ in network-byte order (big-endian). + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient free memory exists. + +== SEE ALSO + +<<nng_msg_alloc#,nng_msg_alloc(3)>>, +<<nng_msg_body#,nng_msg_body(3)>>, +<<nng_msg_chop#,nng_msg_chop(3)>>, +<<nng_msg_free#,nng_msg_free(3)>>, +<<nng_msg_insert#,nng_msg_insert(3)>>, +<<nng_msg_len#,nng_msg_len(3)>>, +<<nng_msg_realloc#,nng_msg_realloc(3)>>, +<<nng_msg_trim#,nng_msg_trim(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_msg_body.adoc b/docs/man/nng_msg_body.adoc new file mode 100644 index 00000000..507c0e0d --- /dev/null +++ b/docs/man/nng_msg_body.adoc @@ -0,0 +1,55 @@ += nng_msg_body(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_msg_body - return message body + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +void *nng_msg_body(nng_msg *msg); +----------- + +== DESCRIPTION + +The `nng_msg_body()` function returns a pointer to the start of the body +content of the message _msg_. + +NOTE: The value returned by this is invalidated by a call to any of the +functions that modify the message itself. Such functions are +<<nng_msg_free#,nng_msg_free(3)>>, <<nng_msg_realloc#,nng_msg_realloc(3)>>, +any of the <<nng_msg_trim#,nng_msg_trim(3)>>, +<<nng_msg_chop#,nng_msg_chop(3)>>, <<nng_msg_append#,nng_msg_append(3)>>, +or <<nng_msg_insert#,nng_msg_insert(3)>> variants. + +== RETURN VALUES + +Pointer to start of message body. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_msg_alloc#,nng_msg_alloc(3)>>, +<<nng_msg_append#,nng_msg_append(3)>>, +<<nng_msg_chop#,nng_msg_chop(3)>>, +<<nng_msg_free#,nng_msg_free(3)>>, +<<nng_msg_insert#,nng_msg_insert(3)>>, +<<nng_msg_len#,nng_msg_len(3)>>, +<<nng_msg_realloc#,nng_msg_realloc(3)>>, +<<nng_msg_trim#,nng_msg_trim(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_msg_chop.adoc b/docs/man/nng_msg_chop.adoc new file mode 100644 index 00000000..f2acff4b --- /dev/null +++ b/docs/man/nng_msg_chop.adoc @@ -0,0 +1,54 @@ += nng_msg_chop(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_msg_chop, nng_msg_chop_u32 - remove data from end of message body + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_msg_chop(nng_msg *msg, size_t size); +int nng_msg_chop_u32(nng_msg *msg, uint32_t *val32); +----------- + +== DESCRIPTION + +The `nng_msg_chop()` and `nng_msg_chop_u32()` functions remove data from +the end of the body of message _msg_. +The first function removes _size_ bytes. +The second function removes 4 bytes, and stores them in the value _val32_, +after converting them from network-byte order (big-endian) to native +byte order. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_EINVAL`:: The message body is too short to remove the requested data. + +== SEE ALSO + +<<nng_msg_alloc#,nng_msg_alloc(3)>>, +<<nng_msg_append#,nng_msg_append(3)>>, +<<nng_msg_body#,nng_msg_body(3)>>, +<<nng_msg_free#,nng_msg_free(3)>>, +<<nng_msg_insert#,nng_msg_insert(3)>>, +<<nng_msg_len#,nng_msg_len(3)>>, +<<nng_msg_realloc#,nng_msg_realloc(3)>>, +<<nng_msg_trim#,nng_msg_trim(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_msg_clear.adoc b/docs/man/nng_msg_clear.adoc new file mode 100644 index 00000000..aa6e8e64 --- /dev/null +++ b/docs/man/nng_msg_clear.adoc @@ -0,0 +1,41 @@ += nng_msg_clear(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_msg_clear - clear message body content + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +void nng_msg_clear(nng_msg *msg); +----------- + +== DESCRIPTION + +The `nng_msg_clear()` function resets the body length of _msg_ to zero. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_msg_alloc#,nng_msg_alloc(3)>>, +<<nng_msg_free#,nng_msg_free(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_msg_dup.adoc b/docs/man/nng_msg_dup.adoc new file mode 100644 index 00000000..426fba29 --- /dev/null +++ b/docs/man/nng_msg_dup.adoc @@ -0,0 +1,45 @@ += nng_msg_dup(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_msg_dup - duplicate a message + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_msg_dup(nng_msg **dup, nng_msg_t *orig); +----------- + +== DESCRIPTION + +The `nng_msg_dup()` makes a duplicate of the original message _orig_, and +saves the result in the location pointed by _dup_. The actual message +body and header content is copied, but the duplicate may contain a +different amount of unused space than the original message. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient free memory exists to duplicate a message. + +== SEE ALSO + +<<nng_msg_alloc#,nng_msg_alloc(3)>>, +<<nng_msg_free#,nng_msg_free(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_msg_free.adoc b/docs/man/nng_msg_free.adoc new file mode 100644 index 00000000..dd9c39c6 --- /dev/null +++ b/docs/man/nng_msg_free.adoc @@ -0,0 +1,41 @@ += nng_msg_free(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_msg_free - free a message + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +void nng_msg_free(nng_msg *msg); +----------- + +== DESCRIPTION + +The `nng_msg_free()` function deallocates the message _msg_ entirely. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_msg_alloc#,nng_msg_alloc(3)>>, +<<nng_msg_realloc#,nng_msg_realloc(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_msg_header.adoc b/docs/man/nng_msg_header.adoc new file mode 100644 index 00000000..7d85db5e --- /dev/null +++ b/docs/man/nng_msg_header.adoc @@ -0,0 +1,56 @@ += nng_msg_header(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_msg_header - return message header + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +void *nng_msg_header(nng_msg *msg); +----------- + +== DESCRIPTION + +The `nng_msg_header()` function returns a pointer to the start of the header +content of the message _msg_. + +NOTE: The message header contains protocol-specific header content. Most +applications should not need to access this content, but it is available +for raw mode sockets (set with the `NNG_OPT_RAW` option -- see +<<nng_setopt#,nng_setopt(3)>> for more details.) + +NOTE: The value returned by this is invalidated by a call to any of the +functions that modify the message or the header content. + +== RETURN VALUES + +Pointer to start of message header. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_msg_alloc#,nng_msg_alloc(3)>>, +<<nng_msg_body#,nng_msg_body(3)>>, +<<nng_msg_free#,nng_msg_free(3)>>, +<<nng_msg_header_append#,nng_msg_header_append(3)>>, +<<nng_msg_header_chop#,nng_msg_header_chop(3)>>, +<<nng_msg_header_insert#,nng_msg_header_insert(3)>> +<<nng_msg_header_len#,nng_msg_header_len(3)>>, +<<nng_msg_header_trim#,nng_msg_header_trim(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_msg_header_append.adoc b/docs/man/nng_msg_header_append.adoc new file mode 100644 index 00000000..a21da6dc --- /dev/null +++ b/docs/man/nng_msg_header_append.adoc @@ -0,0 +1,53 @@ += nng_msg_header_append(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_msg_header_append, nng_msg_header_append_u32 - append to message header + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_msg_header_append(nng_msg *msg, const void *val, size_t size); +int nng_msg_header_append_u32(nng_msg *msg, uint32_t val32); +----------- + +== DESCRIPTION + +The `nng_msg_header_append()` and `nng_msg_header_append_u32()` +functions append data to +the end of the headers of message _msg_, reallocating it if necessary. +The first function appends _size_ bytes, copying them from _val_. The +second function appends the value _val32_ in network-byte order (big-endian). + + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient free memory exists. + +== SEE ALSO + +<<nng_msg_alloc#,nng_msg_alloc(3)>>, +<<nng_msg_header#,nng_msg_header(3)>>, +<<nng_msg_header_chop#,nng_msg_header_chop(3)>>, +<<nng_msg_header_insert#,nng_msg_header_insert(3)>>, +<<nng_msg_header_len#,nng_msg_header_len(3)>>, +<<nng_msg_header_trim#,nng_msg_header_trim(3)>>, +<<nng_msg_free#,nng_msg_free(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_msg_header_chop.adoc b/docs/man/nng_msg_header_chop.adoc new file mode 100644 index 00000000..f9c9f547 --- /dev/null +++ b/docs/man/nng_msg_header_chop.adoc @@ -0,0 +1,53 @@ += nng_msg_header_chop(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_msg_header_chop, nng_msg_header_chop_u32 - remove data from end of message header + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_msg_header_chop(nng_msg *msg, size_t size); +int nng_msg_header_chop_u32(nng_msg *msg, uint32_t *val32); +----------- + +== DESCRIPTION + +The `nng_msg_header_chop()` and `nng_msg_header_chop_u32()` functions remove +data from the end of the header of message _msg_. +The first function removes _size_ bytes. +The second function removes 4 bytes, and stores them in the value _val32_, +after converting them from network-byte order (big-endian) to native +byte order. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_EINVAL`:: The message header is too short to remove the requested data. + +== SEE ALSO + +<<nng_msg_alloc#,nng_msg_alloc(3)>>, +<<nng_msg_header#,nng_msg_header(3)>>, +<<nng_msg_header_append#,nng_msg_header_append(3)>>, +<<nng_msg_header_insert#,nng_msg_header_insert(3)>>, +<<nng_msg_header_len#,nng_msg_header_len(3)>>, +<<nng_msg_header_trim#,nng_msg_header_trim(3)>>, +<<nng_msg_free#,nng_msg_free(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_msg_header_clear.adoc b/docs/man/nng_msg_header_clear.adoc new file mode 100644 index 00000000..03fbdccb --- /dev/null +++ b/docs/man/nng_msg_header_clear.adoc @@ -0,0 +1,41 @@ += nng_msg_header_clear(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_msg_header_clear - clear message header + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +void nng_msg_header_clear(nng_msg *msg); +----------- + +== DESCRIPTION + +The `nng_msg_clear()` function resets the header length of _msg_ to zero. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_msg_alloc#,nng_msg_alloc(3)>>, +<<nng_msg_free#,nng_msg_free(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_msg_header_insert.adoc b/docs/man/nng_msg_header_insert.adoc new file mode 100644 index 00000000..4cc5016c --- /dev/null +++ b/docs/man/nng_msg_header_insert.adoc @@ -0,0 +1,53 @@ += nng_msg_header_insert(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_msg_header_insert, nng_msg_header_insert_u32 - prepend to message header + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_msg_header_insert(nng_msg *msg, const void *val, size_t size); +int nng_msg_header_insert_u32(nng_msg *msg, uint32_t val32); +----------- + +== DESCRIPTION + +The `nng_msg_header_insert()` and `nng_msg_header_insert_u32()` functions +prepend data to the front of the headers of message _msg_, reallocating +if necessary. +The first function prepends _size_ bytes, copying them from _val_. The +second function prepends the value _val32_ in network-byte order (big-endian). + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient free memory exists. + +== SEE ALSO + +<<nng_msg_alloc#,nng_msg_alloc(3)>>, +<<nng_msg_header_append#,nng_msg_header_append(3)>>, +<<nng_msg_header_body#,nng_msg_header_body(3)>>, +<<nng_msg_header_chop#,nng_msg_header_chop(3)>>, +<<nng_msg_header_len#,nng_msg_header_len(3)>>, +<<nng_msg_header_trim#,nng_msg_header_trim(3)>>, +<<nng_msg_free#,nng_msg_free(3)>>, +<<nng_msg_realloc#,nng_msg_realloc(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_msg_header_len.adoc b/docs/man/nng_msg_header_len.adoc new file mode 100644 index 00000000..68dfbcff --- /dev/null +++ b/docs/man/nng_msg_header_len.adoc @@ -0,0 +1,41 @@ += nng_msg_header_len(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_msg_header_len - return message header length + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +size_t nng_msg_header_len(nng_msg *msg); +----------- + +== DESCRIPTION + +The `nng_msg_header_len()` returns the length of message header of _msg_. + +== RETURN VALUES + +Length of message header. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_msg_alloc#,nng_msg_alloc(3)>>, +<<nng_msg_header#,nng_msg_header(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_msg_header_trim.adoc b/docs/man/nng_msg_header_trim.adoc new file mode 100644 index 00000000..44496c13 --- /dev/null +++ b/docs/man/nng_msg_header_trim.adoc @@ -0,0 +1,53 @@ += nng_msg_header_trim(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_msg_header_trim, nng_msg_header_trim_u32 - remove data from start of message header + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_msg_header_trim(nng_msg *msg, size_t size); +int nng_msg_header_trim_u32(nng_msg *msg, uint32_t *val32); +----------- + +== DESCRIPTION + +The `nng_msg_header_trim()` and `nng_msg_header_trim_u32()` functions remove +data from the start of the header of message _msg_. +The first function removes _size_ bytes. +The second function removes 4 bytes, and stores them in the value _val32_, +after converting them from network-byte order (big-endian) to native +byte order. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_EINVAL`:: The message header is too short to remove the requested data. + +== SEE ALSO + +<<nng_msg_alloc#,nng_msg_alloc(3)>>, +<<nng_msg_header#,nng_msg_header(3)>>, +<<nng_msg_header_append#,nng_msg_header_append(3)>>, +<<nng_msg_header_chop#,nng_msg_header_chop(3)>>, +<<nng_msg_header_insert#,nng_msg_header_insert(3)>>, +<<nng_msg_header_len#,nng_msg_header_len(3)>>, +<<nng_msg_free#,nng_msg_free(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_msg_insert.adoc b/docs/man/nng_msg_insert.adoc new file mode 100644 index 00000000..2a1f6d12 --- /dev/null +++ b/docs/man/nng_msg_insert.adoc @@ -0,0 +1,57 @@ += nng_msg_insert(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_msg_insert, nng_msg_insert_u32 - prepend to message body + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_msg_insert(nng_msg *msg, const void *val, size_t size); +int nng_msg_insert(nng_msg *msg, uint32_t val32); +----------- + +== DESCRIPTION + +The `nng_msg_insert()` and `nng_msg_insert_u32()` functions prepend data to +the front of the body of message _msg_, reallocating it if necessary. +The first function prepends _size_ bytes, copying them from _val_. The +second function prepends the value _val32_ in network-byte order (big-endian). + +TIP: This function makes use of pre-allocated "headroom" in the message if +available, so it can often avoid performing any reallocation. Applications +should use this instead of reallocating and copying message content themselves, +in order to benefit from this capabilitiy. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient free memory exists. + +== SEE ALSO + +<<nng_msg_alloc#,nng_msg_alloc(3)>>, +<<nng_msg_append#,nng_msg_append(3)>>, +<<nng_msg_body#,nng_msg_body(3)>>, +<<nng_msg_chop#,nng_msg_chop(3)>>, +<<nng_msg_free#,nng_msg_free(3)>>, +<<nng_msg_len#,nng_msg_len(3)>>, +<<nng_msg_realloc#,nng_msg_realloc(3)>>, +<<nng_msg_trim#,nng_msg_trim(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_msg_len.adoc b/docs/man/nng_msg_len.adoc new file mode 100644 index 00000000..260be306 --- /dev/null +++ b/docs/man/nng_msg_len.adoc @@ -0,0 +1,41 @@ += nng_msg_len(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_msg_len - return message body length + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +size_t nng_msg_len(nng_msg *msg); +----------- + +== DESCRIPTION + +The `nng_msg_len()` returns the length of the body of message _msg_. + +== RETURN VALUES + +Length of message body. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_msg_alloc#,nng_msg_alloc(3)>>, +<<nng_msg_body#,nng_msg_body(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_msg_realloc.adoc b/docs/man/nng_msg_realloc.adoc new file mode 100644 index 00000000..47c9540b --- /dev/null +++ b/docs/man/nng_msg_realloc.adoc @@ -0,0 +1,61 @@ += nng_msg_alloc(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_msg_alloc - allocate a message + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_msg_realloc(nng_msg *msg, size_t size); +----------- + +== DESCRIPTION + +The `nng_msg_realloc()` function re-allocates a message so that it has +a body of length _size_. This message attempts to avoid extra allocations, +and will reuse the existing memory when possible. + +TIP: One way to further reduce message allocations is to allocate a message +larger than needed, then use this function or <<nng_msg_chop#,nng_msg_chop(3)>> +to reduce the message size to that actually needed. The extra space left +over will still be present in the message, so that when the message size +needs to grow due to this function or <<nng_msg_append#,nng_msg_append(3)>> +no actual memory allocations need to take place. + +NOTE: Pointers to message body and header content obtained prior to this +function must not be in use, as the underlying memory used for the message +may have changed, particularly if the message size is increasing. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient free memory exists to reallocate a message. + +== SEE ALSO + +<<nng_msg_alloc#,nng_msg_alloc(3)>>, +<<nng_msg_append#,nng_msg_append(3)>>, +<<nng_msg_body#,nng_msg_body(3)>>, +<<nng_msg_chop#,nng_msg_chop(3)>>, +<<nng_msg_free#,nng_msg_free(3)>>, +<<nng_msg_insert#,nng_msg_insert(3)>>, +<<nng_msg_len#,nng_msg_len(3)>>, +<<nng_msg_trim#,nng_msg_trim(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_msg_trim.adoc b/docs/man/nng_msg_trim.adoc new file mode 100644 index 00000000..ff6f8431 --- /dev/null +++ b/docs/man/nng_msg_trim.adoc @@ -0,0 +1,54 @@ += nng_msg_trim(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_msg_trim, nng_msg_trim_u32 - remove data from start of message body + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_msg_trim(nng_msg *msg, size_t size); +int nng_msg_trim_u32(nng_msg *msg, uint32_t *val32); +----------- + +== DESCRIPTION + +The `nng_msg_trim()` and `nng_msg_trim_u32()` functions remove data from +the start of the body of message _msg_. +The first function removes _size_ bytes. +The second function removes 4 bytes, and stores them in the value _val32_, +after converting them from network-byte order (big-endian) to native +byte order. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_EINVAL`:: The message body is too short to remove the requested data. + +== SEE ALSO + +<<nng_msg_alloc#,nng_msg_alloc(3)>>, +<<nng_msg_append#,nng_msg_append(3)>>, +<<nng_msg_body#,nng_msg_body(3)>>, +<<nng_msg_chop#,nng_msg_chop(3)>>, +<<nng_msg_free#,nng_msg_free(3)>>, +<<nng_msg_insert#,nng_msg_insert(3)>>, +<<nng_msg_len#,nng_msg_len(3)>>, +<<nng_msg_realloc#,nng_msg_realloc(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_pair.adoc b/docs/man/nng_pair.adoc new file mode 100644 index 00000000..b826f5fc --- /dev/null +++ b/docs/man/nng_pair.adoc @@ -0,0 +1,132 @@ += nng_pair(7) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_pair - pair protocol + +== SYNOPSIS + +.Version 0 +[source,c] +---------- +#include <nng/protocol/pair0/pair.h> + +int nng_pair0_open(nng_socket *s); +---------- + +.Version 1 +[source,c] +---------- +#include <nng/protocol/pair1/pair.h> + +int nng_pair1_open(nng_socket *s); +---------- + +== DESCRIPTION + +The _nng_pair_ protocol implements a peer-to-peer pattern, where +relationships between peers are one-to-one. + +Version 1 of this protocol supports an optional _polyamorous_ mode where a +peer can maintain multiple partnerships. Using this mode requires +some additional sophistication in the application. + +=== Socket Operations + +The `nng_pair_open()` call creates a _pair_ socket. Normally, this +pattern will block when attempting to send a message, if no peer is +able to receive the message. + +NOTE: Even though this mode may appear to be "reliable", because back-pressure +prevents discarding messages most of the time, there are topologies involving +_devices_ (see <<nng_device#,nng_device(3)>>) or raw mode sockets where +messages may be discarded. Applications that require reliable delivery +semantics should consider using <<nng_req#,nng_req(7)>> sockets, or +implement their own acknowledgement layer on top of pair sockets. + +In order to avoid head-of-line blocking conditions, _polyamorous_ mode pair +sockets (version 1 only) discard messages if they are unable to deliver them +to a peer. + +=== Protocol Versions + +Version 0 is the legacy version of this protocol. It lacks any header +information, and is suitable when building simple one-to-one topologies. + +TIP: Use version 0 if you need to communicate with other implementations, +including the legacy https://github.com/nanomsg/nanomsg[nanomsg] library or +https://github.com/go-mangos/mangos[mangos]. + +Version 1 of the protocol offers improved protection against loops when +used with <<nng_device#,nng_device(3)>>. It also offers _polyamorous_ +mode for forming multiple partnerships on a single socket. + +NOTE: Version 1 of this protocol is considered experimental at this time. + +=== Polyamorous Mode + +Normally pair sockets are for one-to-one communication, and a given peer +will reject new connections if it already has an active connection to another +peer. + +In _polyamorous_ mode, which is only available with version 1, a socket can +support many one-to-one connections. In this mode, the application must +choose the remote peer to receive an ougoing message by setting the value +of the pipe ID on the outgoing message using +the <<nng_msg_set_pipe#,nng_msg_set_pipe(3)>> function. + +Most often the value of the outgoing pipe ID will be obtained from an incoming +message using the <<nng_msg_get_pipe#,nng_msg_get_pipe(3)>> function, +such as when replying to an incoming message. + +In order to prevent head-of-line blocking, if the peer on the given pipe +is not able to receive (or the pipe is no longer available, such as if the +peer has disconnected), then the message will be discarded with no notification +to the sender. + +=== Protocol Options + +The following protocol-specific options are available. + +`NNG_OPT_PAIR1_POLY`:: + + (Version 1 only). This option enables the use of _polyamorous_ mode. + The value is read-write, and takes an integer boolean value. The default + false value (0) indicates that legacy monogamous mode should be used. + +`NNG_OPT_MAXTTL`:: + + (Version 1 only). Maximum time-to-live. This option is an integer value + between 0 and 255, + inclusive, and is the maximum number of "hops" that a message may + pass through until it is discarded. The default value is 8. A value + of 0 may be used to disable the loop protection, allowing an infinite + number of hops. ++ +TIP: Each node along a forwarding path may have it's own value for the +maximum time-to-live, and performs its own checks before forwarding a message. +Therefore it is helpful if all nodes in the topology use the same value for +this option. + +=== Protocol Headers + +Version 0 of the pair protocol has no protocol-specific headers. + +Version 1 of the pair protocol uses a single 32-bit unsigned value. The +low-order (big-endian) byte of this value contains a "hop" count, and is +used in conjuction with the `NNG_OPT_MAXTTL` option to guard against +device forwarding loops. This value is initialized to 1, and incremented +each time the message is received by a new node. + +== SEE ALSO + +<<nng#,nng(7)>> diff --git a/docs/man/nng_pub.adoc b/docs/man/nng_pub.adoc new file mode 100644 index 00000000..a8acb2c1 --- /dev/null +++ b/docs/man/nng_pub.adoc @@ -0,0 +1,66 @@ += nng_pub(7) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_pub - publisher protocol + +== SYNOPSIS + +[source,c] +---------- +#include <nng/protocol/pubsub0/pub.h> + +int nng_pub0_open(nng_socket *s); +---------- + +== DESCRIPTION + +The _nng_pub_ protocol is one half of a publisher/subscriber pattern. +In this pattern, a publisher sends data, which is broadcast to all +subscribers. The subscribing applications only see the data to which +they have subscribed. + +The _nng_pub_ protocol is the publisher side, and the +<<nng_sub#,nng_sub(7)>> protocol is the subscriber side. + +NOTE: In this implementation, the publisher delivers all messages to all +subscribers. The subscribers maintain their own subscriptions, and filter +them locally. Thus, this pattern should not be used in an attempt to +reduce bandwidth consumption. + +The topics that subscribers subscribe to is just the first part of +the message body. Applications should construct their messages +accordingly. + +=== Socket Operations + +The `nng_pub0_open()` call creates a publisher socket. This socket +may be used to send messages, but is unable to receive them. Attempts +to receive messages will result in `NNG_ENOTSUP`. + +=== Protocol Versions + +Only version 0 of this protocol is supported. (At the time of writing, +no other versions of this protocol have been defined.) + +=== Protocol Options + +The _nng_pub_ protocol has no protocol-specific options. + +=== Protocol Headers + +The _nng_pub_ protocol has no protocol-specific headers. + +== SEE ALSO + +<<nng#,nng(7)>>, +<<nng_sub#,nng_sub(7)>> diff --git a/docs/man/nng_pull.adoc b/docs/man/nng_pull.adoc new file mode 100644 index 00000000..f56afb5e --- /dev/null +++ b/docs/man/nng_pull.adoc @@ -0,0 +1,63 @@ += nng_pull(7) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_pull - pull protocol + +== SYNOPSIS + +[source,c] +---------- +#include <nng/protocol/pipeline0/pull.h> + +int nng_pull0_open(nng_socket *s); +---------- + +== DESCRIPTION + +The _nng_pull_ protocol is one half of a pipeline pattern. The other half +is the <<nng_push#,nng_push(7)>> protocol. + +In the pipeline pattern, pushers distribute messages to pullers. +Each message sent +by a pusher will be sent to one of its peer pullers, +chosen in a round-robin fashion +from the set of connected peers available for receiving. +This property makes this pattern useful in load-balancing scenarios. + +=== Socket Operations + +The `nng_pull0_open()` call creates a puller socket. This socket +may be used to receive messages, but is unable to send them. Attempts +to send messages will result in `NNG_ENOTSUP`. + +When receiving messages, the _nng_pull_ protocol accepts messages as +they arrive from peers. If two peers both have a message ready, the +order in which messages are handled is undefined. + +=== Protocol Versions + +Only version 0 of this protocol is supported. (At the time of writing, +no other versions of this protocol have been defined.) + +=== Protocol Options + +The _nng_pull_ protocol has no protocol-specific options. + +=== Protocol Headers + +The _nng_pull_ protocol has no protocol-specific headers. + +== SEE ALSO + +<<nng#,nng(7)>>, +<<nng_push#,nng_push(7)>> diff --git a/docs/man/nng_push.adoc b/docs/man/nng_push.adoc new file mode 100644 index 00000000..42cc2dd5 --- /dev/null +++ b/docs/man/nng_push.adoc @@ -0,0 +1,71 @@ += nng_push(7) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_push - push protocol + +== SYNOPSIS + +[source,c] +---------- +#include <nng/protocol/pipeline0/push.h> + +int nng_push0_open(nng_socket *s); +---------- + +== DESCRIPTION + +The _nng_push_ protocol is one half of a pipeline pattern. The +other side is the <<nng_pull#,nng_pull(7)>> protocol. + +In the pipeline pattern, pushers distribute messages to pullers. +Each message sent +by a pusher will be sent to one of its peer pullers, +chosen in a round-robin fashion +from the set of connected peers available for receiving. +This property makes this pattern useful in load-balancing scenarios. + +=== Socket Operations + +The `nng_push0_open()` call creates a pusher socket. This socket +may be used to send messages, but is unable to receive them. Attempts +to receive messages will result in `NNG_ENOTSUP`. + +Send operations will observe flow control (back-pressure), so that +only peers capable of accepting a message will be considered. If no +peer is available to receive a message, then the send operation will +wait until one is available, or the operation times out. + +NOTE: Although the pipeline protocol honors flow control, and attempts +to avoid dropping messages, no guarantee of delivery is made. Furthermore, +as there is no capability for message acknowledgement, applications that +need reliable delivery are encouraged to consider the +<<nng_req#,nng_req(7)>> protocol instead. + +=== Protocol Versions + +Only version 0 of this protocol is supported. (At the time of writing, +no other versions of this protocol have been defined.) + +=== Protocol Options + +The _nng_push_ protocol has no protocol-specific options. + +=== Protocol Headers + +The _nng_push_ protocol has no protocol-specific headers. + +== SEE ALSO + +<<nng#,nng(7)>>, +<<nng_pull#,nng_pull(7)>>, +<<nng_req#,nng_req(7)>> diff --git a/docs/man/nng_recv.adoc b/docs/man/nng_recv.adoc new file mode 100644 index 00000000..e12d0b53 --- /dev/null +++ b/docs/man/nng_recv.adoc @@ -0,0 +1,79 @@ += nng_recv(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_recv - recv data + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_recv(nng_socket s, void *data, size_t *sizep int flags); +----------- + +== DESCRIPTION + +The `nng_recv()` receives a message. + +If the special flag `NNG_FLAG_ALLOC` is not specified, then the caller must +set _data_ to a buffer to receive the message body content, and must store +the size of that buffer at the location pointed to by _sizep_. When the +function returns, if it is successful, the size at _sizep_ will be updated with +the actual message body length copied into _data_. + +If the special flag `NNG_FLAG_ALLOC` is present, then a "zero-copy" mode is +used. In this case the caller must set the value of _data_ to the location +of another pointer (of type `void *`), and the _sizep_ pointer must be set +to a location to receive the size of the message body. The function will then +allocate a message buffer (as if by <<nng_alloc#,nng_alloc(3)>>), fill it with +the message body, and store it at the address referenced by _data_, and update +the size referenced by _sizep_. When this flag is present, the caller assumes +responsibility for disposing of the received buffer either by the function +<<nng_free#,nng_free(3)>> or reusing the message for sending (with the same +size) via <<nng_send#,nng_send(3)>>. + +NOTE: The semantics of what receiving a message means vary from protocol to +protocol, so examination of the protocol documentation is encouraged. (For +example, with an <<nng_req#,nng_req(3)>> socket a message may only be received +after a request has been sent, and an <<nng_sub#,nng_sub(3)>> socket +may only receive messages corresponding to topics to which it has subscribed.) +Furthermore, some protocols may not support receiving data at all, such as +<<nng_pub#,nng_pub(3)>>. + +TIP: The `NNG_FLAG_ALLOC` flag can be used to reduce data copies, thereby +increasing performance, particularly if the buffer is reused to send +a response using the same flag. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_EAGAIN`:: The socket _s_ cannot accept data for sending. +`NNG_ECLOSED`:: The socket _s_ is not open. +`NNG_EINVAL`:: An invalid set of _flags_ was specified. +`NNG_EMSGSIZE`:: The received message did not fit in the size provided. +`NNG_ENOMEM`:: Insufficient memory is available. +`NNG_ENOTSUP`:: The protocol for socket _s_ does not support receiving. +`NNG_ESTATE`:: The socket _s_ cannot receive data in this state. + +== SEE ALSO + +<<nng_alloc#,nng_alloc(3)>>, +<<nng_free#,nng_free(3)>>, +<<nng_recvmsg#,nng_recvmsg(3)>>, +<<nng_send#,nng_send(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_rep.adoc b/docs/man/nng_rep.adoc new file mode 100644 index 00000000..dcc7e6fb --- /dev/null +++ b/docs/man/nng_rep.adoc @@ -0,0 +1,83 @@ += nng_rep(7) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +NAME +---- +nng_rep - reply protocol + +SYNOPSIS +-------- + +[source,c] +---------- +#include <nng/protocol/reqrep0/rep.h> + +int nng_rep0_open(nng_socket *s); +---------- + +DESCRIPTION +----------- + +The _nng_rep_ protocol is one half of a request/reply pattern. +In this pattern, a requester sends a message to one replier, who +is expected to reply. The request is resent if no reply arrives, +until a reply is received or the request times out. + +TIP: This protocol is useful in setting up RPC-like services. It +is also "reliable", in that a the requester will keep retrying until +a reply is received. + +The _nng_rep_ protocol is the replier side, and the +<<nng_req#,nng_req(7)>> protocol is the requester side. + +Socket Operations +~~~~~~~~~~~~~~~~~ + +The `nng_rep0_open()` call creates a requester socket. This socket +may be used to receive messages (requests), and then to send replies. Generally +a reply can only be sent after receiving a request. (Attempts to receive +a message will result in `NNG_ESTATE` if there is no outstanding request.) + +Attempts to send on a socket with no outstanding requests will result +in `NNG_ESTATE`. + +Raw mode sockets (set with `NNG_OPT_RAW`) ignore all these restrictions. + +Protocol Versions +~~~~~~~~~~~~~~~~~ + +Only version 0 of this protocol is supported. (At the time of writing, +no other versions of this protocol have been defined.) + +Protocol Options +~~~~~~~~~~~~~~~~ + +The following protocol-specific options are available. + +`NNG_OPT_MAXTTL`:: + + Maximum time-to-live. This option is an integer value + between 0 and 255, + inclusive, and is the maximum number of "hops" that a message may + pass through until it is discarded. The default value is 8. A value + of 0 may be used to disable the loop protection, allowing an infinite + number of hops. + +Protocol Headers +~~~~~~~~~~~~~~~~ + +The _nng_rep_ protocol uses a _backtrace_ in the header. This is +more fully documented in the <<nng_req#,nng_req(7)>> manual. + +SEE ALSO +-------- +<<nng#,nng(7)>>, +<<nng_req#,nng_req(7)>> diff --git a/docs/man/nng_req.adoc b/docs/man/nng_req.adoc new file mode 100644 index 00000000..550c90c4 --- /dev/null +++ b/docs/man/nng_req.adoc @@ -0,0 +1,136 @@ += nng_req(7) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_req - request protocol + +== SYNOPSIS + +[source,c] +---------- +#include <nng/protocol/reqrep0/req.h> + +int nng_req0_open(nng_socket *s); +---------- + +== DESCRIPTION + +The _nng_req_ protocol is one half of a request/reply pattern. +In this pattern, a requester sends a message to one replier, who +is expected to reply. The request is resent if no reply arrives, +until a reply is received or the request times out. + +TIP: This protocol is useful in setting up RPC-like services. It +is also "reliable", in that a the requester will keep retrying until +a reply is received. + +NOTE: Because requests are resent, it is important that they be idempotent +to ensure predictable and repeatable behavior even in the face of duplicated +requests, which can occur (for example if a reply message is lost for +some reason.) + +The requester generally only has one outstanding request at a time unless +in "raw" mode (via `NNG_OPT_RAW`), and it will generally attempt to spread +work requests to different peer repliers. + +TIP: This property, when combined with a <<nng_device#,device>> can +help provide a degree of load-balancing. + +The _nng_req_ protocol is the requester side, and the +<<nng_rep#,nng_rep(7)>> protocol is the replier side. + +=== Socket Operations + +The `nng_req0_open()` call creates a requester socket. This socket +may be used to send messages (requests), and then to receive replies. Generally +a reply can only be received after sending a request. (Attempts to receive +a message will result in `NNG_ESTATE` if there is no outstanding request.) + +Requests may be canceled by sending a different request. This will +cause the requester to discard any reply from the earlier request, +but it will not stop a replier +from processing a request it has already received or terminate a request +that has already been placed on the wire. + +Attempts to receive on a socket with no outstanding requests will result +in `NNG_ESTATE`. + +Raw mode sockets (set with `NNG_OPT_RAW`) ignore all these restrictions. + +=== Protocol Versions + +Only version 0 of this protocol is supported. (At the time of writing, +no other versions of this protocol have been defined.) + +=== Protocol Options + +The following protocol-specific options are available. + +`NNG_OPT_REQ_RESENDTIME`:: + + This read/write option is a duration (32-bit unsigned integer) representing + a relative number of milliseconds. + When a new request is started, a timer of this duration is also started. + If no reply is received before this timer expires, then the request will + be resent. (Requests are also automatically resent if the peer to whom + the original request was sent disconnects, or if a peer becomes available + while the requester is waiting for an available peer.) + +`NNG_OPT_MAXTTL`:: + + Maximum time-to-live. This option is an integer value + between 0 and 255, + inclusive, and is the maximum number of "hops" that a message may + pass through until it is discarded. The default value is 8. A value + of 0 may be used to disable the loop protection, allowing an infinite + number of hops. + +=== Protocol Headers + +This protocol uses a _backtrace_ in the header. This +form uses a "stack" of 32-bit big-endian identifiers. There *must* be +at least one identifier, the __request ID__, which will be the last +element in the array, and *must* have the most significant bit set. + +There may be additional __peer ID__s preceeding the request ID. These +will be distinguishable from the request ID by having their most +significant bit clear. + +When a request message is received by a forwarding node (see +<<nng_device#,nng_device(3)>>), the forwarding node prepends a +32-bit peer ID (which *must* have the most significant bit clear), +which is the forwarder's way of identifying the directly connected +peer from which it received the message. (This peer ID, except for the +most significant bit, has meaning only to the forwarding node itself.) + +It may help to think of prepending a peer ID as "pushing" a peer ID onto the +front of the stack of headers for the message. (It will use the peer ID +it popped from the front to determine the next intermediate destination +for the reply.) + +When a reply message is created, it is created using the same headers +that the request contained. + +A forwarding node can "pop" the peer ID it originally pushed on the +message, stripping it from the front of the message as it does so. + +When the reply finally arrives back at the initiating requestor, it +should have only a single element in the message, which will be the +request ID it originally used for the request. + +// TODO: Insert reference to RFC. + +== SEE ALSO + +<<nng_device(3)#,nng_device(3)>>, +<<nng#,nng(7)>>, +<<nng_rep#,nng_rep(7)>> diff --git a/docs/man/nng_respondent.adoc b/docs/man/nng_respondent.adoc new file mode 100644 index 00000000..9cc6519e --- /dev/null +++ b/docs/man/nng_respondent.adoc @@ -0,0 +1,90 @@ += nng_respondent(7) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_respondent - respondent protocol + +== SYNOPSIS + +[source,c] +---------- +#include <nng/protocol/survey0/respond.h> + +int nng_respondent0_open(nng_socket *s); +---------- + +== DESCRIPTION + +The _nng_respondent_ protocol is one half of a survey pattern. +In this pattern, a surveyor sends a survey, which is broadcast to all +peer respondents. The respondents then have a chance to reply (but after +not obliged to). The survey itself is a timed event, so that responses +received after the survey has finished are discarded. + +TIP: This protocol is useful in solving voting problems, such as leader +election in cluster configurations, as well as certain kinds of service +discovery problems. + +The _nng_respondent_ protocol is the respondent side, and the +<<nng_surveyor#,nng_surveyor(7)>> protocol is the surveyor side. + +=== Socket Operations + +The `nng_respondent0_open()` call creates a respondent socket. This socket +may be used to receive messages, and then to send replies. Generally +a reply can only be sent after receiving a survey, and generally the +reply will be sent to surveyor from whom the last survey was received. + +Respondents may discard a survey by simply not replying to it. + +Raw mode sockets (set with `NNG_OPT_RAW`) ignore all these restrictions. + +=== Protocol Versions + +Only version 0 of this protocol is supported. (At the time of writing, +no other versions of this protocol have been defined. An earlier and +incompatible version of the protocol was used in older pre-releases of +http://nanomsg.org[nanomsg], but was not released in any production +version.) + +=== Protocol Options + +The following protocol-specific options are available. + +`NNG_OPT_MAXTTL`:: + + Maximum time-to-live. This option is an integer value + between 0 and 255, + inclusive, and is the maximum number of "hops" that a message may + pass through until it is discarded. The default value is 8. A value + of 0 may be used to disable the loop protection, allowing an infinite + number of hops. + +=== Protocol Headers + +The _nng_respondent_ protocol uses a _backtrace_ in the header. This +form uses an array of 32-bit big-endian identifiers, where the first +element in the array +identifies the local peer identifier to which the message will next be sent. +This is a hop-by-hop header where each element in a path adds routing +information to the end when sending a survey, and when replying removes +elements to obtain the next hop information. The survey ID is at the +end of this header and is inserted into the header as its first element +by the originating surveyor. (Survey IDs are distinguished from hops by +having their high order bit set to one.) + +// TODO: Insert reference to RFC. + +== SEE ALSO + +<<nng#,nng(7)>>, +<<nng_surveyor#,nng_surveyor(7)>> diff --git a/docs/man/nng_send.adoc b/docs/man/nng_send.adoc new file mode 100644 index 00000000..53a87de3 --- /dev/null +++ b/docs/man/nng_send.adoc @@ -0,0 +1,94 @@ += nng_send(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_send - send data + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_send(nng_socket s, void *data, size_t size, int flags); +----------- + +== DESCRIPTION + +The `nng_send()` sends a message containing the _data_ of length _size_ +using the socket _s_. + +NOTE: The semantics of what sending a message means vary from protocol to +protocol, so examination of the protocol documentation is encouraged. (For +example, with an <<nng_pub#,nng_pub(3)>> socket the data is broadcast, so that +any peers who have a suitable subscription will be able to receive it using +<<nng_recv#,nng_recv(3)>> or a similar function.) Furthermore, some protocols +may not support sending data (such as <<nng_sub#,nng_sub(3)>>) or may +require other conditions. (For example, <<nng_rep#,nng_rep(3)>> sockets +cannot normally send data, which are responses to requests, until they have +first received a request.) + +The _flags_ may contain either of (or neither of) the following values: + +`NNG_FLAG_NONBLOCK`:: + The function returns immediately, regardless of whether + the socket is able to accept the data or not. If the socket is unable + to accept the data (such as if backpressure exists because the peers + are consuming messages too slowly, or no peer is present), then the + function will return with `NNG_EAGAIN`. If this flag is not specified, + then the function will block if such a condition exists. + +`NNG_FLAG_ALLOC`:: + The _data_ was allocated using <<nng_alloc#,nng_alloc(3)>>, or was obtained + from a call to <<nng_recv#,nng_recv(3)>> with the `NNG_FLAG_ALLOC` flag. + If this function returns success, then the _data_ is "owned" by the + function, and it will assume responsibility for calling + <<nng_free#,nng_free(3)>> when it is no longer needed. In the absence + of this flag, the _data_ is copied by the implementation before the + function returns to the caller. + +TIP: The `NNG_FLAG_ALLOC` flag can be used to reduce data copies, thereby +increasing performance. + +NOTE: Regardless of the presence or absence of `NNG_FLAG_NONBLOCK`, there may +be queues between the sender and the receiver. Furthermore, there is no +guarantee that the message has actually been delivered. Finally, with some +protocols, the semantic is implictly `NNG_FLAG_NONBLOCK`, such as with +<<nng_pub#,nng_pub(3)>> sockets, which are best-effort delivery only. + +WARNING: When using `NNG_FLAG_ALLOC`, it is important that the value of _size_ +match the actual allocated size of the data. Using an incorrect size results +in unspecified behavior, which may include heap corruption, program crashes, +or transdimensional mutation of the program's author. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_EAGAIN`:: The socket _s_ cannot accept data for sending. +`NNG_ECLOSED`:: The socket _s_ is not open. +`NNG_EINVAL`:: An invalid set of _flags_ was specified. +`NNG_EMSGSIZE`:: The value of _size_ is too large. +`NNG_ENOMEM`:: Insufficient memory is available. +`NNG_ENOTSUP`:: The protocol for socket _s_ does not support sending. +`NNG_ESTATE`:: The socket _s_ cannot send data in this state. + +== SEE ALSO + +<<nng_alloc#,nng_alloc(3)>>, +<<nng_free#,nng_free(3)>>, +<<nng_recv#,nng_recv(3)>>, +<<nng_sendmsg#,nng_sendmsg(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_strerror.adoc b/docs/man/nng_strerror.adoc new file mode 100644 index 00000000..c81a460f --- /dev/null +++ b/docs/man/nng_strerror.adoc @@ -0,0 +1,46 @@ += nng_strerror(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_strerror - return an error description + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +const char * nng_strerror(int err); +----------- + +== DESCRIPTION + +The `nng_strerror()` returns the human-readable description of the +given _nng_ error in `err`. + +NOTE: The returned error message is provided in US English, but in the +future locale-specific strings may be presented instead. + +NOTE: The specific strings associated with specific error messages are +subject to change. Therefore applications must not depend on the message, +but may use them verbatim when supplying information to end-users, such +as in diagnostic messages or log entries. + +== RETURN VALUES + +This function returns the human-readable error message, terminated +by a `NUL` byte. + +== SEE ALSO + +<<libnng#,libnng(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_sub.adoc b/docs/man/nng_sub.adoc new file mode 100644 index 00000000..579e4cf0 --- /dev/null +++ b/docs/man/nng_sub.adoc @@ -0,0 +1,83 @@ += nng_sub(7) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_sub - subscriber protocol + +== SYNOPSIS + +[source,c] +---------- +#include <nng/protocol/pubsub0/sub.h> + +int nng_sub0_open(nng_socket *s); +---------- + +== DESCRIPTION + +The _nng_sub_ protocol is one half of a publisher/subscriber pattern. +In this pattern, a publisher sends data, which is broadcast to all +subscribers. The subscribing applications only see the data to which +they have subscribed. + +The _nng_sub_ protocol is the subscriber side, and the +<<nng_pub#,nng_pub(7)>> protocol is the publisher side. + +NOTE: In this implementation, the publisher delivers all messages to all +subscribers. The subscribers maintain their own subscriptions, and filter +them locally. Thus, this pattern should not be used in an attempt to +reduce bandwidth consumption. + +The topics that subscribers subscribe to is just the first part of +the message body. Applications should construct their messages +accordingly. + +=== Socket Operations + +The `nng_sub0_open()` call creates a subscriber socket. This socket +may be used to receive messages, but is unable to send them. Attempts +to send messages will result in `NNG_ENOTSUP`. + +=== Protocol Versions + +Only version 0 of this protocol is supported. (At the time of writing, +no other versions of this protocol have been defined.) + +=== Protocol Options + +The following protocol-specific options are available. + +`NNG_OPT_SUB_SUBSCRIBE`:: + + This option registers a topic that the subscriber is interested in. + The option is write-only, and takes an array of bytes, of arbitrary size. + Each incoming message is checked against the list of subscribed topics. + If the body begins with the entire set of bytes in the topic, then the + message is accepted. If no topic matches, then the message is + discarded. ++ +TIP: To receive all messages, an empty topic (zero length) can be used. + +`NNG_OPT_SUB_UNSUBSCRIBE`:: + + This option, also read-only, removes a topic from the subscription list. + Note that if the topic was not previously subscribed to with + `NNG_OPT_SUB_SUBSCRIBE` then an `NNG_ENOENT` error will result. + +=== Protocol Headers + +The _nng_sub_ protocol has no protocol-specific headers. + +== SEE ALSO + +<<nng#,nng(7)>>, +<<nng_pub#,nng_pub(7)>> diff --git a/docs/man/nng_surveyor.adoc b/docs/man/nng_surveyor.adoc new file mode 100644 index 00000000..15937b27 --- /dev/null +++ b/docs/man/nng_surveyor.adoc @@ -0,0 +1,107 @@ += nng_surveyor(7) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_surveyor - surveyor protocol + +== SYNOPSIS + +[source,c] +---------- +#include <nng/protocol/survey0/survey.h> + +int nng_surveyor0_open(nng_socket *s); +---------- + +== DESCRIPTION + +The _nng_surveyor_ protocol is one half of a survey pattern. +In this pattern, a surveyor sends a survey, which is broadcast to all +peer respondents. The respondents then have a chance to reply (but after +not obliged to). The survey itself is a timed event, so that responses +received after the survey has finished are discarded. + +TIP: This protocol is useful in solving voting problems, such as leader +election in cluster configurations, as well as certain kinds of service +discovery problems. + +The _nng_surveyor_ protocol is the surveyor side, and the +<<nng_respondent#,nng_respondent(7)>> protocol is the respondent side. + +=== Socket Operations + +The `nng_surveyor0_open()` call creates a respondent socket. This socket +may be used to send messages (surveys), and then to receive replies. Generally +a reply can only be received after sending a survey. Generally a surveyor +can expect to receive at most one reply from each responder. (Messages +can be duplicated in some topologies, so there is no guarantee of this.) + +Attempts to receive on a socket with no outstanding survey will result +in `NNG_ESTATE`. If the survey times out while the surveyor is waiting +for replies, then the result will be `NNG_ETIMEDOUT`. + +Only one survey can be outstanding at a time; sending another survey will +cancel the prior one, and any responses from respondents from the prior +survey that arrive after this will be discarded. + +Raw mode sockets (set with `NNG_OPT_RAW`) ignore all these restrictions. + +=== Protocol Versions + +Only version 0 of this protocol is supported. (At the time of writing, +no other versions of this protocol have been defined. An earlier and +incompatible version of the protocol was used in older pre-releases of +http://nanomsg.org[nanomsg], but was not released in any production +version.) + +=== Protocol Options + +The following protocol-specific options are available. + +`NNG_OPT_SURVEYOR_SURVEYTIME`:: + + This read/write option is a duration (32-bit unsigned integer) representing + a relative number of milliseconds that following surveys will last. + When a new survey is started, a timer of this duration is also started. + Any responses arriving this time will be discarded. Attempts to receive + after the timer expires with no other surveys started will result in + `NNG_ESTATE`. Attempts to receive when this timer expires will result in + `NNG_ETIMEDOUT`. + +`NNG_OPT_MAXTTL`:: + + Maximum time-to-live. This option is an integer value + between 0 and 255, + inclusive, and is the maximum number of "hops" that a message may + pass through until it is discarded. The default value is 8. A value + of 0 may be used to disable the loop protection, allowing an infinite + number of hops. + +=== Protocol Headers + +The _nng_surveyor_ protocol uses a _backtrace_ in the header. This +form uses an array of 32-bit big-endian identifiers, where the first +element in the array +identifies the local peer identifier to which the message will next be sent. +This is a hop-by-hop header where each element in a path adds routing +information to the end when sending a survey, and when replying removes +elements to obtain the next hop information. The survey ID is at the +end of this header and is inserted into the header as its first element +by the originating surveyor. (Survey IDs are distinguished from hops by +having their high order bit set to one.) + +// TODO: Insert reference to RFC. + +== SEE ALSO + +<<nng#,nng(7)>>, +<<nng_respondent#,nng_respondent(7)>> diff --git a/docs/man/nng_tcp.adoc b/docs/man/nng_tcp.adoc new file mode 100644 index 00000000..9a0c9897 --- /dev/null +++ b/docs/man/nng_tcp.adoc @@ -0,0 +1,115 @@ += nng_tcp(7) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_tcp - TCP/IP transport for nng + +== SYNOPSIS + +[source,c] +---------- +#include <nng/transport/tcp/tcp.h> + +int nng_tcp_register(void); +---------- + +== DESCRIPTION + +The _nng_tcp_ transport provides communication support between +_nng_ sockets across a TCP/IP network. Both IPv4 and IPv6 +are supported when the underlying platform also supports it. + +// We need to insert a reference to the nanomsg RFC. + +=== Registration + +The _tcp_ transport is generally built-in to the _nng_ core, so +no extra steps to use it should be necessary. + +=== URI Format + +This transport uses URIs using the scheme `tcp://`, followed by +an IP address or hostname, followed by a colon and finally a +TCP port number. For example, to contact port 80 on the localhost +either of the following URIs could be used: `tcp://127.0.0.1:80` or +`tcp://localhost:80`. + +When specifying IPv6 addresses, the address must be enclosed in +square brackets (`[]`) to avoid confusion with the final colon +separating the port. + +For example, the same port 80 on the IPv6 loopback address ('::1') would +be specified as `tcp://[::1]:80`. + +NOTE: When using symbolic names, the name is resolved when the +name is first used. _nng_ won't become aware of changes in the +name resolution until restart, +usually.footnote:[This is a bug and will likely be fixed in the future.] + +The special value of 0 (`INADDR_ANY`) can be used for a listener +to indicate that it should listen on all interfaces on the host. +A short-hand for this form is to either omit the address, or specify +the asterisk (`*`) character. For example, the following three +URIs are all equivalent, and could be used to listen to port 9999 +on the host: + + 1. `tcp://0.0.0.0:9999` + 2. `tcp://*:9999` + 3. `tcp://:9999` + +The entire URI must be less than `NNG_MAXADDRLEN` bytes long. + +=== Socket Address + +When using an `nng_sockaddr` structure, the actual structure is either +of type `nng_sockaddr_in` (for IPv4) or `nng_sockaddr_in6` (for IPv6). +These are `struct` types with the following definitions: + +[source,c] +-------- +#define NNG_AF_INET 3 <1> +#define NNG_AF_INET6 4 +#define NNG_MAXADDRLEN 128 + +typedef struct { + // ... <2> + uint16_t sa_family; // must be NNG_AF_INET + uint16_t sa_port; // TCP port number + uint32_t sa_addr; + // ... +} nng_sockaddr_in; + +typedef struct { + // ... <2> + uint16_t sa_family; // must be NNG_AF_INET6 + uint16_t sa_port; // TCP port number + uint8_t sa_addr[16]; + // ... +} nng_sockaddr_in6; +-------- +<1> The values of these macros may change, so applications +should avoid depending upon their values and instead use them symbolically. +<2> Other members may be present, but only those listed here +are suitable for application use. + +The `sa_family` member will have the value `NNG_AF_INET` or `NNG_AF_INET6`. +The `sa_port` and `sa_addr` are the TCP port number and address, both in +network byte order (most significant byte is first). + +=== Transport Options + +The _tcp_ transport has no special +options.footnote:[Options for TCP keepalive, linger, and nodelay are planned.] + +== SEE ALSO + +<<nng#,nng(7)>> diff --git a/docs/man/nng_tls.adoc b/docs/man/nng_tls.adoc new file mode 100644 index 00000000..6ad4033f --- /dev/null +++ b/docs/man/nng_tls.adoc @@ -0,0 +1,180 @@ += nng_tls(7) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_tls - TLS transport for nng + +== SYNOPSIS + +[source,c] +---------- +#include <nng/transport/tls/tls.h> + +int nng_tls_register(void); +---------- + +== DESCRIPTION + +The _nng_tls_ transport provides communication support between +_nng_ sockets across a TCP/IP network using +https://tools.ietf.org/html/rfc5246[TLS v1.2] on top of +https://tools.ietf.org/html/rfc793[TCP]. Both IPv4 and IPv6 +are supported when the underlying platform also supports it. + +The protocol details are documented in +http://nanomsg.org/rfcs/sp-tls-v1.html[TLS Mapping for Scalability Protocols]. + +=== Registration + +Depending upon how the library was built, it may be necessary to +register the transport by calling `nng_tls_register`. This function +returns zero on success, or an nng error value if the transport +cannot be initialized for any reason. + +=== Availability + +The _tls_ transport depends on the use of an external library. +As of this writing, https://tls.mbed.org/[mbed TLS] version 2.0 +or later is required. + +TIP: Applications may need to add this library (or libraries) to +their link line, particularly when using a statically built +_nng_ library. + +NOTE: The mbed TLS library uses different licensing terms than +_nng_ itself; as of this writing it is offered under either +https://opensource.org/licenses/Apache-2.0[Apache License 2.0] or +https://opensource.org/licenses/gpl-license[GNU GPL] terms. +You are responsible for understanding and adhering to the +license terms of any libraries you make use of. + +=== URI Format + +This transport uses URIs using the scheme `tls+tcp://`, followed by +an IP address or hostname, followed by a colon and finally a +TCP port number. For example, to contact port 4433 on the localhost +either of the following URIs could be used: `tls+tcp://127.0.0.1:4433` or +`tls+tcp://localhost:4433`. + +When specifying IPv6 addresses, the address must be enclosed in +square brackets (`[]`) to avoid confusion with the final colon +separating the port. + +For example, the same port 4433 on the IPv6 loopback address ('::1') would +be specified as `tls+tcp://[::1]:4433`. + +NOTE: When using symbolic names, the name is resolved when the +name is first used. _nng_ won't become aware of changes in the +name resolution until restart, +usually.footnote:[This is a bug and will likely be fixed in the future.] + +TIP: Certificate validation generally works when using names +rather than IP addresses. This transport automatically +uses the name supplied in the URL when validating the +certificate supplied by the server. + +The special value of 0 (`INADDR_ANY`) can be used for a listener +to indicate that it should listen on all interfaces on the host. +A short-hand for this form is to either omit the address, or specify +the asterisk (`*`) character. For example, the following three +URIs are all equivalent, and could be used to listen to port 9999 +on the host: + + 1. `tls+tcp://0.0.0.0:9999` + 2. `tls+tcp://*:9999` + 3. `tls+tcp://:9999` + +The entire URI must be less than `NNG_MAXADDRLEN` bytes long. + +=== Socket Address + +When using an `nng_sockaddr` structure, the actual structure is either +of type `nng_sockaddr_in` (for IPv4) or `nng_sockaddr_in6` (for IPv6). +These are `struct` types with the following definitions: + +[source,c] +-------- +#define NNG_AF_INET 3 <1> +#define NNG_AF_INET6 4 +#define NNG_MAXADDRLEN 128 + +typedef struct { + // ... <2> + uint16_t sa_family; // must be NNG_AF_INET + uint16_t sa_port; // TCP port number + uint32_t sa_addr; + // ... +} nng_sockaddr_in; + +typedef struct { + // ... <2> + uint16_t sa_family; // must be NNG_AF_INET6 + uint16_t sa_port; // TCP port number + uint8_t sa_addr[16]; + // ... +} nng_sockaddr_in6; +-------- +<1> The values of these macros may change, so applications +should avoid depending upon their values and instead use them symbolically. +<2> Other members may be present, but only those listed here +are suitable for application use. + +The `sa_family` member will have the value `NNG_AF_INET` or `NNG_AF_INET6`. +The `sa_port` and `sa_addr` are the TCP port number and address, both in +network byte order (most significant byte is first). + +=== Transport Options + +The following transport options are available. Note that +setting these must be done before the transport is started. + +`NNG_OPT_TLS_CONFIG`:: + +This option is used on an endpoint to access the underlying TLS +configuration object. The value is of type `nng_tls_config *`. + +TIP: Use this option when advanced TLS configuration is required. + +`NNG_OPT_TLS_CA_FILE`:: + +This is a write-only option used to load certificates associated +associated private key from a file. +See <<nng_tls_config_ca_file#,nng_tls_config_ca_file(3)>> for more +information. + +`NNG_OPT_TLS_CERT_KEY_FILE`:: + +This is a write-only option used to load the local certificate and +associated private key from a file. The private key used must be +unencrypted. (Use the `NNG_OPT_TLS_CONFIG` option to access the underlying +TLS configuration if more advanced configuration is needed.) +See <<nng_tls_config_own_cert#,nng_tls_config_own_cert(3)>> for more +information. + +`NNG_OPT_TLS_AUTH_MODE`:: + +This is a write-only option used to configure the authentication mode +used. It can take an integer with value `NNG_TLS_AUTH_MODE_NONE`, +`NNG_TLS_AUTH_MODE_REQUIRED`, or `NNG_TLS_AUTH_MODE_OPTIONAL`. See +<<nng_tls_config_auth_mode#,nng_tls_config_auth_mode(3)>> for more details. + +`NNG_OPT_TLS_VERIFIED`:: + +This is a read-only option which returns a boolean value (integer 0 or 1). +It will true (1) if the remote peer has been properly verified using TLS +authentication, or false (0) otherwise. This option may return incorrect +results if peer authentication is disabled with `NNG_TLS_AUTH_MODE_NONE`. + +== SEE ALSO + +<<nng#,nng(7)>>, +<<nng_tls_config_alloc#,nng_tls_config_alloc(3)>> diff --git a/docs/man/nng_tls_config_alloc.adoc b/docs/man/nng_tls_config_alloc.adoc new file mode 100644 index 00000000..e67982da --- /dev/null +++ b/docs/man/nng_tls_config_alloc.adoc @@ -0,0 +1,70 @@ += nng_tls_config_alloc(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_tls_config_alloc - allocate TLS configuration object + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +typedef enum nng_tls_mode { + NNG_TLS_MODE_CLIENT, + NNG_TLS_MODE_SERVER +} nng_tls_mode; + +int nng_tls_config_alloc(nni_tls_config **cfgp, nng_tls_mode mode); +----------- + +== DESCRIPTION + +The `nng_tls_config_alloc()` function creates a newly initialized +https://tools.ietf.org/html/rfc5246[Transport Layer Security]) +configuration object, and stores a pointer to it in the value pointed +to by _cfgp_. + +This object is initialized for use when acting as either a +client (`NNG_TLS_MODE_CLIENT`) or as a server (`NNG_TLS_MODE_SERVER`), +depending on the value of _mode_. + +A TLS object can be further modified by functions that set the security +keys used, peeer certificates, protocol policies, and so forth. + +A single TLS configuration object can be used with multiple TLS streams +or services. The underlying system uses reference counting to ensure +that object is not inadvertently freed while in use. + +Also note that a TLS configuration object becomes "read-only" after it +is first used with a service. After this points, attempts to apply +further changes to the configuration will result in `NNG_EBUSY`. + + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient memory is available. +`NNG_EINVAL`:: An invalid _mode_ was specified. + +== SEE ALSO + +<<nng_strerror#,nng_strerror(3)>>, +<<nng_tls_config_auth_mode#,nng_tls_config_auth_mode(3)>>, +<<nng_tls_config_ca_chain#,nng_tls_config_ca_chain(3)>>, +<<nng_tls_config_own_cert#,nng_tls_config_own_cert(3)>>, +<<nng_tls_config_free#,nng_tls_config_free(3)>>, +<<nng_tls_config_server_name#,nng_tls_config_server_name(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_tls_config_auth_mode.adoc b/docs/man/nng_tls_config_auth_mode.adoc new file mode 100644 index 00000000..1c0f70ec --- /dev/null +++ b/docs/man/nng_tls_config_auth_mode.adoc @@ -0,0 +1,70 @@ += nng_tls_config_auth_mode(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_tls_config_auth_mode - configure authentication mode + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +typedef enum nng_tls_auth_mode { + NNG_TLS_AUTH_MODE_NONE, + NNG_TLS_AUTH_MODE_OPTIONAL, + NNG_TLS_AUTH_MODE_REQUIRED +} nng_tls_auth_mode; + +int nng_tls_config_auth_mode(nni_tls_config *cfg, nng_tls_auth_mode mode); +----------- + +== DESCRIPTION + +The `nng_tls_config_auth_mode()` function configures the authentication mode +to be used for TLS sessions using this configuration object. + +The possible modes are: + +`NNG_TLS_AUTH_MODE_NONE`:: +No authentication of the TLS peer is performed. This is the default for +TLS servers, which most typically do not authenticate their clients. + +`NNG_TLS_AUTH_MODE_OPTIONAL`:: +If a certificate is presented by the peer, then it is validated. However, +if the peer does not present a valid certificate, then the sesssion is allowed +to proceed without authentication. + +`NNG_TLS_AUTH_MODE_REQUIRED`:: +A check is made to ensure that the peer has presented a valid certificate +used for the session. If the peer's certificate is invalid or missing, then +the session is refused. This is the default for clients. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient memory is available. +`NNG_EINVAL`:: An invalid _mode_ was specified. +`NNG_EBUSY`:: The configuration _cfg_ is already in use, and cannot be modified. + + +== SEE ALSO + +<<nng_strerror#,nng_strerror(3)>>, +<<nng_tls_config_alloc#,nng_tls_config_alloc(3)>>, +<<nng_tls_config_ca_chain#,nng_tls_config_ca_chain(3)>>, +<<nng_tls_config_ca_file#,nng_tls_config_ca_file(3)>>, +<<nng_tls_config_server_name#,nng_tls_config_server_name(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_tls_config_ca_chain.adoc b/docs/man/nng_tls_config_ca_chain.adoc new file mode 100644 index 00000000..cac92b3c --- /dev/null +++ b/docs/man/nng_tls_config_ca_chain.adoc @@ -0,0 +1,62 @@ += nng_tls_config_ca_chain(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_tls_config_ca_chain - configure certificate authority certificate chain + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_tls_config_ca_cert(nni_tls_config *cfg, const char *chain, + const char *crl); +----------- + +== DESCRIPTION + +The `nng_tls_config_ca_chain()` function configures a certificate or +certificate chain to be used when validating peers using the configuration +_cfg_. + +NOTE: Certificates *must* be configured when using the authentication mode +`NNG_TLS_AUTH_MODE_REQUIRED`. + +TIP: This function may be called multiple times, to add additional chains +to a configuration, without affecting those added previously. + +The certificates located in _chain_ must be a zero-terminated C string in +https://tools.ietf.org/html/rfc7468[PEM] format. Multiple certificates may +appear concatenated together, with the leaf certificate listed first. +together. + +The _crl_ may be `NULL`, or may also be a C string containing a PEM format +certificate revocation list for the associated authority. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient memory is available. +`NNG_EBUSY`:: The configuration _cfg_ is already in use, and cannot be modified. +`NNG_EINVAL`:: An invalid _chain_ or _crl_ was supplied. + +== SEE ALSO + +<<nng_strerror#,nng_strerror(3)>>, +<<nng_tls_config_alloc#,nng_tls_config_alloc(3)>>, +<<nng_tls_config_auth_mode#,nng_tls_config_auth_mode(3)>>, +<<nng_tls_config_ca_file#,nng_tls_config_ca_file(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_tls_config_ca_file.adoc b/docs/man/nng_tls_config_ca_file.adoc new file mode 100644 index 00000000..833c6747 --- /dev/null +++ b/docs/man/nng_tls_config_ca_file.adoc @@ -0,0 +1,59 @@ += nng_tls_config_ca_file(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_tls_config_ca_file - load certificate authority from file + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_tls_config_ca_file(nni_tls_config *cfg, const char *path); +----------- + +== DESCRIPTION + +The `nng_tls_config_ca_file()` function configures the certificate authority +certificate chain and optional revocation list by loading the certificates +(and revocation list if present) from a single named file. The file must +at least one X.509 certificate in https://tools.ietf.org/html/rfc7468[PEM] +format, and may contain multiple such certificates, as well as zero or +more PEM CRL objects. This information is used to validate certificates +that are presented by peers, when using the configuration _cfg_. + +NOTE: Certificates *must* be configured when using the authentication mode +`NNG_TLS_AUTH_MODE_REQUIRED`. + +TIP: This function may be called multiple times, to add additional chains +to a configuration, without affecting those added previously. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient memory is available. +`NNG_EBUSY`:: The configuration _cfg_ is already in use, and cannot be modified. +`NNG_EINVAL`:: The contents of _path_ are invalid or do not contain a valid PEM certificate. +`NNG_ENOENT`:: The file _path_ does not exist. +`NNG_EPERM`:: The file _path_ is not readable. + +== SEE ALSO + +<<nng_strerror#,nng_strerror(3)>>, +<<nng_tls_config_alloc#,nng_tls_config_alloc(3)>>, +<<nng_tls_config_auth_mode#,nng_tls_config_auth_mode(3)>>, +<<nng_tls_config_ca_chain#,nng_tls_config_ca_chain(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_tls_config_cert_key_file.adoc b/docs/man/nng_tls_config_cert_key_file.adoc new file mode 100644 index 00000000..9e1424b6 --- /dev/null +++ b/docs/man/nng_tls_config_cert_key_file.adoc @@ -0,0 +1,63 @@ += nng_tls_config_cert_key_file(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_tls_config_cert_key_file - load own certificate and key from file + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_tls_config_cert_key_file(nni_tls_config *cfg, const char *path, + const char *pass); +----------- + +== DESCRIPTION + +The `nng_tls_config_cert_key_file()` function loads a certificate (or +certificate chain) and a private key from the file named by _path_. + +The file must contain both the https://tools.ietf.org/html/rfc7468[PEM] +encoded certificate and associated private key, which will be used when +establishing TLS sessions using _cfg_. It may contain additional certificates +leading to a validation chain, with the leaf certificate first. +There is no need to include the self-signed root, as the peer +will need to have that already in order to perform it's own validation. + +The private key may be encrypted with a password, in which can be supplied in +_pass_. The value `NULL` should be supplied for _pass_ if the key is not +encrypted. + +On servers, it is possible to call this function multiple times for the +same configuration. This can be useful for specifying different parameters +to be used for different cryptographic algorithms. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient memory is available. +`NNG_EBUSY`:: The configuration _cfg_ is already in use, and cannot be modified. +`NNG_EINVAL`:: The contents of _path_ are invalid. +`NNG_ENOENT`:: The file named by _path_ does not exist. +`NNG_EPERM`:: The file named by _path_ cannot be opened. + +== SEE ALSO + +<<nng_strerror#,nng_strerror(3)>>, +<<nng_tls_config_alloc#,nng_tls_config_alloc(3)>>, +<<nng_tls_config_own_cert#,nng_tls_config_own_cert(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_tls_config_free.adoc b/docs/man/nng_tls_config_free.adoc new file mode 100644 index 00000000..c1233b0b --- /dev/null +++ b/docs/man/nng_tls_config_free.adoc @@ -0,0 +1,42 @@ += nng_tls_config_alloc(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_tls_config_free - deallocate a TLS configuration object + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +void nng_tls_config_free(nni_tls_config *cfg); +----------- + +== DESCRIPTION + +The `nng_tls_config_free()` decrements the reference count on the +TLS configuration object pointed to by _cfg_, and if the resulting +reference count is zero, then deallocates the configuration object. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_tls_config_alloc#,nng_tls_config_alloc(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_tls_config_own_cert.adoc b/docs/man/nng_tls_config_own_cert.adoc new file mode 100644 index 00000000..bd13fa92 --- /dev/null +++ b/docs/man/nng_tls_config_own_cert.adoc @@ -0,0 +1,62 @@ += nng_tls_config_own_cert(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_tls_config_own_cert - configure own certificate and key + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_tls_config_own_cert(nni_tls_config *cfg, const char *cert, + const char *key, const char *pass); +----------- + +== DESCRIPTION + +The `nng_tls_config_own_cert()` function configures a certificate _cert_ +identifying the local side of a TLS connection used with _cfg_, along with an +associated private or secret key _key_. The certificate may be +a chain, with the leaf signer first and the root at the end. The +self-signed certificate at the end can be omitted. (The client should already +have it, and will have to in order to validate this certificate anyway). + +The _key_ may be encrypted with a password, in which can be supplied in +_pass_. The value `NULL` should be supplied for _pass_ if the key is not +encrypted. + +On servers, it is possible to call this function multiple times for the +same configuration. This can be useful for specifying different parameters +to be used for different cryptographic algorithms. + +The certificate located in _cert_ and _key_ must be NUL (`\0`) terminated C +strings containing +https://tools.ietf.org/html/rfc7468[PEM] formatted material. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient memory is available. +`NNG_EBUSY`:: The configuration _cfg_ is already in use, and cannot be modified. +`NNG_EINVAL`:: An invalid _cert_ or _key_ was supplied. + +== SEE ALSO + +<<nng_strerror#,nng_strerror(3)>>, +<<nng_tls_config_alloc#,nng_tls_config_alloc(3)>>, +<<nng_tls_config_cert_key_file#,nng_tls_config_cert_key_file(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_tls_config_server_name.adoc b/docs/man/nng_tls_config_server_name.adoc new file mode 100644 index 00000000..d533a809 --- /dev/null +++ b/docs/man/nng_tls_config_server_name.adoc @@ -0,0 +1,49 @@ += nng_tls_config_server_name(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_tls_config_server_name - configure remote server name + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_tls_config_server_name(nni_tls_config *cfg, const char *name); +----------- + +== DESCRIPTION + +The `nng_tls_config_server_name()` function configures the remote server name +to be used by a client when connection to a server. The supplied _name_ +is used when comparing the identity in the server's certificate. Furthermore, +when Server Name Indication (SNI) is used, the _name_ may be sent to the server +as a hint to tell it which of several possible certificates should be used. + +TIP: This function is only useful in configuring client behavior. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient memory is available. +`NNG_EBUSY`:: The configuration _cfg_ is already in use, and cannot be modified. + +== SEE ALSO + +<<nng_strerror#,nng_strerror(3)>>, +<<nng_tls_config_alloc#,nng_tls_config_alloc(3)>>, +<<nng_tls_config_auth_mode#,nng_tls_config_auth_mode(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_url_clone.adoc b/docs/man/nng_url_clone.adoc new file mode 100644 index 00000000..4c005120 --- /dev/null +++ b/docs/man/nng_url_clone.adoc @@ -0,0 +1,44 @@ += nng_url_clone(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_url_clone - clone URL structure + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_url_clone(nng_url **dup, nng_url *orig); +----------- + +== DESCRIPTION + +The `nng_url_clone()` makes a clone of the original URL structure _orig_, and +saves the result in the location pointed by _dup_. This clone includes +fully duplicating each of the member fields. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient free memory exists to duplicate a message. + +== SEE ALSO + +<<nng_url_free#,nng_url_free(3)>>, +<<nng_url_parse#,nng_url_parse(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_url_free.adoc b/docs/man/nng_url_free.adoc new file mode 100644 index 00000000..427f6f48 --- /dev/null +++ b/docs/man/nng_url_free.adoc @@ -0,0 +1,42 @@ += nng_url_free(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_url_free - free a URL structure + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +void nng_url_free(nng_url *url); +----------- + +== DESCRIPTION + +The `nng_url_free()` function deallocates the _url_ entirely, including +any of it's members. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_url_clone#,nng_url_clone(3)>>, +<<nng_url_parse#,nng_url_parse(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_url_parse.adoc b/docs/man/nng_url_parse.adoc new file mode 100644 index 00000000..c42d5c1c --- /dev/null +++ b/docs/man/nng_url_parse.adoc @@ -0,0 +1,94 @@ += nng_url_parse(3) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_url_parse - create URL structure from a string + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_url_parse(nng_url **urlp, const char *str); +----------- + +== DESCRIPTION + +The `nng_url_parse()` function parses the string _str_ containing an +https://tools.ietf.org/html/rfc3986[RFC 3986] compliant URL, and creates +a structure containing the results. A pointer to the resulting structure +is stored in _urlp_. + +The `nng_url` structure has at least the following members: + +[source, c] +---- +struct nng_url { + char *u_scheme; // Scheme, such as "http"; always lower case. + char *u_rawurl; // Unparsed URL, with minimal canonicalization. + char *u_userinfo; // Userinfo component, or NULL. + char *u_host; // Full host, including port if present. + char *u_hostname; // Hostname only (or address), or empy string. + char *u_port; // Port number, may be default or empty string. + char *u_path; // Path if present, empty string otherwise. + char *u_query; // Query info if present, NULL otherwise. + char *u_fragment; // Fragment if present, NULL otherwise. + char *u_requri; // Request-URI (path[?query][#fragment]) +}; +---- + +=== URL Canonicalization + +The `nng_url_parse()` function also canonicalizes the results, as +follows: + + 1. The URL is parsed into the various components. + 2. The `u_scheme`, `u_hostname`, `u_host`, and `u_port` members are + converted to lower case. + 3. Percent-encoded values for + https://tools.ietf.org/html/rfc3986#section-2.3[unreserved characters] + converted to their unencoded forms. + 4. Additionally URL percent-encoded values for characters in the path + and with numeric values larger than 127 (i.e. not ASCII) are decoded. + 5. The resulting `u_path` is checked for invalid UTF-8 sequences, consisting + of surrogate pairs, illegal byte sequences, or overlong encodings. + If this check fails, then the entire URL is considered invalid, and + the function returns `NNG_EINVAL`. + 6. Path segments consisting of `.` and `..` are resolved as per + https://tools.ietf.org/html/rfc3986#section-6.2.2.3[RFC 3986 6.2.2.3]. + 7. Further, empty path segments are removed, meaning that duplicate + slash (`/`) separators are removed from the path. + 8. If a port was not specified, but the scheme defines a default + port, then `u_port` will be filled in with the value of the default port. + +TIP: Only the `u_userinfo`, `u_query`, and `u_fragment` members will ever be + `NULL`. The other members will be filled in with either default values + or the empty string if they cannot be determined from _str_. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + + +== ERRORS + +`NNG_ENOMEM`:: Insufficient free memory exists to allocate a message. +`NNG_EINVAL`:: An invalid URL was supplied. + + +== SEE ALSO + +<<nng_url_clone#,nng_url_clone(3)>>, +<<nng_url_free#,nng_url_free(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_ws.adoc b/docs/man/nng_ws.adoc new file mode 100644 index 00000000..c41ccc1c --- /dev/null +++ b/docs/man/nng_ws.adoc @@ -0,0 +1,209 @@ += nng_ws(7) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_ws - WebSocket transport for nng + +== SYNOPSIS + +[source,c] +---------- +#include <nng/transport/websocket/ws.h> + +int nng_ws_register(void); +int nng_wss_register(void); +---------- + +== DESCRIPTION + +The _nng_ws_ transport provides communication support between +_nng_ sockets across a TCP/IP network using +https://tools.ietf.org/html/rfc6455[WebSockets]. Both IPv4 and IPv6 +are supported when the underlying platform also supports it. + +The protocol details are documented in +http://nanomsg.org/rfcs/sp-websocket-v1.html[WebSocket Mapping for Scalability Protocols]. + +=== Registration + +Depending upon how the library was built, it may be necessary to +register the transport by calling `nng_ws_register`. This function +returns zero on success, or an nng error value if the transport +cannot be initialized for any reason. + +If TLS support is enabled in the library, secure WebSockets (over TLS v1.2) +can be used as well, but the secure transport may have to be registered using +the `nng_wss_register` function. (Note that this function will not be +present if TLS support was not enabled in the library.) + +=== URI Format + +This transport uses URIs using the scheme `ws://`, followed by +an IP address or hostname, optionally followed by a colon and an +TCP port number, optionally followed by a path. (If no port number +is specified then port 80 is assumed. If no path is specified then +a path of `/` is assumed.) +For example, the URI `ws://localhost/app/pubsub` would use +port 80 on localhost, with the path `/app/pubsub`. + +Secure WebSockets (if enabled) use the scheme `wss://`, and the default +TCP port number of 443. Otherwise the format is the same as for regular +WebSockets. + +When specifying IPv6 addresses, the address must be enclosed in +square brackets (`[]`) to avoid confusion with the final colon +separating the port. + +For example, the same path and port on the IPv6 loopback address (`::1`) +would be specified as `ws://[::1]/app/pubsub`. + +NOTE: When using symbolic names, the name is resolved when the +name is first used. _nng_ won't become aware of changes in the +name resolution until restart, +usually.footnote:[This is a bug and will likely be fixed in the future.] + +NOTE: The value specified as the host, if any, will also be used +in the `Host:` HTTP header during HTTP negotiation. + +To listen to all ports on the system, the host name may be elided from +the URL on the listener. This will wind up listening to all interfaces +on the system, with possible caveats for IPv4 and IPv6 depending on what +the underlying system supports. (On most modern systems it will map to the +special IPv6 address `::`, and both IPv4 and IPv6 connections will be +permitted, with IPv4 addresses mapped to IPv6 addresses.) + +=== Socket Address + +When using an `nng_sockaddr` structure, the actual structure is either +of type `nng_sockaddr_in` (for IPv4) or `nng_sockaddr_in6` (for IPv6). +These are `struct` types with the following definitions: + +[source,c] +-------- +#define NNG_AF_INET 3 <1> +#define NNG_AF_INET6 4 +#define NNG_MAXADDRLEN 128 + +typedef struct { + // ... <2> + uint16_t sa_family; // must be NNG_AF_INET + uint16_t sa_port; // TCP port number + uint32_t sa_addr; + // ... +} nng_sockaddr_in; + +typedef struct { + // ... <2> + uint16_t sa_family; // must be NNG_AF_INET6 + uint16_t sa_port; // TCP port number + uint8_t sa_addr[16]; + // ... +} nng_sockaddr_in6; +-------- +<1> The values of these macros may change, so applications +should avoid depending upon their values and instead use them symbolically. +<2> Other members may be present, but only those listed here +are suitable for application use. + +The `sa_family` member will have the value `NNG_AF_INET` or `NNG_AF_INET6`. +The `sa_port` and `sa_addr` are the TCP port number and address, both in +network byte order (most significant byte is first). + +=== Server Instances + +This transport makes use of shared HTTP server instances, permitting multiple +sockets or listeners to be configured with the same hostname and port. When +creating a new listener, it is registered with an existing HTTP server instance +if one can be found. Note that the matching algorithm is somewhat simple, +using only a string based hostname or IP address and port to match. Therefore +it is recommended to use only IP addresses or the empty string as the hostname +in listener URLs. + +Likewise, when sharing a server instance, it may not be possible to alter +TLS configuration if the server is already running, as there is only a single +TLS configuration context for the entire server instance. + +All sharing of server instances is only typically possible within the same +process. + +The server may also be used by other things (for example to serve static +content), in the same process. + +=== Transport Options + +The following transport options are available. Note that +setting these must be done before the transport is started. + +NOTE: The TLS specific options (beginning with `NNG_OPT_TLS_`) are +only available for `wss://` endpoints. + +`NNG_OPT_WS_REQUEST_HEADERS`:: + +This value is a string, consisting of multiple lines terminated +by CRLF sequences, that can be used to add further headers to the +HTTP request sent when connecting. This option can be set on dialers, +and retrieved from pipes. + +`NNG_OPT_WS_RESPONSE_HEADERS`:: + +This value is a string, consisting of multiple lines terminated +by CRLF sequences, that can be used to add furthe headers to the +HTTP response sent when connecting. This option can be set on listeners, +and retrieved from pipes. + +`NNG_OPT_TLS_CONFIG`:: + +This option is used on an endpoint to access the underlying TLS +configuration object. The value is of type `nng_tls_config *`. + +TIP: Use this option when advanced TLS configuration is required. + +`NNG_OPT_TLS_CA_FILE`:: + +This is a write-only option used to load certificates associated +associated private key from a file. +See <<nng_tls_config_ca_file#,nng_tls_config_ca_file(3)>> for more +information. + +`NNG_OPT_TLS_CERT_KEY_FILE`:: + +This is a write-only option used to load the local certificate and +associated private key from a file. The private key used must be +unencrypted. (Use the `NNG_OPT_TLS_CONFIG` option to access the underlying +TLS configuration if more advanced configuration is needed.) +See <<nng_tls_config_own_cert#,nng_tls_config_own_cert(3)>> for more +information. + +`NNG_OPT_TLS_AUTH_MODE`:: + +This is a write-only option used to configure the authentication mode +used. It can take an integer with value `NNG_TLS_AUTH_MODE_NONE`, +`NNG_TLS_AUTH_MODE_REQUIRED`, or `NNG_TLS_AUTH_MODE_OPTIONAL`. See +<<nng_tls_config_auth_mode#,nng_tls_config_auth_mode(3)>> for more details. + +`NNG_OPT_TLS_VERIFIED`:: + +This is a read-only option which returns a boolean value (integer 0 or 1). +It will true (1) if the remote peer has been properly verified using TLS +authentication, or false (0) otherwise. This option may return incorrect +results if peer authentication is disabled with `NNG_TLS_AUTH_MODE_NONE`. + +// We should also look at a hook mechanism for listeners. Probably this could +// look like NNG_OPT_WS_LISTEN_HOOK_FUNC which would take a function pointer +// along the lines of int hook(void *, char *req_headers, char **res_headers), +// and NNG_OPT_LISTEN_HOOK_ARG that passes the void * passed in as first arg. +// Alternatively we can uplevel the HTTP API and pass the actual HTTP objects. + +== SEE ALSO + +<<nng#,nng(7)>>, +<<nng_tls_config_alloc#,nng_tls_config_alloc(3)>> diff --git a/docs/man/nng_zerotier.adoc b/docs/man/nng_zerotier.adoc new file mode 100644 index 00000000..d28b1884 --- /dev/null +++ b/docs/man/nng_zerotier.adoc @@ -0,0 +1,209 @@ += nng_zerotier(7) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_zerotier - ZeroTier transport for nng + +== SYNOPSIS + +[source,c] +---------- +#include <nng/transport/zerotier/zerotier.h> + +int nng_zt_register(void); +---------- + +== DESCRIPTION + +The _nng_zerotier_ transport provides communication support for +_nng_ applications over a http://www.zerotier.com[ZeroTier] network, +using a Virtual Layer 2 packet facility. + +CAUTION: This transport is very experimental. To utilize it at +present, the library must be built with support, and the +ZeroTierOne `dev` branch must be included; this will require +linking against a suitable `libzerotiercore` static library. + +NOTE: The `libzerotiercore` library at present is covered under different +license terms than the rest of _nng_. Please be careful to review +and adhere to the licensing terms. + +While ZeroTier makes use of the host's IP stack (and UDP in particular), +this transport does not use or require an IP stack on the virtual +network; thereby mitigating any considerations about IP address management. + +This service uses Ethernet type 901 to transport packets. Network rules +must permit this Ethernet type to pass in order to have a functional +network. + +NOTE: This document assumes that the reader is familiar with ZeroTier +concepts and administration. + +=== Registration + +Depending upon how the library was built, it may be necessary to +register the transport by calling `nng_zt_register`. This function +returns zero on success, or an nng error value if the transport +cannot be initialized for any reason. + +=== URI Format + +This transport uses URIs using the scheme `zt://`, followed by a node +number (ten hexadecimal digits) followed by a `.` delimited, and then +a network address (sixteen hexadecimal digits), followed by a colon (`.`) +and service or port number (decimal value, up to 24-bits). +For example, the URI `zt://fedcba9876.0123456789abdef:999` indicates +that node fedcba9876 on network 0123456789abcdef is listening on port 999. + +The special value `*` can be used in lieu of a node number to represent +the node's own node number. + +Listeners may use port 0 to indicate that a suitable port +number be selected automatically. Applications using this must determine the +selected port number using the `nng_listener_getopt` function. + +=== Socket Address + +When using an `nng_sockaddr` structure, the actual structure is of type +`struct nng_sockaddr_zt`. This type has the following definition: + +[source,c] +-------- +#define NNG_AF_ZT 5 + +struct nng_sockaddr_zt { + uint16_t sa_family; // must be NNG_AF_ZT + uint64_t sa_nwid; // 64-bit network ID + uint64_t sa_nodeid; // 40-bit node ID + uint32_t sa_port; // 24-bit application port +} +-------- + +The `sa_family` member will have the value `NNG_AF_ZT` (5). The remaining +members are, unlike TCP socket address, in native byte order. Only the +lower 24-bits of the `sa_port` may be used. Likewise only the lower 40-bits +of the `sa_nodeid` may be used. + +=== Node Presence + +By default this transport creates an "ephemeral" node, and used the +same ephemeral node for any additional endpoints created. As this node +is ephemeral, the keys associated with it and all associated data are +located in memory and are discarded upon application termination. If +a persistent node is desired, please see the `NNG_OPT_ZT_HOME` option +below. + +It is possible for a single application to join multiple networks +using the same node, or using separate nodes. + +=== Transport Options + +The following transport options are available: + +`NNG_OPT_ZT_HOME`:: + + This is a string representing the "home directory", where the transport + can store (and reuse) persistent state, such as key materials, node + identity, and federation membership. This option must be set before the + ZeroTier transport is first used. If this value is empty, then an ephemeral + ZeroTier node is created, and no persistent state is used. The default + is to use an ephemeral node. ++ +NOTE: If this option is set to different values on different sockets, +dialers, or listeners, then separate nodes will be created. It +is perfectly valid for an application to have multiple node identities +in this fashion. + +`NNG_OPT_ZT_NWID`:: + + This is a read-only option for listeners, dialers, and pipes, and + provides a `uint64_t` in native byte order representing the 64-bit ZeroTier + network number. + +`NNG_OPT_ZT_NODE`:: + + This is a read-only option for listeners, dialers, and pipes, and + provides a `uint64_t` in native byte order representing the ZeroTier + 40-bit node address. + +`NNG_OPT_ZT_NETWORK_STATUS`:: + + This is a read-only integer, representing the ZeroTier network status. + Valid values for this are: ++ +[cols="1,2"] +|=== + +| `nng_zt_network_status_configuring` +| The ZeroTier node is still configuring, network services are not available. + +| `nng_zt_network_status_ok` +| The ZeroTier network is up. + +| `nng_zt_network_status_denied` +| The node does not have permission to join the ZeroTier network. + +| `nng_zt_network_status_notfound` +| The ZeroTier network is not found. + +| `nng_zt_network_status_error` +| Some other ZeroTier error has occurred; the network is not available. + +| `nng_zt_network_status_obsolete` +| The node is running obsolete software; the network is not available. + +|=== + + +`NNG_OPT_ZT_NETWORK_NAME`:: + + This is a read-only ASCIIZ string containing the name of the network + as established by the ZeroTier network administrator. + +`NNG_OPT_ZT_PING_TIME`:: + + If no traffic has been received from the ZeroTier peer after this + period of time, then a "ping" message is sent to check if the peer + is still alive. This is an `nng_duration` (msec). + +`NNG_OPT_ZT_PING_COUNT`:: + + If this number (`int`) of consecutive "ping" requests are sent to the + peer with no response (and no other intervening traffic), then the + peer is assumed to be dead and the connection is closed. Note that + if any traffic is received from the peer, then the underlying counter + is reset to zero. + +`NNG_OPT_ZT_MTU`:: + + This is a read-only size (`size_t`) representing the ZeroTier virtual + network MTU; this is the Virtual Layer 2 MTU. The headers used by + this transport and the protocols consume some of this for each message + sent over the network. (The transport uses 20-bytes of this, and each + protocol may consume additional space, typically not more than 16-bytes.) + +`NNG_OPT_ZT_ORBIT`:: + + This is a write-only option that takes an array of two `uint64_t` values, + indicating the ID of a ZeroTier "moon", and the node ID of the root server + for that moon. (The ID may be zero if the moon ID is the same as it's + root server ID, which is conventional.) + +`NNG_OPT_ZT_DEORBIT`:: + + This write-only option takes a single `uint64_t` indicating the moon + ID to "deorbit". If the node is not already orbiting the moon, then + this has no effect. + +== SEE ALSO + +<<nng#,nng(7)>> diff --git a/docs/man/preview.sh b/docs/man/preview.sh new file mode 100755 index 00000000..73f17aaa --- /dev/null +++ b/docs/man/preview.sh @@ -0,0 +1,128 @@ +#!/bin/bash +# +# Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +# Copyright 2018 Capitar IT Group BV <info@capitar.com> +# 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. +# + +# This script is used to preview in HTML or man format, the documentation. +# I use it during development, YMMV. It is probably completely useless +# on Windows. + +MANSOURCE="NNG" +MANMANUAL="NNG Reference Manual" + +case $(uname -s) in +Darwin) + OPEN=open + MAN=man + ;; +Linux) + OPEN=xdg-open + MAN=man + ;; +*) + echo "No idea how to preview on this system." + exit 2 +esac + +if [ -n "$DISPLAY" ] +then + style=html +else + style=man +fi + +while getopts cs: arg +do + case "${arg}" in + c) cleanup=yes;; + s) style=$OPTARG;; + ?) echo "Usage: $0 [-s <style>][-c] <files...>"; exit 1 ;; + esac +done +shift $(( $OPTIND - 1 )) + +case $style in +html) + suffix=.html + ;; +ps) + suffix=.ps + ;; +pdf) + suffix=.pdf + ;; +man) + suffix=.man + OPEN=${MAN} + ;; +*) + echo "Unknown style, choose one of [html|man|pdf|ps]." 1>&2 + exit 2 +esac + +version=$(cat $(dirname $0)/../.version) +name=nng + +generate_pdf() { + typeset input=$1 + typeset output=$2 + asciidoctor-pdf -aversion-label=${name} -arevnumber=${version} \ + -asource-highlighter=pygments -aicons=font \ + -a mansource="${MANSOURCE}" -a manmanual="${MANMANUAL}" \ + -b pdf -a notitle -d article -o ${output} $input +} + +generate_html() { + typeset input=$1 + typeset output=$2 + asciidoctor -atoc=left -aversion-label=${name} -arevnumber=${version} \ + -aicons=font -asource-highlighter=pygments \ + -a mansource="${MANSOURCE}" -a manmanual="${MANMANUAL}" \ + -b html5 -d manpage -o ${output} $input +} + +generate_man() { + typeset input=$1 + typeset output=$2 + asciidoctor -aversion-label=${name} -arevnumber=${version} \ + -a mansource="${MANSOURCE}" -a manmanual="${MANMANUAL}" \ + -d manpage -b manpage -o ${output} $input +} + +generate_ps() { + typeset input=$1 + typeset output=$2 + manpage=${2%.ps}.man + generate_man $1 $manpage + if [ $? -eq 0 ]; then + man -t $manpage > $output + fi +} + + +if [ -n "${cleanup}" ] +then + tempdir=$(mktemp -d) + clean() { + sleep 1 + rm -rf ${tempdir} + } + trap clean 0 + mkdir -p ${tempdir} +else + tempdir=/tmp/${LOGNAME}.${name}.preview + mkdir -p ${tempdir} +fi + +for input in "$@"; do + base=$(basename $input) + base=${base%.adoc} + output=${tempdir}/${base}${suffix} + generate_${style} $input $output + $OPEN $output +done diff --git a/docs/man/publish.sh b/docs/man/publish.sh new file mode 100755 index 00000000..8ef60b58 --- /dev/null +++ b/docs/man/publish.sh @@ -0,0 +1,115 @@ +#!/bin/bash +# +# Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +# Copyright 2018 Capitar IT Group BV <info@capitar.com> +# 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. +# +# +# This program attempts to publish updated documentation to our gh-pages +# branch. +# +# We read the .version file from ../.version. +# +# The docs are published into the gh-pages branch, in a directory +# called man/v<version>. +# +# This script requires asciidoctor, pygments, git, and a UNIX shell. +# + +tmpdir=$(mktemp -d) +srcdir=$(dirname $0) +dstdir=${tmpdir}/pages +cd ${srcdir} +VERSION=$(cat ../.version) +MANMANUAL="NNG Reference Manual" +MANSOURCE="NNG" +LAYOUT=refman +dstman=${dstdir}/man/v${VERSION} +name=nng + +giturl="${GITURL:-git@github.com:nanomsg/nng}" + +cleanup() { + echo "DELETING ${tmpdir}" + rm -rf ${tmpdir} +} + +mkdir -p ${tmpdir} + +trap cleanup 0 + +echo git clone ${giturl} ${dstdir} || exit 1 +git clone ${giturl} ${dstdir} || exit 1 + +(cd ${dstdir}; git checkout gh-pages) + +[ -d ${dstman} ] || mkdir -p ${dstman} + +dirty= +for input in $(find . -name '*.adoc'); do + adoc=${input#./} + html=${adoc%.adoc}.html + output=${dstman}/${html} + + status=$(git status -s $input ) + when=$(git log -n1 --format='%ad' '--date=format-local:%s' $input ) + cat <<EOF > ${output} +--- +version: ${VERSION} +layout: ${LAYOUT} +--- +EOF + + if [ -n "$when" ] + then + epoch="SOURCE_DATE_EPOCH=${when}" + else + epoch= + dirty=yes + fi + if [ -n "$status" ] + then + echo "File $adoc is not checked in!" + dirty=yes + fi + + + env ${epoch} asciidoctor \ + -dmanpage \ + -amansource="${MANSOURCE}" \ + -amanmanual="${MANMANUAL}" \ + -anofooter=yes \ + -askip-front-matter \ + -atoc=left \ + -asource-highlighter=pygments \ + -aicons=font \ + -bhtml5 \ + -o - ${adoc} >> ${output} + chmod 0644 ${output} + + if [ $? -ne 0 ] + then + echo "Failed to process $adoc !" + fails=yes + fi + + + (cd ${dstman}; git add ${html}) +done + +if [ -n "$dirty" ] +then + echo "Repository has uncommited documentation. Aborting." + exit 1 +fi + +if [ -n "$fails" ] +then + echo "Failures formatting documentation. Aborting." + exit 1 +fi + +(cd ${dstman}; git commit -m "man page updates for ${VERSION}"; git push origin gh-pages) |