factotum/nats.zig
1
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
nats.zig/deps/nats.c/doc/html/group__js_sub_group.html
torque 41fbdf886b
git subrepo pull --branch=v3.7.0 deps/nats.c 
subrepo:
  subdir:   "deps/nats.c"
  merged:   "5d057f6"
upstream:
  origin:   "https://github.com/nats-io/nats.c.git"
  branch:   "v3.7.0"
  commit:   "5d057f6"
git-subrepo:
  version:  "0.4.6"
  commit:   "affc4c01a"
2023-10-14 13:22:13 -07:00

616 lines
43 KiB
HTML
Raw Blame History

<!-- HTML header for doxygen 1.8.10-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.8"/>
<title>NATS C Client with JetStream and Streaming support: Subscribing</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="customdoxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;" >
<div id="projectname">NATS C Client with JetStream and Streaming support
&#160;<span id="projectnumber">3.7.0</span>
</div>
<div id="projectbrief">The nats.io C Client, Supported by Synadia Communications Inc.</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.8 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(document).ready(function(){initNavTree('group__js_sub_group.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>
<div class="header">
<div class="summary">
<a href="#func-members">Functions</a> </div>
<div class="headertitle"><div class="title">Subscribing<div class="ingroups"><a class="el" href="group__func_group.html">Functions</a> &raquo; <a class="el" href="group__js_group.html">JetStream</a></div></div></div>
</div><!--header-->
<div class="contents">
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="func-members" name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:ga472adb949d1af9d8f07bda99f5d7f3f8" id="r_ga472adb949d1af9d8f07bda99f5d7f3f8"><td class="memItemLeft" align="right" valign="top"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> <a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__js_sub_group.html#ga472adb949d1af9d8f07bda99f5d7f3f8">jsSubOptions_Init</a> (<a class="el" href="structjs_sub_options.html">jsSubOptions</a> *opts)</td></tr>
<tr class="memdesc:ga472adb949d1af9d8f07bda99f5d7f3f8"><td class="mdescLeft">&#160;</td><td class="mdescRight">Initializes a subscribe options structure. <br /></td></tr>
<tr class="separator:ga472adb949d1af9d8f07bda99f5d7f3f8"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gaa686c6efd84ef963de1925108e896515" id="r_gaa686c6efd84ef963de1925108e896515"><td class="memItemLeft" align="right" valign="top"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> <a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__js_sub_group.html#gaa686c6efd84ef963de1925108e896515">js_Subscribe</a> (<a class="el" href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8">natsSubscription</a> **sub, <a class="el" href="group__types_group.html#gaaf12cdd24c6cc23a57c20466c92ff8c1">jsCtx</a> *js, const char *subject, <a class="el" href="group__callbacks_group.html#gad1a5ac566893e13dc8c81ac0e9c87afe">natsMsgHandler</a> cb, void *cbClosure, <a class="el" href="structjs_options.html">jsOptions</a> *opts, <a class="el" href="structjs_sub_options.html">jsSubOptions</a> *subOpts, <a class="el" href="status_8h.html#a10731415ffcd3e2330df10c4d5fd3d70">jsErrCode</a> *errCode)</td></tr>
<tr class="memdesc:gaa686c6efd84ef963de1925108e896515"><td class="mdescLeft">&#160;</td><td class="mdescRight">Create an asynchronous subscription. <br /></td></tr>
<tr class="separator:gaa686c6efd84ef963de1925108e896515"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gabacb010031e535f9fb6e2167337e8adf" id="r_gabacb010031e535f9fb6e2167337e8adf"><td class="memItemLeft" align="right" valign="top"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> <a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__js_sub_group.html#gabacb010031e535f9fb6e2167337e8adf">js_SubscribeSync</a> (<a class="el" href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8">natsSubscription</a> **sub, <a class="el" href="group__types_group.html#gaaf12cdd24c6cc23a57c20466c92ff8c1">jsCtx</a> *js, const char *subject, <a class="el" href="structjs_options.html">jsOptions</a> *opts, <a class="el" href="structjs_sub_options.html">jsSubOptions</a> *subOpts, <a class="el" href="status_8h.html#a10731415ffcd3e2330df10c4d5fd3d70">jsErrCode</a> *errCode)</td></tr>
<tr class="memdesc:gabacb010031e535f9fb6e2167337e8adf"><td class="mdescLeft">&#160;</td><td class="mdescRight">Create a synchronous subscription. <br /></td></tr>
<tr class="separator:gabacb010031e535f9fb6e2167337e8adf"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gaaeaddb73857aa4eb4901eec945ed27cd" id="r_gaaeaddb73857aa4eb4901eec945ed27cd"><td class="memItemLeft" align="right" valign="top"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> <a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__js_sub_group.html#gaaeaddb73857aa4eb4901eec945ed27cd">js_PullSubscribe</a> (<a class="el" href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8">natsSubscription</a> **sub, <a class="el" href="group__types_group.html#gaaf12cdd24c6cc23a57c20466c92ff8c1">jsCtx</a> *js, const char *subject, const char *durable, <a class="el" href="structjs_options.html">jsOptions</a> *opts, <a class="el" href="structjs_sub_options.html">jsSubOptions</a> *subOpts, <a class="el" href="status_8h.html#a10731415ffcd3e2330df10c4d5fd3d70">jsErrCode</a> *errCode)</td></tr>
<tr class="memdesc:gaaeaddb73857aa4eb4901eec945ed27cd"><td class="mdescLeft">&#160;</td><td class="mdescRight">Create a pull subscriber. <br /></td></tr>
<tr class="separator:gaaeaddb73857aa4eb4901eec945ed27cd"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gafc5e0d2269bd23b4d5fb7f3b05278e50" id="r_gafc5e0d2269bd23b4d5fb7f3b05278e50"><td class="memItemLeft" align="right" valign="top"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> <a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__js_sub_group.html#gafc5e0d2269bd23b4d5fb7f3b05278e50">natsSubscription_Fetch</a> (<a class="el" href="structnats_msg_list.html">natsMsgList</a> *list, <a class="el" href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8">natsSubscription</a> *sub, int batch, int64_t timeout, <a class="el" href="status_8h.html#a10731415ffcd3e2330df10c4d5fd3d70">jsErrCode</a> *errCode)</td></tr>
<tr class="memdesc:gafc5e0d2269bd23b4d5fb7f3b05278e50"><td class="mdescLeft">&#160;</td><td class="mdescRight">Fetches messages for a pull subscription. <br /></td></tr>
<tr class="separator:gafc5e0d2269bd23b4d5fb7f3b05278e50"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga1c3a62de8cd4855ae61ea4f67417a43b" id="r_ga1c3a62de8cd4855ae61ea4f67417a43b"><td class="memItemLeft" align="right" valign="top"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> <a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__js_sub_group.html#ga1c3a62de8cd4855ae61ea4f67417a43b">jsFetchRequest_Init</a> (<a class="el" href="structjs_fetch_request.html">jsFetchRequest</a> *request)</td></tr>
<tr class="memdesc:ga1c3a62de8cd4855ae61ea4f67417a43b"><td class="mdescLeft">&#160;</td><td class="mdescRight">Initializes a fetch request options structure. <br /></td></tr>
<tr class="separator:ga1c3a62de8cd4855ae61ea4f67417a43b"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga676292505e7fde8688cfd886b79a10ed" id="r_ga676292505e7fde8688cfd886b79a10ed"><td class="memItemLeft" align="right" valign="top"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> <a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__js_sub_group.html#ga676292505e7fde8688cfd886b79a10ed">natsSubscription_FetchRequest</a> (<a class="el" href="structnats_msg_list.html">natsMsgList</a> *list, <a class="el" href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8">natsSubscription</a> *sub, <a class="el" href="structjs_fetch_request.html">jsFetchRequest</a> *request)</td></tr>
<tr class="memdesc:ga676292505e7fde8688cfd886b79a10ed"><td class="mdescLeft">&#160;</td><td class="mdescRight">Fetches messages for a pull subscription with a complete request configuration. <br /></td></tr>
<tr class="separator:ga676292505e7fde8688cfd886b79a10ed"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gaae716a1431db065744c079b71a9f4c2e" id="r_gaae716a1431db065744c079b71a9f4c2e"><td class="memItemLeft" align="right" valign="top"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> <a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__js_sub_group.html#gaae716a1431db065744c079b71a9f4c2e">natsSubscription_GetConsumerInfo</a> (<a class="el" href="structjs_consumer_info.html">jsConsumerInfo</a> **ci, <a class="el" href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8">natsSubscription</a> *sub, <a class="el" href="structjs_options.html">jsOptions</a> *opts, <a class="el" href="status_8h.html#a10731415ffcd3e2330df10c4d5fd3d70">jsErrCode</a> *errCode)</td></tr>
<tr class="memdesc:gaae716a1431db065744c079b71a9f4c2e"><td class="mdescLeft">&#160;</td><td class="mdescRight">Returns the <a class="el" href="structjs_consumer_info.html">jsConsumerInfo</a> associated with this subscription. <br /></td></tr>
<tr class="separator:gaae716a1431db065744c079b71a9f4c2e"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga0daed9f0d2d00cb14314ecc180a6fa84" id="r_ga0daed9f0d2d00cb14314ecc180a6fa84"><td class="memItemLeft" align="right" valign="top"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> <a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__js_sub_group.html#ga0daed9f0d2d00cb14314ecc180a6fa84">natsSubscription_GetSequenceMismatch</a> (<a class="el" href="structjs_consumer_sequence_mismatch.html">jsConsumerSequenceMismatch</a> *csm, <a class="el" href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8">natsSubscription</a> *sub)</td></tr>
<tr class="memdesc:ga0daed9f0d2d00cb14314ecc180a6fa84"><td class="mdescLeft">&#160;</td><td class="mdescRight">Returns the consumer sequence mismatch information. <br /></td></tr>
<tr class="separator:ga0daed9f0d2d00cb14314ecc180a6fa84"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<p>Subscribing functions </p>
<h2 class="groupheader">Function Documentation</h2>
<a id="ga472adb949d1af9d8f07bda99f5d7f3f8" name="ga472adb949d1af9d8f07bda99f5d7f3f8"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga472adb949d1af9d8f07bda99f5d7f3f8">&#9670;&#160;</a></span>jsSubOptions_Init()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> <a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a> jsSubOptions_Init </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structjs_sub_options.html">jsSubOptions</a> *&#160;</td>
<td class="paramname"><em>opts</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Use this before setting specific subscribe options and passing this configuration to the JetStream subscribe APIs.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">opts</td><td>the pointer to the <a class="el" href="structjs_sub_options.html">jsSubOptions</a> to initialize. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="gaa686c6efd84ef963de1925108e896515" name="gaa686c6efd84ef963de1925108e896515"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gaa686c6efd84ef963de1925108e896515">&#9670;&#160;</a></span>js_Subscribe()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> <a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a> js_Subscribe </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8">natsSubscription</a> **&#160;</td>
<td class="paramname"><em>sub</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group__types_group.html#gaaf12cdd24c6cc23a57c20466c92ff8c1">jsCtx</a> *&#160;</td>
<td class="paramname"><em>js</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char *&#160;</td>
<td class="paramname"><em>subject</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group__callbacks_group.html#gad1a5ac566893e13dc8c81ac0e9c87afe">natsMsgHandler</a>&#160;</td>
<td class="paramname"><em>cb</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void *&#160;</td>
<td class="paramname"><em>cbClosure</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structjs_options.html">jsOptions</a> *&#160;</td>
<td class="paramname"><em>opts</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structjs_sub_options.html">jsSubOptions</a> *&#160;</td>
<td class="paramname"><em>subOpts</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="status_8h.html#a10731415ffcd3e2330df10c4d5fd3d70">jsErrCode</a> *&#160;</td>
<td class="paramname"><em>errCode</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Typically the user or administrator will have created a JetStream consumer and this call will reference the stream/consumer to bind to with the use of <a class="el" href="structjs_sub_options.html">jsSubOptions</a>'s <code>Stream</code> and <code>Consumer</code>.</p>
<p>Without the stream information, the library will use the provided <code>subject</code> to try figure out which stream this subscription is for.</p>
<p>If a <code>Durable</code> is specified (with <a class="el" href="structjs_sub_options.html">jsSubOptions</a>' <code>Config.Durable</code>), the subscription will be durable. However, note the behavior described below regarding JetStream consumers created by this call.</p>
<p>If no <code>Durable</code> is specified, the subscription will be ephemeral and removed by the server either after calling <a class="el" href="group__sub_group.html#gaee87f8be0e6c2a4693ba2cea070583ba" title="Unsubscribes.">natsSubscription_Unsubscribe</a> or after the subscription is destroyed and the <code>InactivityThreshold</code> has elapsed.</p>
<dl class="section note"><dt>Note</dt><dd>If a JetStream consumer does not exist and this call creates it, it will be removed in the server once the user calls <a class="el" href="group__sub_group.html#gaee87f8be0e6c2a4693ba2cea070583ba" title="Unsubscribes.">natsSubscription_Unsubscribe</a> or <a class="el" href="group__sub_group.html#ga26c9736289d326fb7d6df7e2a0df72ab" title="Drains the subscription with a default timeout.">natsSubscription_Drain</a>, even if this is a <code>Durable</code> subscription. If the subscription should be maintained, it should be explicitly created using <a class="el" href="group__js_assets_group.html#gaf2efb63db150e782d9007090b49d4115" title="Adds a JetStream consumer.">js_AddConsumer</a> and then bound to with the use of <a class="el" href="structjs_sub_options.html">jsSubOptions</a>' <code>Stream</code> and <code>Consumer</code>.</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>Prior to release v3.4.0, calling <a class="el" href="group__sub_group.html#ga50a95dd96e9b714201679a015d62832f" title="Destroys the subscription.">natsSubscription_Destroy</a> would delete the JetStream consumer if it was created by this call. The original intent was that it would be deleted only with explicit calls to unsubscribe or drain. Therefore, starting v3.4.0, if the user calls only <a class="el" href="group__sub_group.html#ga50a95dd96e9b714201679a015d62832f" title="Destroys the subscription.">natsSubscription_Destroy</a> (to free memory), the JetStream consumer will no longer be deleted. The user would have to explicitly call <a class="el" href="group__sub_group.html#gaee87f8be0e6c2a4693ba2cea070583ba" title="Unsubscribes.">natsSubscription_Unsubscribe</a> or <a class="el" href="group__js_assets_group.html#ga52fbc61759b11494db91f348a733c490" title="Deletes a consumer.">js_DeleteConsumer</a>.</dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">sub</td><td>the location where to store the pointer to the newly created <a class="el" href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8" title="Interest on a given subject.">natsSubscription</a> object. </td></tr>
<tr><td class="paramname">js</td><td>the pointer to the <a class="el" href="group__types_group.html#gaaf12cdd24c6cc23a57c20466c92ff8c1">jsCtx</a> object. </td></tr>
<tr><td class="paramname">subject</td><td>the subject this subscription is created for. </td></tr>
<tr><td class="paramname">cb</td><td>the <a class="el" href="group__callbacks_group.html#gad1a5ac566893e13dc8c81ac0e9c87afe" title="Callback used to deliver messages to the application.">natsMsgHandler</a> callback. </td></tr>
<tr><td class="paramname">cbClosure</td><td>a pointer to an user defined object (can be <code>NULL</code>). See the <a class="el" href="group__callbacks_group.html#gad1a5ac566893e13dc8c81ac0e9c87afe" title="Callback used to deliver messages to the application.">natsMsgHandler</a> prototype. </td></tr>
<tr><td class="paramname">opts</td><td>the pointer to the <a class="el" href="structjs_options.html">jsOptions</a> object, possibly <code>NULL</code>. </td></tr>
<tr><td class="paramname">subOpts</td><td>the subscribe options, possibly <code>NULL</code>. </td></tr>
<tr><td class="paramname">errCode</td><td>the location where to store the JetStream specific error code, or <code>NULL</code> if not needed. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="gabacb010031e535f9fb6e2167337e8adf" name="gabacb010031e535f9fb6e2167337e8adf"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gabacb010031e535f9fb6e2167337e8adf">&#9670;&#160;</a></span>js_SubscribeSync()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> <a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a> js_SubscribeSync </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8">natsSubscription</a> **&#160;</td>
<td class="paramname"><em>sub</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group__types_group.html#gaaf12cdd24c6cc23a57c20466c92ff8c1">jsCtx</a> *&#160;</td>
<td class="paramname"><em>js</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char *&#160;</td>
<td class="paramname"><em>subject</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structjs_options.html">jsOptions</a> *&#160;</td>
<td class="paramname"><em>opts</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structjs_sub_options.html">jsSubOptions</a> *&#160;</td>
<td class="paramname"><em>subOpts</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="status_8h.html#a10731415ffcd3e2330df10c4d5fd3d70">jsErrCode</a> *&#160;</td>
<td class="paramname"><em>errCode</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>See important notes in <a class="el" href="group__js_sub_group.html#gaa686c6efd84ef963de1925108e896515" title="Create an asynchronous subscription.">js_Subscribe</a>.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">sub</td><td>the location where to store the pointer to the newly created <a class="el" href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8" title="Interest on a given subject.">natsSubscription</a> object. </td></tr>
<tr><td class="paramname">js</td><td>the pointer to the <a class="el" href="group__types_group.html#gaaf12cdd24c6cc23a57c20466c92ff8c1">jsCtx</a> object. </td></tr>
<tr><td class="paramname">subject</td><td>the subject this subscription is created for. the <a class="el" href="group__callbacks_group.html#gad1a5ac566893e13dc8c81ac0e9c87afe" title="Callback used to deliver messages to the application.">natsMsgHandler</a> prototype. </td></tr>
<tr><td class="paramname">opts</td><td>the pointer to the <a class="el" href="structjs_options.html">jsOptions</a> object, possibly <code>NULL</code>. </td></tr>
<tr><td class="paramname">subOpts</td><td>the subscribe options, possibly <code>NULL</code>. </td></tr>
<tr><td class="paramname">errCode</td><td>the location where to store the JetStream specific error code, or <code>NULL</code> if not needed. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="gaaeaddb73857aa4eb4901eec945ed27cd" name="gaaeaddb73857aa4eb4901eec945ed27cd"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gaaeaddb73857aa4eb4901eec945ed27cd">&#9670;&#160;</a></span>js_PullSubscribe()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> <a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a> js_PullSubscribe </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8">natsSubscription</a> **&#160;</td>
<td class="paramname"><em>sub</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group__types_group.html#gaaf12cdd24c6cc23a57c20466c92ff8c1">jsCtx</a> *&#160;</td>
<td class="paramname"><em>js</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char *&#160;</td>
<td class="paramname"><em>subject</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char *&#160;</td>
<td class="paramname"><em>durable</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structjs_options.html">jsOptions</a> *&#160;</td>
<td class="paramname"><em>opts</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structjs_sub_options.html">jsSubOptions</a> *&#160;</td>
<td class="paramname"><em>subOpts</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="status_8h.html#a10731415ffcd3e2330df10c4d5fd3d70">jsErrCode</a> *&#160;</td>
<td class="paramname"><em>errCode</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>A pull based consumer is a type of consumer that does not have a delivery subject, that is the library has to request for the messages to be delivered as needed from the server.</p>
<dl class="section note"><dt>Note</dt><dd>If no durable name is provided, the pull subscription will create an ephemeral JetStream consumer. The requirement for a durable name is lifted in NATS C client v3.4.0+ and NATS Server v2.7.0+. </dd>
<dd>
If a durable name is specified, it cannot contain the character ".".</dd></dl>
<p>See important notes in <a class="el" href="group__js_sub_group.html#gaa686c6efd84ef963de1925108e896515" title="Create an asynchronous subscription.">js_Subscribe</a>.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">sub</td><td>the location where to store the pointer to the newly created <a class="el" href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8" title="Interest on a given subject.">natsSubscription</a> object. </td></tr>
<tr><td class="paramname">js</td><td>the pointer to the <a class="el" href="group__types_group.html#gaaf12cdd24c6cc23a57c20466c92ff8c1">jsCtx</a> object. </td></tr>
<tr><td class="paramname">subject</td><td>the subject this subscription is created for. </td></tr>
<tr><td class="paramname">durable</td><td>the optional durable name. </td></tr>
<tr><td class="paramname">opts</td><td>the pointer to the <a class="el" href="structjs_options.html">jsOptions</a> object, possibly <code>NULL</code>. </td></tr>
<tr><td class="paramname">subOpts</td><td>the subscribe options, possibly <code>NULL</code>. </td></tr>
<tr><td class="paramname">errCode</td><td>the location where to store the JetStream specific error code, or <code>NULL</code> if not needed. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="gafc5e0d2269bd23b4d5fb7f3b05278e50" name="gafc5e0d2269bd23b4d5fb7f3b05278e50"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gafc5e0d2269bd23b4d5fb7f3b05278e50">&#9670;&#160;</a></span>natsSubscription_Fetch()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> <a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a> natsSubscription_Fetch </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structnats_msg_list.html">natsMsgList</a> *&#160;</td>
<td class="paramname"><em>list</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8">natsSubscription</a> *&#160;</td>
<td class="paramname"><em>sub</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int&#160;</td>
<td class="paramname"><em>batch</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int64_t&#160;</td>
<td class="paramname"><em>timeout</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="status_8h.html#a10731415ffcd3e2330df10c4d5fd3d70">jsErrCode</a> *&#160;</td>
<td class="paramname"><em>errCode</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Fetches up to <code>batch</code> messages from the server, waiting up to <code>timeout</code> milliseconds. No more thant <code>batch</code> messages will be returned, however, it can be less.</p>
<p>For <code>batch</code> greater than <code>1</code>, this call will not necessarily wait up <code>timeout</code> milliseconds if some messages were collected and the library receives a notification that no more messages are available at this time.<br />
It means that calling <code>natsSubscription_Fetch(&amp;list, sub, 10, 5000)</code> may return after less than 5 seconds with only 3 messages.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">list</td><td>the location to a <a class="el" href="structnats_msg_list.html" title="A list of NATS messages.">natsMsgList</a> that will be filled by the result of this call. </td></tr>
<tr><td class="paramname">sub</td><td>the pointer to the <a class="el" href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8" title="Interest on a given subject.">natsSubscription</a> object. </td></tr>
<tr><td class="paramname">batch</td><td>the batch size, that is, the maximum number of messages to return. </td></tr>
<tr><td class="paramname">timeout</td><td>the timeout (required) expressed in number of milliseconds. </td></tr>
<tr><td class="paramname">errCode</td><td>the location where to store the JetStream specific error code, or <code>NULL</code> if not needed. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="ga1c3a62de8cd4855ae61ea4f67417a43b" name="ga1c3a62de8cd4855ae61ea4f67417a43b"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga1c3a62de8cd4855ae61ea4f67417a43b">&#9670;&#160;</a></span>jsFetchRequest_Init()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> <a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a> jsFetchRequest_Init </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structjs_fetch_request.html">jsFetchRequest</a> *&#160;</td>
<td class="paramname"><em>request</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Use this before setting specific fetch options and passing it to <a class="el" href="group__js_sub_group.html#ga676292505e7fde8688cfd886b79a10ed" title="Fetches messages for a pull subscription with a complete request configuration.">natsSubscription_FetchRequest</a>.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">request</td><td>the pointer to the <a class="el" href="structjs_fetch_request.html">jsFetchRequest</a> object. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="ga676292505e7fde8688cfd886b79a10ed" name="ga676292505e7fde8688cfd886b79a10ed"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga676292505e7fde8688cfd886b79a10ed">&#9670;&#160;</a></span>natsSubscription_FetchRequest()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> <a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a> natsSubscription_FetchRequest </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structnats_msg_list.html">natsMsgList</a> *&#160;</td>
<td class="paramname"><em>list</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8">natsSubscription</a> *&#160;</td>
<td class="paramname"><em>sub</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structjs_fetch_request.html">jsFetchRequest</a> *&#160;</td>
<td class="paramname"><em>request</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Similar to <a class="el" href="group__js_sub_group.html#gafc5e0d2269bd23b4d5fb7f3b05278e50" title="Fetches messages for a pull subscription.">natsSubscription_Fetch</a> but a full <a class="el" href="structjs_fetch_request.html">jsFetchRequest</a> configuration is provided for maximum control.</p>
<p>Initialize the <a class="el" href="structjs_fetch_request.html">jsFetchRequest</a> structure using <a class="el" href="group__js_sub_group.html#ga1c3a62de8cd4855ae61ea4f67417a43b" title="Initializes a fetch request options structure.">jsFetchRequest_Init</a> and then set the parameters desired, then invoke this function.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">list</td><td>the location to a <a class="el" href="structnats_msg_list.html" title="A list of NATS messages.">natsMsgList</a> that will be filled by the result of this call. </td></tr>
<tr><td class="paramname">sub</td><td>the pointer to the <a class="el" href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8" title="Interest on a given subject.">natsSubscription</a> object. </td></tr>
<tr><td class="paramname">request</td><td>the pointer to a <a class="el" href="structjs_fetch_request.html">jsFetchRequest</a> configuration. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="gaae716a1431db065744c079b71a9f4c2e" name="gaae716a1431db065744c079b71a9f4c2e"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gaae716a1431db065744c079b71a9f4c2e">&#9670;&#160;</a></span>natsSubscription_GetConsumerInfo()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> <a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a> natsSubscription_GetConsumerInfo </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structjs_consumer_info.html">jsConsumerInfo</a> **&#160;</td>
<td class="paramname"><em>ci</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8">natsSubscription</a> *&#160;</td>
<td class="paramname"><em>sub</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structjs_options.html">jsOptions</a> *&#160;</td>
<td class="paramname"><em>opts</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="status_8h.html#a10731415ffcd3e2330df10c4d5fd3d70">jsErrCode</a> *&#160;</td>
<td class="paramname"><em>errCode</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Returns the <a class="el" href="structjs_consumer_info.html">jsConsumerInfo</a> associated with this subscription.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">ci</td><td>the location where to store the pointer to the new <a class="el" href="structjs_consumer_info.html">jsConsumerInfo</a> object. </td></tr>
<tr><td class="paramname">sub</td><td>the pointer to the <a class="el" href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8" title="Interest on a given subject.">natsSubscription</a> object. </td></tr>
<tr><td class="paramname">opts</td><td>the pointer to the <a class="el" href="structjs_options.html">jsOptions</a> object, possibly <code>NULL</code>. </td></tr>
<tr><td class="paramname">errCode</td><td>the location where to store the JetStream specific error code, or <code>NULL</code> if not needed. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="ga0daed9f0d2d00cb14314ecc180a6fa84" name="ga0daed9f0d2d00cb14314ecc180a6fa84"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga0daed9f0d2d00cb14314ecc180a6fa84">&#9670;&#160;</a></span>natsSubscription_GetSequenceMismatch()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="nats_8h.html#a3bc1b3fe7f64083e60c7c3b93f205bad">NATS_EXTERN</a> <a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80">natsStatus</a> natsSubscription_GetSequenceMismatch </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structjs_consumer_sequence_mismatch.html">jsConsumerSequenceMismatch</a> *&#160;</td>
<td class="paramname"><em>csm</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8">natsSubscription</a> *&#160;</td>
<td class="paramname"><em>sub</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>If <code>Heartbeat</code> is configured in <a class="el" href="structjs_consumer_config.html">jsConsumerConfig</a> object (or configured in an existing JetStream consumer), the server sends heartbeats to the client at the given interval.</p>
<p>Those heartbeats contains information that allow the application to detect a mismatch between the server and client's view of the state of the consumer.</p>
<p>If the library detects a sequence mismatch, the behavior is different depending on the type of subscription:</p>
<ul>
<li>For asynchronous subscriptions: the error <a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80a22fa4802a34bac497f23e269a20a52f2" title="For JetStream subscriptions, it means that a consumer sequence mismatch was discovered.">NATS_MISMATCH</a> is published to the error handler (see <a class="el" href="group__opts_group.html#ga127ec7a8196b453947a7fa9a64096cbd" title="Sets the error handler for asynchronous events.">natsOptions_SetErrorHandler</a>).</li>
<li>For synchronous subscriptions: the next call to <a class="el" href="group__sub_group.html#ga6538a5d78dfb0f16514b94c8e74c11af" title="Returns the next available message.">natsSubscription_NextMsg()</a> will return the error <a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80a22fa4802a34bac497f23e269a20a52f2" title="For JetStream subscriptions, it means that a consumer sequence mismatch was discovered.">NATS_MISMATCH</a> (but will succeed afterwards).</li>
</ul>
<p>In both cases, the user should check what the mismatch is using this function and possibly recreate the consumer based on the provided information.</p>
<dl class="section note"><dt>Note</dt><dd>For a valid JetStream subscription, this function will return <a class="el" href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80ad0229a12b17d3d12a28efed6213720d8">NATS_NOT_FOUND</a> if no consumer sequence mismatch has been detected.</dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="structjs_consumer_sequence_mismatch.html">jsConsumerSequenceMismatch</a></dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">csm</td><td>the pointer location where to copy the consumer sequence mismatch information. </td></tr>
<tr><td class="paramname">sub</td><td>the pointer to the <a class="el" href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8" title="Interest on a given subject.">natsSubscription</a> object. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
</div><!-- contents -->
</div><!-- doc-content -->
<!-- HTML footer for doxygen 1.8.10-->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">NATS.IO Supported By Synadia Communications Inc.
<a href="http://www.nats.io">
</a></li>
</ul>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink