SYNOPSIS
#include <nn/nn.h>DESCRIPTION
The nng library provides source-level compatibility for most nanomsg 1.0 applications.
| This is intended to faciliate converting legacy applications to use the nng library. New applications shoud not use the newer nng API instead. |
Applications making use of this compatibility layer take care to link with libnng instead of libnn.
| Some capabilities, protocols, and transports, will not be accessible using this API, as the compatible API has no provision for expression of certain concepts introduced in the newer nng API. |
| While reasonable efforts have been made to provide for compatibility, some things may behave differently, and some less common parts of the nanomsg 1.0 API are not supported at this time, including certain options and the statistics API. |
| If an installation of the older nanomsg library is present on the build system, it may be necessary to provide a different search path for header files to ensure that the compatibility definitions are used in compilation. |
Functions
The following functions are provided:
|
create a socket |
|
get socket option |
|
set socket option |
|
accept connections from remote peers |
|
connect to remote peer |
|
send data |
|
receive data |
|
shut down endpoint |
|
close socket |
|
poll sockets |
|
create forwarding device |
|
receive message |
|
send message |
|
get statistic (stub) |
|
allocate message |
|
reallocate message |
|
free message |
|
return most recent error |
|
return message for error |
|
terminate library |
| Documentation for the compatibility functions will be supplied here later. In the meantime it can be found online at the nanomsg site. |
There are a few caveats, that should be kept in mind.
| Socket numbers can be quite large. The legacy libnanomsg attempted to reuse socket numbers, like file descriptors in UNIX systems. The nng library avoids this to prevent accidental reuse or collision after a descriptor is closed. Consequently, socket numbers can become quite large, and should probably not be used for array indices. |
The following options (nn_getsockopt) are unsupported:
NN_PROTOCOL, NN_SNDPRIO, NN_RCVPRIO, NN_IPV4ONLY.
Some of these will probably be added back in the future when
the relevant support is added to nng.
|
Statistics (nn_get_statistic) are unsupported.
The plan is to support statistics in the native nng API, but
we think there is no need for this in a compatibility layer.
Hence, this function returns ENOTSUP.
|
| Some transports can support longer URLs than legacy libnanomsg can. It is a good idea to use short pathnames in URLs if interoperability is a concern. |
| Some transports are unusable from this mode. In particular, this legacy API offers no way to configure TLS parameters that are required for use. |
ABI versioning is not supported.
We don’t offer the NN_VERSION_ macros. Sorry.
|
Runtime symbol information is not implemented.
Specifically, there is no nn_symbol() function yet.
(This may be addressed later if there is a need.)
|
The nn_term() function is destructive and should be avoided.
This function closes down all sockets, and really there is no good
reason to ever use it.
Removal from existing code is advised.
(Keep track of sockets and close them explicitly if necessary.)
|
| It is possible at present to intermix sockets between the new and the old APIs, but this is not a guaranteed feature, and should only be used temporarily to facilitate transitioning code to the new APIs. |