= nng_listener(5)
|
//
|
// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
|
// Copyright 2018 Capitar IT Group BV <info@capitar.com>
|
//
|
// This document is supplied under the terms of the MIT License, a
|
// copy of which should be located in the distribution where this
|
// file was obtained (LICENSE.txt). A copy of the license may also be
|
// found online at https://opensource.org/licenses/MIT.
|
//
|
|
== NAME
|
|
nng_listener - listener
|
|
== SYNOPSIS
|
|
[source, c]
|
----
|
#include <nng/nng.h>
|
|
typedef struct nng_listener_s nng_listener;
|
----
|
|
== DESCRIPTION
|
|
(((listener)))
|
An `nng_listener` is a handle to a listener object, which is responsible for
|
creating xref:nng_pipe.5.adoc[`nng_pipe`] objects by accepting incoming connections.
|
A given listener object may create many pipes at the same time, much like an
|
HTTP server can have many connections to multiple clients simultaneously.
|
|
Listener objects are created by the
|
xref:nng_listener_create.3.adoc[`nng_listener_create()`]
|
or xref:nng_listen.3.adoc[`nng_listen()`] functions, and are always associated
|
with a single xref:nng_socket.5.adoc[`nng_socket`].
|
|
IMPORTANT: The `nng_listener` structure is always passed by value (both
|
for input parameters and return values), and should be treated opaquely.
|
Passing structures this way gives the compiler a chance to perform
|
accurate type checks in functions passing values of this type.
|
|
TIP: A given xref:nng_socket.5.adoc[`nng_socket`] may have multiple listener
|
objects, multiple xref:nng_dialer.5.adoc[dialer] objects, or even some
|
of both.
|
|
TIP: The client/server relationship described by dialer/listener is
|
completely orthogonal to any similar relationship in the protocols.
|
For example, a xref:nng_rep.7.adoc[_rep_] socket may use a dialer
|
to connect to a listener on an xref:nng_req.7.adoc[_req_] socket.
|
This orthogonality can lead to innovative solutions to otherwise
|
challenging communications problems.
|
|
Listener objects may be destroyed by the
|
xref:nng_listener_close.3.adoc[`nng_listener_close()`] function.
|
They are also closed when their associated socket is closed.
|
|
[[NNG_LISTENER_INITIALIZER]]
|
=== Initialization
|
|
A listener may be initialized using the macro `NNG_LISTENER_INITIALIZER`
|
before it is opened, to prevent confusion with valid open listener.
|
|
== SEE ALSO
|
|
[.text-left]
|
xref:nng_listen.3.adoc[nng_listen(3)],
|
xref:nng_listener_close.3.adoc[nng_listener_close(3)],
|
xref:nng_listener_create.3.adoc[nng_listener_create(3)],
|
xref:nng_listener_getopt.3.adoc[nng_listener_getopt(3)],
|
xref:nng_listener_id.3.adoc[nng_listener_id(3)],
|
xref:nng_listener_setopt.3.adoc[nng_listener_setopt(3)],
|
xref:nng_listener_start.3.adoc[nng_listener_start(3)],
|
xref:nng_dialer.5.adoc[nng_dialer(5)],
|
xref:nng_pipe.5.adoc[nng_pipe(5)],
|
xref:nng_socket.5.adoc[nng_socket(5)],
|
xref:nng.7.adoc[nng(7)]
|
