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 |
|
cancel asynchronous I/O operation |
|
return number of bytes transferred |
|
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 |
|
return numeric context identifier |
|
create context |
|
receive message using context asynchronously |
|
send message using context asynchronously |
|
set context option |
|
send message |
|
create and start dialer |
|
close dialer |
|
create dialer |
|
get dialer option |
|
return numeric dialer identifier |
|
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 |
|
return numeric listener identifier |
|
set listener option |
|
start listener |
|
allocate a message |
|
append to message body |
|
return message body |
|
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 |
|
set pipe for message |
|
remove data from start of message body |
|
create pair socket |
|
close pipe |
|
return dialer that created pipe |
|
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 |
|
recv message |
|
create rep socket |
|
create rep socket |
|
create respondent socket |
|
send data |
|
send message asynchronously |
|
send message |
|
set socket option |
|
sleep asynchronously |
|
return numeric socket identifier |
|
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.
Tip
|
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.
allocate HTTP client |
|
establish HTTP client connection |
|
free HTTP client |
|
get HTTP client TLS configuration |
|
set HTTP client TLS configuration |
|
close HTTP connection |
|
read from HTTP connection |
|
read all from HTTP connection |
|
read HTTP request |
|
read HTTP response |
|
write to HTTP connection |
|
write all to HTTP connection |
|
write HTTP request |
|
write HTTP response |
|
allocate HTTP server handler |
|
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 |
|
set HTTP request header |
|
free HTTP request structure |
|
return HTTP request header |
|
return HTTP request method |
|
return HTTP request URI |
|
return HTTP request protocol version |
|
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 |
|
set HTTP response header |
|
free HTTP response structure |
|
return HTTP response header |
|
return HTTP response reason |
|
return HTTP status code |
|
return HTTP response protocol version |
|
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 TLS configuration |
|
get and hold HTTP server instance |
|
release HTTP server instance |
|
set HTTP server TLS configuration |
|
start HTTP server |
|
stop HTTP server |
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 |
|
sleep milliseconds |
|
allocate mutex |
|
free mutex |
|
lock mutex |
|
lock mutex |
|
parse command line options |
|
get random number |
|
create thread |
|
reap thread |
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.
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 |
|
configure own certificate and key |
|
configure remote server 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 |
|
listener |
|
message |
|
socket, dialer, listener, and pipe options |
|
communications pipe |
|
socket address |
|
IPv4 socket address |
|
IPv6 socket address |
|
inproc socket address |
|
IPC socket address |
|
ZeroTier socket address |
|
socket handle |
Section 7: Protocols and Transports
This sections documents various protocols and transports that are available in the distribution.
Protocols represent “patterns” of communication, 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 |
|
subscriber protocol |
|
surveyor protocol |
|
TCP/IP transport |
|
TLS transport |
|
WebSocket transport |
|
ZeroTier transport |