libnng(3)

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 (DEPRECATED)
nng_socket_get	get socket option
nng_socket_id	get numeric socket identifier
nng_socket_raw	is the socket raw
nng_socket_proto_id	get the socket protocol identifier
nng_socket_proto_name	get the socket protocol name
nng_socket_set	set socket option
nng_sub_subscribe	manage subscriptions

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 (DEPRECATED)
nng_dialer_id	get numeric dialer identifier
nng_dialer_set	set dialer option
nng_dialer_setopt	set dialer option (DEPRECATED)
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 (DEPRECATED)
nng_listener_id	get numeric listener identifier
nng_listener_set	set listener option
nng_listener_setopt	set listener option (DEPRECATED)
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 (DEPRECATED)
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. This is no longer necessary, and applications should not call these functions anymore.

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

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 (DEPRECATED)
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 (DEPRECATED)

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

Logging Support

Common functionality for message logging.

nng_log	log a message
nng_log_set_facility	set log facility
nng_log_set_level	set log level
nng_log_set_logger	set logging handler

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.