= nng_recv_aio(3)
//
// 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_recv_aio - receive message asynchronously

== SYNOPSIS

[source, c]
----
#include <nng/nng.h>

void nng_recv_aio(nng_socket s, nng_aio *aio);
----

== DESCRIPTION

The `nng_recv_aio()` receives a xref:nng_msg.5.adoc[message] using the
xref:nng_socket.5.adoc[socket] _s_ asynchronously.

When a message is successfully received by the socket, it is
stored in the _aio_ by an internal call equivalent to
xref:nng_aio_set_msg.3.adoc[`nng_aio_set_msg()`], then the completion
callback on the _aio_ is executed.
In this case, xref:nng_aio_result.3.adoc[`nng_aio_result()`] will
return zero.
The callback function is responsible for retrieving the message
and disposing of it appropriately.

IMPORTANT: Failing to accept and dispose of messages in this
case can lead to memory leaks.

If for some reason the asynchronous receive cannot be completed
successfully (including by being canceled or timing out), then
the callback will still be executed,
but xref:nng_aio_result.3.adoc[`nng_aio_result()`] will be non-zero.

NOTE: The semantics of what receiving a message means varies from protocol to
protocol, so examination of the protocol documentation is encouraged.
(For example, with a xref:nng_pub.7.adoc[_pub_] socket the data is broadcast, so that
any peers who have a suitable subscription will be able to receive it using
xref:nng_recv.3.adoc[`nng_recv()`] or a similar function.)
Furthermore, some protocols may not support receiving (such as
xref:nng_pub.7.adoc[_pub_]) or may require other conditions.
(For example, xref:nng_req.7.adoc[_req_] sockets cannot normally receive data, which
are replies to requests, until they have first sent a request.)

== RETURN VALUES

None.  (The operation completes asynchronously.)

== ERRORS

[horizontal]
`NNG_ECANCELED`:: The operation was aborted.
`NNG_ECLOSED`:: The socket _s_ is not open.
`NNG_ENOMEM`:: Insufficient memory is available.
`NNG_ENOTSUP`:: The protocol for socket _s_ does not support receiving.
`NNG_ESTATE`:: The socket _s_ cannot receive data in this state.
`NNG_ETIMEDOUT`:: The receive timeout expired.

== SEE ALSO

[.text-left]
xref:nng_aio_get_msg.3.adoc[nng_aio_get_msg(3)],
xref:nng_aio_set_msg.3.adoc[nng_aio_set_msg(3)],
xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)],
xref:nng_strerror.3.adoc[nng_strerror(3)],
xref:nng_aio.5.adoc[nng_aio(5)],
xref:nng_msg.5.adoc[nng_msg(5)],
xref:nng_socket.5.adoc[nng_socket(5)],
xref:nng.7.adoc[nng(7)]