<trclass="memdesc:gaa686c6efd84ef963de1925108e896515"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Create an asynchronous subscription. <br/></td></tr>
<trclass="memdesc:gabacb010031e535f9fb6e2167337e8adf"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Create a synchronous subscription. <br/></td></tr>
<trclass="memdesc:gafc5e0d2269bd23b4d5fb7f3b05278e50"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Fetches messages for a pull subscription. <br/></td></tr>
<trclass="memdesc:ga676292505e7fde8688cfd886b79a10ed"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Fetches messages for a pull subscription with a complete request configuration. <br/></td></tr>
<trclass="memdesc:gaae716a1431db065744c079b71a9f4c2e"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Returns the <aclass="el"href="structjs_consumer_info.html">jsConsumerInfo</a> associated with this subscription. <br/></td></tr>
<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 <aclass="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 <aclass="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 <aclass="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>
<dlclass="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 <aclass="el"href="group__sub_group.html#gaee87f8be0e6c2a4693ba2cea070583ba"title="Unsubscribes.">natsSubscription_Unsubscribe</a> or <aclass="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 <aclass="el"href="group__js_assets_group.html#gaf2efb63db150e782d9007090b49d4115"title="Adds a JetStream consumer.">js_AddConsumer</a> and then bound to with the use of <aclass="el"href="structjs_sub_options.html">jsSubOptions</a>' <code>Stream</code> and <code>Consumer</code>.</dd></dl>
<dlclass="section warning"><dt>Warning</dt><dd>Prior to release v3.4.0, calling <aclass="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 <aclass="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 <aclass="el"href="group__sub_group.html#gaee87f8be0e6c2a4693ba2cea070583ba"title="Unsubscribes.">natsSubscription_Unsubscribe</a> or <aclass="el"href="group__js_assets_group.html#ga52fbc61759b11494db91f348a733c490"title="Deletes a consumer.">js_DeleteConsumer</a>.</dd></dl>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">sub</td><td>the location where to store the pointer to the newly created <aclass="el"href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8"title="Interest on a given subject.">natsSubscription</a> object. </td></tr>
<tr><tdclass="paramname">js</td><td>the pointer to the <aclass="el"href="group__types_group.html#gaaf12cdd24c6cc23a57c20466c92ff8c1">jsCtx</a> object. </td></tr>
<tr><tdclass="paramname">subject</td><td>the subject this subscription is created for. </td></tr>
<tr><tdclass="paramname">cb</td><td>the <aclass="el"href="group__callbacks_group.html#gad1a5ac566893e13dc8c81ac0e9c87afe"title="Callback used to deliver messages to the application.">natsMsgHandler</a> callback. </td></tr>
<tr><tdclass="paramname">cbClosure</td><td>a pointer to an user defined object (can be <code>NULL</code>). See the <aclass="el"href="group__callbacks_group.html#gad1a5ac566893e13dc8c81ac0e9c87afe"title="Callback used to deliver messages to the application.">natsMsgHandler</a> prototype. </td></tr>
<tr><tdclass="paramname">opts</td><td>the pointer to the <aclass="el"href="structjs_options.html">jsOptions</a> object, possibly <code>NULL</code>. </td></tr>
<p>See important notes in <aclass="el"href="group__js_sub_group.html#gaa686c6efd84ef963de1925108e896515"title="Create an asynchronous subscription.">js_Subscribe</a>.</p>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">sub</td><td>the location where to store the pointer to the newly created <aclass="el"href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8"title="Interest on a given subject.">natsSubscription</a> object. </td></tr>
<tr><tdclass="paramname">js</td><td>the pointer to the <aclass="el"href="group__types_group.html#gaaf12cdd24c6cc23a57c20466c92ff8c1">jsCtx</a> object. </td></tr>
<tr><tdclass="paramname">subject</td><td>the subject this subscription is created for. the <aclass="el"href="group__callbacks_group.html#gad1a5ac566893e13dc8c81ac0e9c87afe"title="Callback used to deliver messages to the application.">natsMsgHandler</a> prototype. </td></tr>
<tr><tdclass="paramname">opts</td><td>the pointer to the <aclass="el"href="structjs_options.html">jsOptions</a> object, possibly <code>NULL</code>. </td></tr>
<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>
<dlclass="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 <aclass="el"href="group__js_sub_group.html#gaa686c6efd84ef963de1925108e896515"title="Create an asynchronous subscription.">js_Subscribe</a>.</p>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">sub</td><td>the location where to store the pointer to the newly created <aclass="el"href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8"title="Interest on a given subject.">natsSubscription</a> object. </td></tr>
<tr><tdclass="paramname">js</td><td>the pointer to the <aclass="el"href="group__types_group.html#gaaf12cdd24c6cc23a57c20466c92ff8c1">jsCtx</a> object. </td></tr>
<tr><tdclass="paramname">subject</td><td>the subject this subscription is created for. </td></tr>
<tr><tdclass="paramname">opts</td><td>the pointer to the <aclass="el"href="structjs_options.html">jsOptions</a> object, possibly <code>NULL</code>. </td></tr>
<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(&list, sub, 10, 5000)</code> may return after less than 5 seconds with only 3 messages.</p>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">list</td><td>the location to a <aclass="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><tdclass="paramname">sub</td><td>the pointer to the <aclass="el"href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8"title="Interest on a given subject.">natsSubscription</a> object. </td></tr>
<tr><tdclass="paramname">batch</td><td>the batch size, that is, the maximum number of messages to return. </td></tr>
<tr><tdclass="paramname">timeout</td><td>the timeout (required) expressed in number of milliseconds. </td></tr>
<tr><tdclass="paramname">errCode</td><td>the location where to store the JetStream specific error code, or <code>NULL</code> if not needed. </td></tr>
<p>Use this before setting specific fetch options and passing it to <aclass="el"href="group__js_sub_group.html#ga676292505e7fde8688cfd886b79a10ed"title="Fetches messages for a pull subscription with a complete request configuration.">natsSubscription_FetchRequest</a>.</p>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">request</td><td>the pointer to the <aclass="el"href="structjs_fetch_request.html">jsFetchRequest</a> object. </td></tr>
<p>Similar to <aclass="el"href="group__js_sub_group.html#gafc5e0d2269bd23b4d5fb7f3b05278e50"title="Fetches messages for a pull subscription.">natsSubscription_Fetch</a> but a full <aclass="el"href="structjs_fetch_request.html">jsFetchRequest</a> configuration is provided for maximum control.</p>
<p>Initialize the <aclass="el"href="structjs_fetch_request.html">jsFetchRequest</a> structure using <aclass="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>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">list</td><td>the location to a <aclass="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><tdclass="paramname">sub</td><td>the pointer to the <aclass="el"href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8"title="Interest on a given subject.">natsSubscription</a> object. </td></tr>
<tr><tdclass="paramname">request</td><td>the pointer to a <aclass="el"href="structjs_fetch_request.html">jsFetchRequest</a> configuration. </td></tr>
<p>Returns the <aclass="el"href="structjs_consumer_info.html">jsConsumerInfo</a> associated with this subscription.</p>
<dlclass="params"><dt>Parameters</dt><dd>
<tableclass="params">
<tr><tdclass="paramname">ci</td><td>the location where to store the pointer to the new <aclass="el"href="structjs_consumer_info.html">jsConsumerInfo</a> object. </td></tr>
<tr><tdclass="paramname">sub</td><td>the pointer to the <aclass="el"href="group__types_group.html#ga87158ec63b4f90f69e20451624ea01d8"title="Interest on a given subject.">natsSubscription</a> object. </td></tr>
<tr><tdclass="paramname">opts</td><td>the pointer to the <aclass="el"href="structjs_options.html">jsOptions</a> object, possibly <code>NULL</code>. </td></tr>
<tr><tdclass="paramname">errCode</td><td>the location where to store the JetStream specific error code, or <code>NULL</code> if not needed. </td></tr>
<p>If <code>Heartbeat</code> is configured in <aclass="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 <aclass="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 <aclass="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 <aclass="el"href="group__sub_group.html#ga6538a5d78dfb0f16514b94c8e74c11af"title="Returns the next available message.">natsSubscription_NextMsg()</a> will return the error <aclass="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>
<dlclass="section note"><dt>Note</dt><dd>For a valid JetStream subscription, this function will return <aclass="el"href="status_8h.html#a36c934157b663b7b5fb5d6609c897c80ad0229a12b17d3d12a28efed6213720d8">NATS_NOT_FOUND</a> if no consumer sequence mismatch has been detected.</dd></dl>
<tr><tdclass="paramname">csm</td><td>the pointer location where to copy the consumer sequence mismatch information. </td></tr>
<tr><tdclass="paramname">sub</td><td>the pointer to the <aclass="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 -->
<divid="nav-path"class="navpath"><!-- id is needed for treeview function! -->
<ul>
<liclass="footer">NATS.IO Supported By Synadia Communications Inc.