<trclass="memdesc:ga1a091d24f939d881bf04fba78b8995c2"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Destroys this list of messages. <br/></td></tr>
<trclass="memdesc:ga098e4fec1c5a71c00a0d092fbd6d1a21"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Creates a <aclass="el"href="group__types_group.html#gadcab54026c4ed78f344ce03ce31bb61a"title="A structure holding a subject, optional reply and payload.">natsMsg</a> object. <br/></td></tr>
<trclass="memdesc:gad7cad38946648e3047aa0665a3dd230a"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Returns the subject set in this message. <br/></td></tr>
<trclass="memdesc:ga880535362c91b3e405792aa66ff945b6"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Returns the reply set in this message. <br/></td></tr>
<trclass="memdesc:ga523364451fd92534e754054266196e59"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Returns the message payload. <br/></td></tr>
<trclass="memdesc:ga25b69066ae50287e178aaf4f70f7d3de"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Returns the message length. <br/></td></tr>
<trclass="memdesc:gaf30b47d4217c9335919f05536e379af8"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Set the header entries associated with <code>key</code> to the single element <code>value</code>. <br/></td></tr>
<trclass="memdesc:ga2b641ec3b1745604d7de1102e472254b"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Add <code>value</code> to the header associated with <code>key</code>. <br/></td></tr>
<trclass="memdesc:gab3349f0b0ce721b340d5c0753c90ee18"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Get the header entry associated with <code>key</code>. <br/></td></tr>
<trclass="memdesc:gae1ce9c9d82d151a3ea9dc03da048f66f"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Get all header values associated with <code>key</code>. <br/></td></tr>
<trclass="memdesc:gac78ca02dc93d05cae837ced6386408f1"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Delete the value(s) associated with <code>key</code>. <br/></td></tr>
<trclass="memdesc:ga43aa4a8e4b93725b4876ee2677e19c7b"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Indicates if this message is a "no responders" message from the server. <br/></td></tr>
<trclass="memdesc:ga9e9590018284939f43f60964283f33ae"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Destroys the message object. <br/></td></tr>
<p>This function iterates through the list of all messages and call <aclass="el"href="group__msg_group.html#ga9e9590018284939f43f60964283f33ae"title="Destroys the message object.">natsMsg_Destroy</a> for each valid (not set to <code>NULL</code>) message. It then frees the array that was allocated to hold pointers to those messages.</p>
<dlclass="section note"><dt>Note</dt><dd>The <aclass="el"href="structnats_msg_list.html"title="A list of NATS messages.">natsMsgList</a> object itself is not freed since it is expected that users will pass a pointer to a stack object. Should the user create its own object, it will be the user responsibility to free this object.</dd></dl>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">list</td><td>the <aclass="el"href="structnats_msg_list.html"title="A list of NATS messages.">natsMsgList</a> list of <aclass="el"href="group__types_group.html#gadcab54026c4ed78f344ce03ce31bb61a"title="A structure holding a subject, optional reply and payload.">natsMsg</a> objects to destroy. </td></tr>
<p>Creates a <aclass="el"href="group__types_group.html#gadcab54026c4ed78f344ce03ce31bb61a"title="A structure holding a subject, optional reply and payload.">natsMsg</a> object. This is used by the subscription related calls and by <aclass="el"href="group__conn_pub_group.html#ga74511acd87385931112c45c48c2a14ba"title="Publishes a message on a subject.">natsConnection_PublishMsg()</a>.</p>
<dlclass="section note"><dt>Note</dt><dd>Messages need to be destroyed with <aclass="el"href="group__msg_group.html#ga9e9590018284939f43f60964283f33ae"title="Destroys the message object.">natsMsg_Destroy()</a> when no longer needed.</dd></dl>
<dlclass="section see"><dt>See also</dt><dd><aclass="el"href="group__msg_group.html#ga9e9590018284939f43f60964283f33ae"title="Destroys the message object.">natsMsg_Destroy()</a></dd></dl>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">newMsg</td><td>the location where to store the pointer to the newly created <aclass="el"href="group__types_group.html#gadcab54026c4ed78f344ce03ce31bb61a"title="A structure holding a subject, optional reply and payload.">natsMsg</a> object. </td></tr>
<tr><tdclass="paramname">subj</td><td>the subject this message will be sent to. Cannot be <code>NULL</code>. </td></tr>
<tr><tdclass="paramname">reply</td><td>the optional reply for this message. </td></tr>
<dlclass="section warning"><dt>Warning</dt><dd>The string belongs to the message and must not be freed. Copy it if needed. </dd></dl>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">msg</td><td>the pointer to the <aclass="el"href="group__types_group.html#gadcab54026c4ed78f344ce03ce31bb61a"title="A structure holding a subject, optional reply and payload.">natsMsg</a> object. </td></tr>
<p>Returns the reply, possibly <code>NULL</code>.</p>
<dlclass="section warning"><dt>Warning</dt><dd>The string belongs to the message and must not be freed. Copy it if needed.</dd></dl>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">msg</td><td>the pointer to the <aclass="el"href="group__types_group.html#gadcab54026c4ed78f344ce03ce31bb61a"title="A structure holding a subject, optional reply and payload.">natsMsg</a> object. </td></tr>
<p>Returns the message payload, possibly <code>NULL</code>.</p>
<p>Note that although the data sent and received from the server is not <code>NULL</code> terminated, the NATS C Client does add a <code>NULL</code> byte to the received payload. If you expect the received data to be a "string", then this conveniently allows you to call <aclass="el"href="group__msg_group.html#ga523364451fd92534e754054266196e59"title="Returns the message payload.">natsMsg_GetData()</a> without having to copy the returned data to a buffer to add the <code>NULL</code> byte at the end.</p>
<dlclass="section warning"><dt>Warning</dt><dd>The string belongs to the message and must not be freed. Copy it if needed.</dd></dl>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">msg</td><td>the pointer to the <aclass="el"href="group__types_group.html#gadcab54026c4ed78f344ce03ce31bb61a"title="A structure holding a subject, optional reply and payload.">natsMsg</a> object. </td></tr>
<p>Returns the message's payload length, possibly 0.</p>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">msg</td><td>the pointer to the <aclass="el"href="group__types_group.html#gadcab54026c4ed78f344ce03ce31bb61a"title="A structure holding a subject, optional reply and payload.">natsMsg</a> object. </td></tr>
<p>It will replace any existing value associated with <code>key</code>.</p>
<dlclass="section warning"><dt>Warning</dt><dd>Prior to v3.0.0, the <code>key</code> was stored in its canonical form, this is no longer the case. Header keys are now case sensitive.</dd>
<dd>
Headers are not thread-safe, that is, you must not set/add/get values or delete keys for the same message from different threads. The internal structure of <code>natsMsg</code> may possible be altered during this call.</dd></dl>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">msg</td><td>the pointer to the <aclass="el"href="group__types_group.html#gadcab54026c4ed78f344ce03ce31bb61a"title="A structure holding a subject, optional reply and payload.">natsMsg</a> object. </td></tr>
<tr><tdclass="paramname">key</td><td>the key under which the <code>value</code> will be stored. It can't ne <code>NULL</code> or empty. </td></tr>
<tr><tdclass="paramname">value</td><td>the string to store under the given <code>key</code>. The value can be <code>NULL</code> or empty string. </td></tr>
<p>It will append to any existing values associated with <code>key</code>.</p>
<dlclass="section warning"><dt>Warning</dt><dd>Prior to v3.0.0, the <code>key</code> was stored in its canonical form, this is no longer the case. Header keys are now case sensitive.</dd>
<dd>
Headers are not thread-safe, that is, you must not set/add/get values or delete keys for the same message from different threads. The internal structure of <code>natsMsg</code> may possible be altered during this call.</dd></dl>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">msg</td><td>the pointer to the <aclass="el"href="group__types_group.html#gadcab54026c4ed78f344ce03ce31bb61a"title="A structure holding a subject, optional reply and payload.">natsMsg</a> object. </td></tr>
<tr><tdclass="paramname">key</td><td>the key under which the <code>value</code> will be stored. It can't ne <code>NULL</code> or empty. </td></tr>
<tr><tdclass="paramname">value</td><td>the string to add to the values associated with the given <code>key</code>. The value can be <code>NULL</code> or empty string. </td></tr>
<p>If more than one entry for the <code>key</code> is available, the first is returned. The returned value is owned by the library and MUST not be freed or altered.</p>
<dlclass="section warning"><dt>Warning</dt><dd>Prior to v3.0.0, the <code>key</code> was stored in its canonical form, this is no longer the case. Header keys are now case sensitive.</dd>
<dd>
Headers are not thread-safe, that is, you must not set/add/get values or delete keys for the same message from different threads. The internal structure of <code>natsMsg</code> may possible be altered during this call.</dd></dl>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">msg</td><td>the pointer to the <aclass="el"href="group__types_group.html#gadcab54026c4ed78f344ce03ce31bb61a"title="A structure holding a subject, optional reply and payload.">natsMsg</a> object. </td></tr>
<tr><tdclass="paramname">key</td><td>the key for which the value is requested. </td></tr>
<tr><tdclass="paramname">value</td><td>the memory location where the library will store the pointer to the first value (if more than one is found) associated with the <code>key</code>. </td></tr>
</table>
</dd>
</dl>
<dlclass="section return"><dt>Returns</dt><dd>NATS_NOT_FOUND if <code>key</code> is not present in the headers. </dd></dl>
<p>The returned strings are own by the library and MUST not be freed or altered. However, the returned array <code>values</code> MUST be freed by the user.</p>
<divclass="line"><spanclass="keywordflow">if</span> (s == <aclass="code hl_enumvalue"href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80a9cee6c417868ecaa69f99ff4f6576990">NATS_OK</a>)</div>
<divclass="line">{</div>
<divclass="line"><spanclass="comment">// do something with the values</span></div>
<divclass="line"></div>
<divclass="line"><spanclass="comment">// then free the array of pointers.</span></div>
</div><!-- fragment --><dlclass="section warning"><dt>Warning</dt><dd>Prior to v3.0.0, the <code>key</code> was stored in its canonical form, this is no longer the case. Header keys are now case sensitive.</dd>
<dd>
Headers are not thread-safe, that is, you must not set/add/get values or delete keys for the same message from different threads. The internal structure of <code>natsMsg</code> may possible be altered during this call.</dd></dl>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">msg</td><td>the pointer to the <aclass="el"href="group__types_group.html#gadcab54026c4ed78f344ce03ce31bb61a"title="A structure holding a subject, optional reply and payload.">natsMsg</a> object. </td></tr>
<tr><tdclass="paramname">key</td><td>the key for which the values are requested. </td></tr>
<tr><tdclass="paramname">values</td><td>the memory location where the library will store the pointer to the array of values. </td></tr>
<tr><tdclass="paramname">count</td><td>the memory location where the library will store the number of values returned. </td></tr>
</table>
</dd>
</dl>
<dlclass="section return"><dt>Returns</dt><dd>NATS_NOT_FOUND if <code>key</code> is not present in the headers. </dd></dl>
<p>The returned strings are own by the library and MUST not be freed or altered. However, the returned array <code>keys</code> MUST be freed by the user.</p>
<divclass="line"><spanclass="keywordflow">if</span> (s == <aclass="code hl_enumvalue"href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80a9cee6c417868ecaa69f99ff4f6576990">NATS_OK</a>)</div>
<divclass="line">{</div>
<divclass="line"><spanclass="comment">// do something with the keys</span></div>
<divclass="line"></div>
<divclass="line"><spanclass="comment">// then free the array of pointers.</span></div>
<divclass="ttc"id="agroup__msg_group_html_ga6ee8a007111ada293dd24ff0bab02491"><divclass="ttname"><ahref="group__msg_group.html#ga6ee8a007111ada293dd24ff0bab02491">natsMsgHeader_Keys</a></div><divclass="ttdeci">NATS_EXTERN natsStatus natsMsgHeader_Keys(natsMsg *msg, const char ***keys, int *count)</div><divclass="ttdoc">Get all header keys.</div></div>
</div><!-- fragment --><dlclass="section warning"><dt>Warning</dt><dd>Headers are not thread-safe, that is, you must not set/add/get values or delete keys for the same message from different threads. The internal structure of <code>natsMsg</code> may possible be altered during this call.</dd></dl>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">msg</td><td>the pointer to the <aclass="el"href="group__types_group.html#gadcab54026c4ed78f344ce03ce31bb61a"title="A structure holding a subject, optional reply and payload.">natsMsg</a> object. </td></tr>
<tr><tdclass="paramname">keys</td><td>the memory location where the library will store the pointer to the array of keys. </td></tr>
<tr><tdclass="paramname">count</td><td>the memory location where the library will store the number of keys returned. </td></tr>
</table>
</dd>
</dl>
<dlclass="section return"><dt>Returns</dt><dd>NATS_NOT_FOUND if no key is present. </dd></dl>
<dlclass="section warning"><dt>Warning</dt><dd>Prior to v3.0.0, the <code>key</code> was stored in its canonical form, this is no longer the case. Header keys are now case sensitive.</dd>
<dd>
Headers are not thread-safe, that is, you must not set/add/get values or delete keys for the same message from different threads. The internal structure of <code>natsMsg</code> may possible be altered during this call.</dd></dl>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">msg</td><td>the pointer to the <aclass="el"href="group__types_group.html#gadcab54026c4ed78f344ce03ce31bb61a"title="A structure holding a subject, optional reply and payload.">natsMsg</a> object. </td></tr>
<tr><tdclass="paramname">key</td><td>the key to delete from the headers map. </td></tr>
</table>
</dd>
</dl>
<dlclass="section return"><dt>Returns</dt><dd>NATS_NOT_FOUND if <code>key</code> is not present in the headers. </dd></dl>
<p>Starting with the NATS Server v2.2.0+ and the C client v2.2.0+ releases, which introduced support for message headers and the "no responders" feature, if a request is received by the server and there are no subscriptions on the request's subject, the server sends a message with no payload but with a header "Status" with value "503".</p>
<p>The call <aclass="el"href="group__conn_pub_group.html#gaf4b4a022f9c21fc269b87c000330c5a7"title="Sends a request and waits for a reply.">natsConnection_Request()</a> and its variants intercept this special message and instead of returning it to the user, they return <aclass="el"href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80aab97324e40ccfe1360080c651c330e62"title="No responders were running when the server received the request.">NATS_NO_RESPONDERS</a>.</p>
<p>If a synchronous subscription is created on a subject used as a reply subject to a <aclass="el"href="group__conn_pub_group.html#gaaaa3d75ffec2dcdc6bf905cdb1eee59e"title="Publishes data on a subject expecting replies on the given reply.">natsConnection_PublishRequest</a> call (and its variants), <aclass="el"href="group__sub_group.html#ga6538a5d78dfb0f16514b94c8e74c11af"title="Returns the next available message.">natsSubscription_NextMsg</a> also detects this message and returns <aclass="el"href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80aab97324e40ccfe1360080c651c330e62"title="No responders were running when the server received the request.">NATS_NO_RESPONDERS</a> (but it was not from release v2.2.0 to v2.4.1).</p>
<p>For asynchronous subscriptions, the user may want to know that the request failed because there are no responders. For that reason, the message is passed to the message callback, and this function can be used to detect that this is a "no responders" message from the server and act accordingly.</p>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">msg</td><td>the pointer to the <aclass="el"href="group__types_group.html#gadcab54026c4ed78f344ce03ce31bb61a"title="A structure holding a subject, optional reply and payload.">natsMsg</a> object. </td></tr>
</table>
</dd>
</dl>
<dlclass="section return"><dt>Returns</dt><dd><code>true</code> if this message is a "no responders" message from the server, that is, has no payload and the "Status" header with "503" as the value. </dd></dl>
<tr><tdclass="paramname">msg</td><td>the pointer to the <aclass="el"href="group__types_group.html#gadcab54026c4ed78f344ce03ce31bb61a"title="A structure holding a subject, optional reply and payload.">natsMsg</a> object to destroy. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
</div><!-- contents -->
</div><!-- doc-content -->
<!-- HTML footer for doxygen 1.8.10-->
<!-- start footer part -->
<divid="nav-path"class="navpath"><!-- id is needed for treeview function! -->
<ul>
<liclass="footer">NATS.IO Supported By Synadia Communications Inc.