path: root/man/tip/nng_ctx_send.3.html

---
version: tip
layout: manpage_v2
title: nng_ctx_send(3)
---
<h1>nng_ctx_send(3)</h1>
<div class="sect1">
<h2 id="_name">NAME</h2>
<div class="sectionbody">
<div class="paragraph">
<p>nng_ctx_send - send message using context asynchronously</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_synopsis">SYNOPSIS</h2>
<div class="sectionbody">
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf">&lt;nng/nng.h&gt;</span>

<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_send</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">);</span></code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_description">DESCRIPTION</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The <code>nng_ctx_send()</code> sends a <a href="nng_msg.5.html">message</a> using the
<a href="nng_ctx.5.html">context</a> <em>ctx</em> asynchronously.</p>
</div>
<div class="paragraph">
<p>The message to send must have previously been set on the <em>aio</em>
using the <a href="nng_aio_set_msg.3.html"><code>nng_aio_set_msg()</code></a> function.
The function assumes ownership of the message.</p>
</div>
<div class="paragraph">
<p>If the message was successfully queued for delivery to the socket,
then the <em>aio</em> will be completed, and <a href="nng_aio_result.3.html"><code>nng_aio_result()</code></a>
will return zero.
In this case the socket will dispose of the message when it is finished with it.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The operation will be completed, and the callback associated
with the <em>aio</em> executed, as soon as the socket accepts the message
for sending.
This does <em>not</em> indicate that the message was actually delivered, as it
may still be buffered in the sending socket, buffered in the receiving
socket, or in flight over physical media.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>If the operation fails for any reason (including cancellation or timeout),
then the <em>aio</em> callback will be executed and
<a href="nng_aio_result.3.html"><code>nng_aio_result()</code></a> will return a non-zero error status.
In this case, the callback has a responsibility to retrieve the message from
the <em>aio</em> with <a href="nng_aio_get_msg.3.html"><code>nng_aio_get_msg()</code></a> and dispose of
it appropriately.
(This may include retrying the send operation on the same or a different
socket, or deallocating the message with <a href="nng_msg_free.3.html"><code>nng_msg_free()</code></a>.)</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The semantics of what sending a message means varies from protocol to
protocol, so examination of the protocol documentation is encouraged.
</td>
</tr>
</table>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
Context send operations are asynchronous.
If a synchronous operation is needed, one can be constructed by using a
<code>NULL</code> callback on the <em>aio</em> and then waiting for the operation using
<a href="nng_aio_wait.3.html"><code>nng_aio_wait()</code></a>.
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_return_values">RETURN VALUES</h2>
<div class="sectionbody">
<div class="paragraph">
<p>None.  (The operation completes asynchronously.)</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_errors">ERRORS</h2>
<div class="sectionbody">
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
<code>NNG_ECANCELED</code>
</td>
<td class="hdlist2">
<p>The operation was aborted.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<code>NNG_ECLOSED</code>
</td>
<td class="hdlist2">
<p>The context <em>ctx</em> is not open.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<code>NNG_EMSGSIZE</code>
</td>
<td class="hdlist2">
<p>The message is too large.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<code>NNG_ENOMEM</code>
</td>
<td class="hdlist2">
<p>Insufficient memory is available.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<code>NNG_ENOTSUP</code>
</td>
<td class="hdlist2">
<p>The protocol for context <em>ctx</em> does not support sending.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<code>NNG_ESTATE</code>
</td>
<td class="hdlist2">
<p>The context <em>ctx</em> cannot send data in this state.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<code>NNG_ETIMEDOUT</code>
</td>
<td class="hdlist2">
<p>The send timeout expired.</p>
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_see_also">SEE ALSO</h2>
<div class="sectionbody">
<div class="paragraph text-left">
<p><a href="nng_aio_get_msg.3.html">nng_aio_get_msg(3)</a>,
<a href="nng_aio_set_msg.3.html">nng_aio_set_msg(3)</a>,
<a href="nng_msg_alloc.3.html">nng_msg_alloc(3)</a>,
<a href="nng_strerror.3.html">nng_strerror(3)</a>,
<a href="nng_aio.5.html">nng_aio(5)</a>,
<a href="nng_ctx.5.html">nng_ctx(5)</a>,
<a href="nng_msg.5.html">nng_msg(5)</a>,
<a href="nng.7.html">nng(7)</a></p>
</div>
</div>
</div>