= 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 "`owned`"
by 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 "`owning`" 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)]