diff options
Diffstat (limited to 'docs/libnng.adoc')
| -rw-r--r-- | docs/libnng.adoc | 313 |
1 files changed, 0 insertions, 313 deletions
diff --git a/docs/libnng.adoc b/docs/libnng.adoc deleted file mode 100644 index 72516705..00000000 --- a/docs/libnng.adoc +++ /dev/null @@ -1,313 +0,0 @@ -= 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)>> |