SYNOPSIS
#include <nng/nng.h>
int nng_listen(nng_socket s, const char *url, nng_listener *lp, int flags);DESCRIPTION
The nng_listener() function creates a newly initialized
listener, associated with socket s, and configured to listen at the
address specified by url. If the value of lp is not NULL, then
the newly created listener is stored at the address indicated by lp.
Listeners are used to accept connections initiated by remote dialers. An incoming connection generally results in a pipe being created and attached to the socket s. Unlike dialers, listeners generally can create many pipes, which may be open concurrently.
| While it is convenient to think of listeners as "servers", the relationship between the listener or dialer is orthogonal to any server or client status that might be associated with a given protocol. For example, a REQ socket might have associated dialers, but might also have associated listeners. It may even have some of each at the same time! |
Normally, the act of "binding" to the address indicated by url is done
synchronously, including any necessary name resolution. As a result,
a failure, such as if the address is already in use, will be returned
immediately. However, if the special value NNG_FLAG_NONBLOCK is
supplied in flags, then this is done asynchronously; furthermore any
failure to bind will be periodically reattempted in the background.
While NNG_FLAG_NONBLOCK can help an application be more resilient,
it also generally makes diagnosing failures somewhat more difficult.
|
Because the listener is started immediately, it is generally not possible to apply extra configuration; if that is needed applications should consider using nng_listener_create(3) and nng_listener_start(3) instead.
The created listener will continue to accept new connections, associating their pipes with the socket, until either it or the socket s is closed.
RETURN VALUES
This function returns 0 on success, and non-zero otherwise.
ERRORS
NNG_EADDRINUSE-
The address specified by url is already in use.
NNG_EADDRINVAL-
An invalid url was specified.
NNG_ECLOSED-
The socket s is not open.
NNG_EINVAL-
An invalid set of flags was specified.
NNG_ENOMEM-
Insufficient memory is available.