| This documentation is for the TIP (development tree) of NNG and may represent unreleased changes or functionality that is experimental, and is subject to change before release. The latest released version is v1.8.0. See the documentation for v1.8.0 for the most up-to-date information. |
NNG Reference Manual
Section 1: Commands and Utilities
This section documents utilities and programs that are included with the distribution.
command line access to Scalability Protocols |
Section 3: Library Functions
This section documents core libary functions supporting Scalability Protocols.
Most Scalability Protocols applications can be written using just the functions documented in this section, as this represents the primary API for building such applications.
nanomsg next generation library |
|
abort asynchronous I/O operation |
|
allocate asynchronous I/O handle |
|
begin asynchronous I/O operation |
|
test if asynchronous I/O is busy |
|
cancel asynchronous I/O operation |
|
return number of bytes transferred |
|
defer asynchronous I/O operation |
|
finish asynchronous I/O operation |
|
free asynchronous I/O handle |
|
return input parameter |
|
get message from asynchronous receive |
|
return output result |
|
return result of asynchronous operation |
|
set input parameter |
|
set scatter/gather vector |
|
set message for asynchronous send |
|
set output result |
|
set asynchronous I/O timeout |
|
stop asynchronous I/O operation |
|
wait for asynchronous I/O operation |
|
allocate memory |
|
create bus socket |
|
close socket |
|
close context |
|
get context option |
|
get context option |
|
return numeric context identifier |
|
create context |
|
receive message using context asynchronously |
|
receive message using socket |
|
send message using context asynchronously |
|
send message using context |
|
set context option |
|
set context option |
|
message forwarding device |
|
create and start dialer |
|
close dialer |
|
create dialer |
|
get dialer option |
|
get dialer option |
|
return numeric dialer identifier |
|
set dialer option |
|
set dialer option |
|
start dialer |
|
free memory |
|
get socket option |
|
register inproc transport |
|
register ipc transport |
|
create and start listener |
|
close listener |
|
create listener |
|
get listener option |
|
get listener option |
|
return numeric listener identifier |
|
set listener option |
|
set listener option |
|
start listener |
|
log messages |
|
get minimum level for logging messagse |
|
set facility used for log messages |
|
set minimum level for logging messagse |
|
set logging handler |
|
allocate a message |
|
append to message body |
|
return message body |
|
return message body length |
|
remove data from end of message body |
|
clear message body content |
|
duplicate a message |
|
free a message |
|
get pipe for message |
|
return message header |
|
append to message header |
|
remove data from end of message header |
|
clear message header |
|
prepend to message header |
|
return message header length |
|
remove data from start of message header |
|
prepend to message body |
|
return message body length |
|
reallocate a message |
|
reserve storage for a message |
|
set pipe for message |
|
remove data from start of message body |
|
create pair socket |
|
close pipe |
|
return dialer that created pipe |
|
get pipe option |
|
get pipe option |
|
return numeric pipe identifier |
|
return listener that created pipe |
|
register pipe notification callback |
|
return owning socket for pipe |
|
create pub socket |
|
create pull socket |
|
create push socket |
|
recv data |
|
receive message asynchronously |
|
receive a message |
|
create rep socket |
|
create req socket |
|
create respondent socket |
|
send data |
|
send message asynchronously |
|
send message |
|
set socket option |
|
sleep asynchronously |
|
get socket option |
|
return numeric socket identifier |
|
set socket option |
|
get statistic Boolean value |
|
get child statistic |
|
get statistic description |
|
find statistic by name |
|
find dialer statistics |
|
find listener statistics |
|
find socket statistics |
|
get statistic name |
|
get next statistic |
|
get statistic string value |
|
get statistic timestamp |
|
get statistic type |
|
get statistic unit |
|
get statistic numeric value |
|
free statistics snapshot |
|
get statistics snapshot |
|
get string representation of socket address |
|
duplicate string |
|
return an error description |
|
free memory |
|
create sub socket |
|
create surveyor socket |
|
register tcp transport |
|
register tls transport |
|
clone URL structure |
|
free a URL structure |
|
create URL structure from a string |
|
report library version |
|
register WebSocket transport |
|
register WebSocket secure transport |
|
register ZeroTier transport |
Section 3compat: Compatible Library Functions
This section documents the nanomsg 1.0 libary compatible functions.
These functions are provided as a transition aid, for application developers coming to NNG from libnanomsg, and are discouraged from use in new applications.
While this is discouraged for long term use, as a transition aid
applications may use the value returned by the
nng_socket_id() in these functions just like a
socket descriptor (as if the socket were opened via
nn_socket()).
This sort of API intermixing should only be used during transition from
the legacy API to the new API.
|
allocate message (compatible API) |
|
accept connections from remote peers (compatible API) |
|
close socket (compatible API) |
|
message control data (compatible API) |
|
connect to remote peer (compatible API) |
|
create forwarding device (compatible API) |
|
return most recent error (compatible API) |
|
free message (compatible API) |
|
get statistic (stub) |
|
get socket option (compatible API) |
|
poll sockets (compatible API) |
|
reallocate message (compatible API) |
|
receive data (compatible API) |
|
receive message (compatible API) |
|
send data (compatible API) |
|
send message (compatible API) |
|
set socket option (compatible API) |
|
shut down endpoint (compatible API) |
|
create socket (compatible API) |
|
return message for error (compatible API) |
|
terminate library (compatible API) |
|
compatibility with nanomsg 1.0 |
Section 3http: Supplemental HTTP Functions
This section documents supplemental HTTP (HyperText Transport Protocol) support functions that are available.
These functions can be used in conjunction with the WebSocket transport for Scalability Protocols, or they may be used to construct other types of applications that communicate using HTTP.
It is also possible to combine the two, such that an HTTP server providing static or dynamic content can also be used to host one or more Scalability Protocols sockets.
| At present NNG only supports HTTP/1.0 and HTTP/1.1. |
allocate HTTP client |
|
establish HTTP client connection |
|
free HTTP client |
|
get HTTP client TLS configuration |
|
set HTTP client TLS configuration |
|
perform one HTTP transaction |
|
close HTTP connection |
|
read from HTTP connection |
|
read all from HTTP connection |
|
read HTTP request |
|
read HTTP response |
|
perform one HTTP transaction on connection |
|
write to HTTP connection |
|
write all to HTTP connection |
|
write HTTP request |
|
write HTTP response |
|
allocate HTTP server handler |
|
set HTTP handler to collect request body |
|
free HTTP server handler |
|
return extra data for HTTP handler |
|
set extra data for HTTP handler |
|
set host for HTTP handler |
|
set HTTP handler method |
|
set HTTP handler to match trees |
|
hijack HTTP server connection |
|
add HTTP request header |
|
allocate HTTP request structure |
|
copy HTTP request body |
|
delete HTTP request header |
|
free HTTP request structure |
|
get HTTP request body |
|
return HTTP request header |
|
return HTTP request method |
|
return HTTP request URI |
|
return HTTP request protocol version |
|
reset HTTP request structure |
|
set HTTP request body |
|
set HTTP request header |
|
set HTTP request method |
|
set HTTP request URI |
|
set HTTP request protocol version |
|
add HTTP response header |
|
allocate HTTP response structure |
|
allocate HTTP error response |
|
copy HTTP response body |
|
delete HTTP response header |
|
free HTTP response structure |
|
get HTTP response body |
|
return HTTP response header |
|
return HTTP response reason |
|
return HTTP status code |
|
return HTTP response protocol version |
|
reset HTTP response structure |
|
set HTTP response body |
|
set HTTP response header |
|
set HTTP response reason |
|
set HTTP response status |
|
set HTTP response protocol version |
|
add HTTP server handler |
|
delete HTTP server handler |
|
get HTTP server address |
|
get HTTP server TLS configuration |
|
get and hold HTTP server instance |
|
release HTTP server instance |
|
use HTTP server error page |
|
set custom HTTP error file |
|
set custom HTTP error page |
|
set HTTP server TLS configuration |
|
start HTTP server |
|
stop HTTP server |
Section 3str: Supplemental TCP Functions
This section documents supplemental byte stream functions that are available.
These functions are made available to facilitate using raw byte stream connections with the NNG asynchronous I/O API. These byte streams may be useful for applications that need to communicate with raw TCP/IP or IPC streams instead of Scalability Protocols.
close byte stream |
|
allocate byte stream dialer |
|
close byte stream dialer |
|
initiate outgoing byte stream connection |
|
free byte stream dialer |
|
get option from byte stream dialer |
|
set option on byte stream dialer |
|
free byte stream |
|
get option from byte stream |
|
accept incoming byte stream connection |
|
allocate byte stream listener |
|
close byte stream listener |
|
free byte stream listener |
|
get option from byte stream listener |
|
bind listener to configured address |
|
set option on byte stream listener |
|
receive from byte stream |
|
send to byte stream |
|
set option on byte stream |
Section 3supp: Supplemental Functions
This section documents supplemental functions that are available. These functions are not intrinsic to building Scalability Protocols applications with this library.
However, their use may facilitate writing portable applications by providing uniform functions for common application needs such as mutual exclusion locks, threading, time keeping, and similar needs.
get time |
|
allocate condition variable |
|
free condition variable |
|
wait for condition or timeout |
|
wait for condition |
|
wake all waiters |
|
wake one waiter |
|
identifier based mapping table |
|
sleep milliseconds |
|
allocate mutex |
|
free mutex |
|
lock mutex |
|
unlock mutex |
|
parse command line options |
|
get random number |
|
create a connected pair of BSD sockets |
|
create thread |
|
reap thread |
|
set thread name |
Section 3tls: Supplemental TLS Functions
This section documents supplemental TLS (Transport Layer Security) functions that are available. TLS support is available when using Scalability Protocols with the TLS transport, or when using WebSocket, either with the WebSocket transport for Scalability Protocols, or combined with other HTTP capabilities.
These functions depend on library support that is not included directly with NNG however, so their presence will depend on whether this additional support was present and enabled with libnng was built.
Currently, this extra support can be provided by the mbedTLS library or by external plug-ins.
| Contact Staysail Systems, Inc. for details about commercially available options, including support for FIPS 140-2 validated cryptography and TLS v1.3. |
allocate TLS configuration object |
|
configure authentication mode |
|
configure certificate authority certificate chain |
|
load certificate authority from file |
|
load own certificate and key from file |
|
deallocate a TLS configuration object |
|
hold TLS configuration object |
|
configure own certificate and key |
|
configure remote server name |
|
configure TLS version |
|
TLS engine description |
|
TLS FIPS 140-2 mode indicator |
|
TLS engine name |
Section 5: Macros and Types
This section documents core macros and types that are available.
These are the core types and macros that most Scalabilty Protocols applications need will use.
asynchronous I/O handle |
|
protocol context |
|
dialer |
|
relative time in milliseconds |
|
scatter/gather element |
|
IPC-specific options |
|
listener |
|
message |
|
socket, dialer, listener, and pipe options |
|
communications pipe |
|
socket address |
|
abstract IPC socket address |
|
IPv4 socket address |
|
IPv6 socket address |
|
inproc socket address |
|
IPC socket address |
|
ZeroTier socket address |
|
socket handle |
|
statistic |
|
byte stream |
|
byte stream dialer |
|
byte stream listener |
|
TCP-specific options |
|
TLS configuration object |
|
TLS engine implementation |
|
TLS-specific options |
|
Universal Resource Locator object |
Section 7: Protocols and Transports
This sections documents various protocols and transports that are available in the distribution.
Protocols implement communication patterns, such as request/reply, publish/subscribe, and so forth. A given socket is created with exactly one protocol, and that protocol defines the key behavior of the socket.
Conversely, transports are the underlying mechansims by which messages are moved between participants, such as TCP/IP or UNIX domain IPC. A given socket may be using several transports at the same time.
nanomsg next generation |
|
bus protocol |
|
intra-process transport |
|
IPC transport |
|
pair protocol |
|
publisher protocol |
|
pull protocol |
|
push protocol |
|
reply protocol |
|
request protocol |
|
respondent protocol |
|
BSD Socket transport (experimental) |
|
subscriber protocol |
|
surveyor protocol |
|
TCP/IP transport |
|
TLS transport |
|
WebSocket transport |
|
ZeroTier transport |