libnng.3.adoc

libnng(3)

NAME

libnng - nanomsg next generation library

SYNOPSIS

cc [flags] files -lnng [libraries]

DESCRIPTION

NNG 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()	allocate memory
nng_free()	free memory
nng_strdup()	duplicate string
nng_strerror()	return an error description
nng_strfree()	free string
nng_version()	report library version

Socket Functions

The following functions operate on sockets.

nng_close()	close socket
nng_dial()	create and start dialer
nng_getopt()	get socket option
nng_listen()	create and start listener
nng_recv()	receive data
nng_send()	send data
nng_setopt()	set socket option
nng_socket_get()	get socket option
nng_socket_id()	get numeric socket identifier
nng_socket_set()	set socket option

Connection Management

The following functions are used with either listeners, or dialers. Listeners accept incoming connection requests, and dialers make them.

nng_dial()	create and start dialer
nng_dialer_close()	close dialer
nng_dialer_create()	create dialer
nng_dialer_get()	get dialer option
nng_dialer_getopt()	get dialer option
nng_dialer_id()	get numeric dialer identifier
nng_dialer_set()	set dialer option
nng_dialer_setopt()	set dialer option
nng_dialer_start()	start dialer
nng_listen()	create and start listener
nng_listener_close()	close listener
nng_listener_create()	create listener
nng_listener_get()	get listener option
nng_listener_getopt()	get listener option
nng_listener_id()	get numeric listener identifier
nng_listener_set()	set listener option
nng_listener_setopt()	set listener option
nng_listener_start()	start listener
nng_pipe_close()	close pipe
nng_pipe_dialer()	return dialer that created pipe
nng_pipe_get()	get pipe option
nng_pipe_getopt()	get pipe option
nng_pipe_id()	get numeric pipe identifier
nng_pipe_listener()	return listener that created pipe
nng_pipe_notify()	register pipe notification callback
nng_pipe_socket()	return owning socket for pipe

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()	allocate a message
nng_msg_append()	append to message body
nng_msg_body()	return message body
nng_msg_capacity()	return capacity allocated for message body
nng_msg_chop()	remove data from end of message body
nng_msg_clear()	clear message body
nng_msg_dup()	duplicate a message
nng_msg_free()	free a message
nng_msg_get_pipe()	get pipe for message
nng_msg_insert()	prepend to message body
nng_msg_len()	return the message body length
nng_msg_realloc()	reallocate a message
nng_msg_reserve()	reserve storage for message body
nng_msg_set_pipe()	set pipe for message
nng_msg_trim()	remove data from start of message body
nng_recvmsg()	receive a message
nng_sendmsg()	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()	return message header
nng_msg_header_append()	append to message header
nng_msg_header_chop()	remove data from end of message header
nng_msg_header_clear()	clear message header
nng_msg_header_insert()	prepend to message header
nng_msg_header_len()	return the message header length
nng_msg_header_trim()	remove data from start of message header

Asynchronous Operations

Most applications will interact with NNG synchronously; that is that functions such as 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 is executed.

A context structure, an nng_aio, is allocated and associated with each asynchronous operation. Only a single asynchronous operation may be associated with an nng_aio at any time.

The following functions are used in the asynchronous model:

nng_aio_abort()	abort asynchronous I/O operation
nng_aio_alloc()	allocate asynchronous I/O handle
nng_aio_begin()	begin asynchronous I/O operation
nng_aio_busy()	test if asynchronous I/O is busy
nng_aio_cancel()	cancel asynchronous I/O operation
nng_aio_count()	return number of bytes transferred
nng_aio_defer()	defer asynchronous I/O operation
nng_aio_finish()	finish asynchronous I/O operation
nng_aio_free()	free asynchronous I/O handle
nng_aio_get_input()	return input parameter
nng_aio_get_msg()	get message from an asynchronous receive
nng_aio_get_output()	return output result
nng_aio_reap()	reap asynchronous I/O handle
nng_aio_result()	return result of asynchronous operation
nng_aio_set_input()	set input parameter
nng_aio_set_iov()	set scatter/gather vector
nng_aio_set_msg()	set message for an asynchronous send
nng_aio_set_output()	set output result
nng_aio_set_timeout()	set asynchronous I/O timeout
nng_aio_stop()	stop asynchronous I/O operation
nng_aio_wait()	wait for asynchronous I/O operation
nng_recv_aio()	receive message asynchronously
nng_send_aio()	send message asynchronously
nng_sleep_aio()	sleep asynchronously

Protocols

The following functions are used to construct a socket with a specific protocol:

nng_bus_open()	open a bus socket
nng_pair_open()	open a pair socket
nng_pub_open()	open a pub socket
nng_pull_open()	open a pull socket
nng_push_open()	open a push socket
nng_rep_open()	open a rep socket
nng_req_open()	open a req socket
nng_respondent_open()	open a respondent socket
nng_sub_open()	open a sub socket
nng_surveyor_open()	open a surveyor socket

Transports

The following functions are used to register a transport for use.

nng_inproc_register()	register inproc transport
nng_ipc_register()	register IPC transport
nng_tcp_register()	register TCP transport
nng_tls_register()	register TLS transport
nng_ws_register()	register WebSocket transport
nng_wss_register()	register WebSocket Secure transport
nng_zt_register()	register ZeroTier transport

Protocol Contexts

The following functions are useful to separate the protocol processing from a socket object, into a separate context. This can allow multiple contexts to be created on a single socket for concurrent applications.

nng_ctx_close()	close context
nng_ctx_get()	get context option
nng_ctx_getopt()	get context option
nng_ctx_id()	get numeric context identifier
nng_ctx_open()	create context
nng_ctx_recv()	receive message using context asynchronously
nng_ctx_recvmsg()	receive a message using context
nng_ctx_send()	send message using context asynchronously
nng_ctx_sendmsg()	send a message using context
nng_ctx_set()	set context option
nng_ctx_setopt()	set context option

Devices, Relays

The following function family is used to create forwarders or relayers that route messages from one socket to another.

nng_device()

message forwarding device

Statistics

The following functions provide access to statistics which can be used to observe program behaviors and as an aid in troubleshooting.

nng_stat_bool()	get statistic Boolean value
nng_stat_child()	get child statistic
nng_stat_name()	get statistic description
nng_stat_find()	find statistic by name
nng_stat_find_dialer()	find dialer statistics
nng_stat_find_listener()	find listener statistics
nng_stat_find_socket()	find socket statistics
nng_stat_name()	get statistic name
nng_stat_next()	get next statistic
nng_stat_string()	get statistic string value
nng_stat_timestamp()	get statistic timestamp
nng_stat_type()	get statistic type
nng_stat_unit()	get statistic unit
nng_stat_value()	get statistic numeric value
nng_stats_free()	free statistics
nng_stats_get()	get statistics

URL Object

Common functionality is supplied for parsing and handling universal resource locators (URLS).

nng_url_clone()	clone URL structure
nng_url_free()	free URL structure
nng_url_parse()	create URL structure from string

Supplemental API

These supplemental functions are not intrinsic to building network applications with NNG, but they are made available as a convenience to aid in creating portable applications.

nng_clock()	get time
nng_cv_alloc()	allocate condition variable
nng_cv_free()	free condition variable
nng_cv_until()	wait for condition or timeout
nng_cv_wait()	wait for condition
nng_cv_wake()	wake all waiters
nng_cv_wake1()	wake one waiter
nng_id_map	identifier based mapping table
nng_msleep()	sleep for milliseconds
nng_mtx_alloc()	allocate mutex
nng_mtx_free()	free mutex
nng_mtx_lock()	lock mutex
nng_mtx_unlock()	unlock mutex
nng_opts_parse()	parse command line options
nng_random()	get random number
nng_socket_pair()	create connected pair of BSD sockets
nng_thread_create()	create thread
nng_thread_destroy()	reap thread
nng_thread_set_name()	set thread name

Byte Streams

These functions are available for use with byte streams. They are considered low-level, for uses where the higher level functions using Scalability Protocols are inappropriate.

Byte streams, represented by nng_stream objects, correspond to underlying connections such as TCP connections or named pipes. They are created by either nng_stream_dialer or nng_stream_listener objects.

nng_stream_close()	close byte stream
nng_stream_dialer_alloc()	allocate byte stream dialer
nng_stream_dialer_close()	close byte stream dialer
nng_stream_dialer_dial()	initiate outgoing byte stream
nng_stream_dialer_free()	free byte stream dialer
nng_stream_dialer_get()	get option from byte stream dialer
nng_stream_dialer_set()	set option on byte stream dialer
nng_stream_free()	free byte stream
nng_stream_get()	get option from byte stream
nng_stream_listener_accept()	accept incoming byte stream
nng_stream_listener_alloc()	allocate byte stream listener
nng_stream_listener_close()	close byte stream listener
nng_stream_listener_free()	free byte stream listener
nng_stream_listener_get()	get option from byte stream listener
nng_stream_listener_listen()	bind byte stream listener to address
nng_stream_listener_set()	set option on byte stream listener
nng_stream_recv()	receive from byte stream
nng_stream_send()	send to byte stream
nng_stream_set()	set option on byte stream

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()	close HTTP connection
nng_http_conn_read()	read from HTTP connection
nng_http_conn_read_all()	read all from HTTP connection
nng_http_conn_read_req()	read HTTP request
nng_http_conn_read_res()	read HTTP response
nng_http_conn_write()	write to HTTP connection
nng_http_conn_write_all()	write all to HTTP connection
nng_http_conn_write_req()	write HTTP request
nng_http_conn_write_res()	write HTTP response
nng_http_req_add_header()	add HTTP request header
nng_http_req_alloc()	allocate HTTP request structure
nng_http_req_copy_data()	copy HTTP request body
nng_http_req_del_header()	delete HTTP request header
nng_http_req_free()	free HTTP request structure
nng_http_req_get_data()	get HTTP request body
nng_http_req_get_header()	return HTTP request header
nng_http_req_get_method()	return HTTP request method
nng_http_req_get_uri()	return HTTP request URI
nng_http_req_get_version()	return HTTP request protocol version
nng_http_req_reset()	reset HTTP request structure
nng_http_req_set_data()	set HTTP request body
nng_http_req_set_header()	set HTTP request header
nng_http_req_set_method()	set HTTP request method
nng_http_req_set_uri()	set HTTP request URI
nng_http_req_set_version()	set HTTP request protocol version
nng_http_res_add_header()	add HTTP response header
nng_http_res_alloc()	allocate HTTP response structure
nng_http_res_alloc_error()	allocate HTTP error response
nng_http_res_copy_data()	copy HTTP response body
nng_http_res_del_header()	delete HTTP response header
nng_http_res_free()	free HTTP response structure
nng_http_res_get_data()	get HTTP response body
nng_http_res_get_header()	return HTTP response header
nng_http_res_get_reason()	return HTTP response reason
nng_http_res_get_status()	return HTTP response status
nng_http_res_get_version()	return HTTP response protocol version
nng_http_res_reset()	reset HTTP response structure
nng_http_res_set_data()	set HTTP response body
nng_http_res_set_header()	set HTTP response header
nng_http_res_set_reason()	set HTTP response reason
nng_http_res_set_status()	set HTTP response status
nng_http_res_set_version()	set HTTP response protocol version

HTTP Client Functions

These functions are intended for use with HTTP client applications.

nng_http_client_alloc()	allocate HTTP client
nng_http_client_connect()	establish HTTP client connection
nng_http_client_free()	free HTTP client
nng_http_client_get_tls()	get HTTP client TLS configuration
nng_http_client_set_tls()	set HTTP client TLS configuration
nng_http_client_transact()	perform one HTTP transaction
nng_http_conn_transact()	perform one HTTP transaction on connection

HTTP Server Functions

These functions are intended for use with HTTP server applications.

nng_http_handler_alloc()	allocate HTTP server handler
nng_http_handler_collect_body()	set HTTP handler to collect request body
nng_http_handler_free()	free HTTP server handler
nng_http_handler_get_data()	return extra data for HTTP handler
nng_http_handler_set_data()	set extra data for HTTP handler
nng_http_handler_set_host()	set host for HTTP handler
nng_http_handler_set_method()	set HTTP handler method
nng_http_handler_set_tree()	set HTTP handler to match trees
nng_http_hijack()	hijack HTTP server connection
nng_http_server_add_handler()	add HTTP server handler
nng_http_server_del_handler()	delete HTTP server handler
nng_http_server_get_addr()	get HTTP server address
nng_http_server_get_tls()	get HTTP server TLS configuration
nng_http_server_hold()	get and hold HTTP server instance
nng_http_server_release()	release HTTP server instance
nng_http_server_set_error_file()	set custom HTTP error file
nng_http_server_set_error_page()	set custom HTTP error page
nng_http_server_set_tls()	set HTTP server TLS configuration
nng_http_server_res_error()	use HTTP server error page
nng_http_server_start()	start HTTP server
nng_http_server_stop()	stop HTTP server

TLS Configuration Objects

The following functions are used to manipulate transport layer security (TLS) configuration objects. Most of these functions will not be used even by TLS applications.

Note	These functions will only be present if the library has been built with TLS support.

nng_tls_config_alloc()	allocate TLS configuration
nng_tls_config_auth_mode()	set authentication mode
nng_tls_config_ca_chain()	set certificate authority chain
nng_tls_config_ca_file()	load certificate authority from file
nng_tls_config_cert_key_file()	load own certificate and key from file
nng_tls_config_psk()	set pre-shared key and identity
nng_tls_config_own_cert()	set own certificate and key
nng_tls_config_free()	free TLS configuration
nng_tls_config_server_name()	set remote server name

MQTT Support

The library support MQTT V3.1.1 for now (V5.0 is being prepared for development)

MQTT Message Handling

nng_mqtt_msg_alloc()	allocate a message with proto_data for mqtt
nng_mqtt_msg_decode()	decode a mqtt bytes stream from nng_msg_body and nng_msg_header to proto_data
nng_mqtt_msg_encode()	encode a mqtt message from proto_data to nng_msg_body and nng_msg_header
nng_mqtt_msg_get_connect()	get mqtt connect message
nng_mqtt_msg_get_packet_type()	get mqtt packet type
nng_mqtt_msg_get_publish()	get mqtt publish message
nng_mqtt_msg_get_subscribe()	get mqtt subscribe message
nng_mqtt_msg_get_unsubscribe()	get mqtt unsubscribe message
nng_mqtt_msg_set_connect()	set mqtt connect message
nng_mqtt_msg_set_packet_type()	set mqtt packet type
nng_mqtt_msg_set_publish()	set mqtt publish message
nng_mqtt_msg_set_subscribe()	set mqtt subscribe message
nng_mqtt_msg_set_unsubscribe()	set mqtt unsubscribe message

MQTT Client Functions

These functions are intended for use with MQTT client applications.

nng_mqtt_client_open	open mqtt client socket
nng_mqtt_set_connect_cb	set mqtt connect callback function
nng_mqtt_set_disconnect_cb	set mqtt disconnect callback function

SEE ALSO

nng_compat(3compat), nng(7)