= nng_ctx_recv(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_ctx_recv - receive message using context asynchronously

== SYNOPSIS

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

void nng_ctx_recv(nng_ctx ctx, nng_aio *aio);
----

== DESCRIPTION

The `nng_ctx_recv()` receives a xref:nng_msg.5.adoc[message] using the
xref:nng_ctx.5.adoc[context] _s_ asynchronously.

When a message is successfully received by the context, 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.

== RETURN VALUES

None.  (The operation completes asynchronously.)

== ERRORS

[horizontal]
`NNG_ECANCELED`:: The operation was aborted.
`NNG_ECLOSED`:: The context _ctx_ is not open.
`NNG_ENOMEM`:: Insufficient memory is available.
`NNG_ENOTSUP`:: The protocol for context _ctx_ does not support receiving.
`NNG_ESTATE`:: The context _ctx_ 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_ctx.5.adoc[nng_ctx(5)],
xref:nng_msg.5.adoc[nng_msg(5)],
xref:nng.7.adoc[nng(7)]