You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by jr...@apache.org on 2017/08/30 03:12:51 UTC
[32/51] [partial] qpid-site git commit: QPID-7903: Publish a snapshot
of the Proton C docs
http://git-wip-us.apache.org/repos/asf/qpid-site/blob/36c59045/content/releases/qpid-proton-master/proton/c/api/group__link.html
----------------------------------------------------------------------
diff --git a/content/releases/qpid-proton-master/proton/c/api/group__link.html b/content/releases/qpid-proton-master/proton/c/api/group__link.html
index 7387805..0462ef7 100755
--- a/content/releases/qpid-proton-master/proton/c/api/group__link.html
+++ b/content/releases/qpid-proton-master/proton/c/api/group__link.html
@@ -3,7 +3,8 @@
<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.8.11"/>
+<meta name="generator" content="Doxygen 1.8.13"/>
+<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Qpid Proton C API: Link</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
@@ -14,7 +15,6 @@
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
- $(window).load(resizeHeight);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
@@ -55,7 +55,7 @@
</table>
</div>
<!-- end header part -->
-<!-- Generated by Doxygen 1.8.11 -->
+<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
@@ -261,11 +261,22 @@ Functions</h2></td></tr>
<tr class="memitem:ga4a821eaf6298b94522572fad73b8e2d1"><td class="memItemLeft" align="right" valign="top">bool </td><td class="memItemRight" valign="bottom"><a class="el" href="group__link.html#ga4a821eaf6298b94522572fad73b8e2d1">pn_link_draining</a> (<a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> *receiver)</td></tr>
<tr class="memdesc:ga4a821eaf6298b94522572fad73b8e2d1"><td class="mdescLeft"> </td><td class="mdescRight">Check if a link is currently draining. <a href="#ga4a821eaf6298b94522572fad73b8e2d1">More...</a><br /></td></tr>
<tr class="separator:ga4a821eaf6298b94522572fad73b8e2d1"><td class="memSeparator" colspan="2"> </td></tr>
+<tr class="memitem:gac282341dacff892eba8e224eca5c5c52"><td class="memItemLeft" align="right" valign="top">uint64_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__link.html#gac282341dacff892eba8e224eca5c5c52">pn_link_max_message_size</a> (<a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> *link)</td></tr>
+<tr class="memdesc:gac282341dacff892eba8e224eca5c5c52"><td class="mdescLeft"> </td><td class="mdescRight"><b>Experimental</b> - Get the maximum message size for a link. <a href="#gac282341dacff892eba8e224eca5c5c52">More...</a><br /></td></tr>
+<tr class="separator:gac282341dacff892eba8e224eca5c5c52"><td class="memSeparator" colspan="2"> </td></tr>
+<tr class="memitem:ga2421a9ddebba208338412dea365cf6ad"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="group__link.html#ga2421a9ddebba208338412dea365cf6ad">pn_link_set_max_message_size</a> (<a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> *link, uint64_t size)</td></tr>
+<tr class="memdesc:ga2421a9ddebba208338412dea365cf6ad"><td class="mdescLeft"> </td><td class="mdescRight"><b>Experimental</b> - Set the maximum message size for a link. <a href="#ga2421a9ddebba208338412dea365cf6ad">More...</a><br /></td></tr>
+<tr class="separator:ga2421a9ddebba208338412dea365cf6ad"><td class="memSeparator" colspan="2"> </td></tr>
+<tr class="memitem:ga9fc507fe3e207e84f2fc251cf9bd833d"><td class="memItemLeft" align="right" valign="top">uint64_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__link.html#ga9fc507fe3e207e84f2fc251cf9bd833d">pn_link_remote_max_message_size</a> (<a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> *link)</td></tr>
+<tr class="memdesc:ga9fc507fe3e207e84f2fc251cf9bd833d"><td class="mdescLeft"> </td><td class="mdescRight"><b>Experimental</b> - Get the remote view of the maximum message size for a link. <a href="#ga9fc507fe3e207e84f2fc251cf9bd833d">More...</a><br /></td></tr>
+<tr class="separator:ga9fc507fe3e207e84f2fc251cf9bd833d"><td class="memSeparator" colspan="2"> </td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<p>A channel for transferring messages. </p>
<h2 class="groupheader">Typedef Documentation</h2>
-<a class="anchor" id="ga89dad3aa7934329a7ff467c636687bc0"></a>
+<a id="ga89dad3aa7934329a7ff467c636687bc0"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#ga89dad3aa7934329a7ff467c636687bc0">◆ </a></span>pn_link_t</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
@@ -282,116 +293,143 @@ Functions</h2></td></tr>
</div>
</div>
<h2 class="groupheader">Enumeration Type Documentation</h2>
-<a class="anchor" id="gad1c2388cdae687be26222a5d66fd2d58"></a>
+<a id="ga3fb58bd0b88d37407ebb615c2630e608"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#ga3fb58bd0b88d37407ebb615c2630e608">◆ </a></span>pn_snd_settle_mode_t</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname">enum <a class="el" href="group__link.html#gad1c2388cdae687be26222a5d66fd2d58">pn_rcv_settle_mode_t</a></td>
+ <td class="memname">enum <a class="el" href="group__link.html#ga3fb58bd0b88d37407ebb615c2630e608">pn_snd_settle_mode_t</a></td>
</tr>
</table>
</div><div class="memdoc">
-<p>Describes the permitted/expected settlement behaviours of a receiving link. </p>
-<p>The receiver settle mode describes the permitted and expected behaviour of a receiving link with respect to settling of deliveries. See <a class="el" href="group__delivery.html#ga98c275fd7158e8b9d7d48d70503d68df" title="Settle a delivery. ">pn_delivery_settle</a> for more details. </p>
+<p>Describes the permitted/expected settlement behaviours of a sending link. </p>
+<p>The sender settle mode describes the permitted and expected behaviour of a sending link with respect to settling of deliveries. See <a class="el" href="group__delivery.html#ga98c275fd7158e8b9d7d48d70503d68df" title="Settle a delivery. ">pn_delivery_settle</a> for more details. </p>
<table class="fieldtable">
-<tr><th colspan="2">Enumerator</th></tr><tr><td class="fieldname"><a class="anchor" id="ggad1c2388cdae687be26222a5d66fd2d58ac22b82396bd686940dfcc861302a8262"></a>PN_RCV_FIRST </td><td class="fielddoc">
-<p>The receiver will settle deliveries regardless of what the sender does. </p>
+<tr><th colspan="2">Enumerator</th></tr><tr><td class="fieldname"><a id="gga3fb58bd0b88d37407ebb615c2630e608a8bd9806d2f8d8c1724ed26bb0543bade"></a>PN_SND_UNSETTLED </td><td class="fielddoc"><p>The sender will send all deliveries initially unsettled. </p>
</td></tr>
-<tr><td class="fieldname"><a class="anchor" id="ggad1c2388cdae687be26222a5d66fd2d58ac79dc7f63fce078a8f0fe268c81dcaf3"></a>PN_RCV_SECOND </td><td class="fielddoc">
-<p>The receiver will only settle deliveries after the sender settles. </p>
+<tr><td class="fieldname"><a id="gga3fb58bd0b88d37407ebb615c2630e608ac159f0edca565961b554768a42e82bf0"></a>PN_SND_SETTLED </td><td class="fielddoc"><p>The sender will send all deliveries settled to the receiver. </p>
+</td></tr>
+<tr><td class="fieldname"><a id="gga3fb58bd0b88d37407ebb615c2630e608ac33a5700d0247976b465aeb7c1437fd1"></a>PN_SND_MIXED </td><td class="fielddoc"><p>The sender may send a mixure of settled and unsettled deliveries. </p>
</td></tr>
</table>
</div>
</div>
-<a class="anchor" id="ga3fb58bd0b88d37407ebb615c2630e608"></a>
+<a id="gad1c2388cdae687be26222a5d66fd2d58"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#gad1c2388cdae687be26222a5d66fd2d58">◆ </a></span>pn_rcv_settle_mode_t</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname">enum <a class="el" href="group__link.html#ga3fb58bd0b88d37407ebb615c2630e608">pn_snd_settle_mode_t</a></td>
+ <td class="memname">enum <a class="el" href="group__link.html#gad1c2388cdae687be26222a5d66fd2d58">pn_rcv_settle_mode_t</a></td>
</tr>
</table>
</div><div class="memdoc">
-<p>Describes the permitted/expected settlement behaviours of a sending link. </p>
-<p>The sender settle mode describes the permitted and expected behaviour of a sending link with respect to settling of deliveries. See <a class="el" href="group__delivery.html#ga98c275fd7158e8b9d7d48d70503d68df" title="Settle a delivery. ">pn_delivery_settle</a> for more details. </p>
+<p>Describes the permitted/expected settlement behaviours of a receiving link. </p>
+<p>The receiver settle mode describes the permitted and expected behaviour of a receiving link with respect to settling of deliveries. See <a class="el" href="group__delivery.html#ga98c275fd7158e8b9d7d48d70503d68df" title="Settle a delivery. ">pn_delivery_settle</a> for more details. </p>
<table class="fieldtable">
-<tr><th colspan="2">Enumerator</th></tr><tr><td class="fieldname"><a class="anchor" id="gga3fb58bd0b88d37407ebb615c2630e608a8bd9806d2f8d8c1724ed26bb0543bade"></a>PN_SND_UNSETTLED </td><td class="fielddoc">
-<p>The sender will send all deliveries initially unsettled. </p>
+<tr><th colspan="2">Enumerator</th></tr><tr><td class="fieldname"><a id="ggad1c2388cdae687be26222a5d66fd2d58ac22b82396bd686940dfcc861302a8262"></a>PN_RCV_FIRST </td><td class="fielddoc"><p>The receiver will settle deliveries regardless of what the sender does. </p>
</td></tr>
-<tr><td class="fieldname"><a class="anchor" id="gga3fb58bd0b88d37407ebb615c2630e608ac159f0edca565961b554768a42e82bf0"></a>PN_SND_SETTLED </td><td class="fielddoc">
-<p>The sender will send all deliveries settled to the receiver. </p>
-</td></tr>
-<tr><td class="fieldname"><a class="anchor" id="gga3fb58bd0b88d37407ebb615c2630e608ac33a5700d0247976b465aeb7c1437fd1"></a>PN_SND_MIXED </td><td class="fielddoc">
-<p>The sender may send a mixure of settled and unsettled deliveries. </p>
+<tr><td class="fieldname"><a id="ggad1c2388cdae687be26222a5d66fd2d58ac79dc7f63fce078a8f0fe268c81dcaf3"></a>PN_RCV_SECOND </td><td class="fielddoc"><p>The receiver will only settle deliveries after the sender settles. </p>
</td></tr>
</table>
</div>
</div>
<h2 class="groupheader">Function Documentation</h2>
-<a class="anchor" id="ga93824a3859c37463e44458cd2f63d31f"></a>
+<a id="ga469bef2e81c53e85899ffbb277616a8c"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#ga469bef2e81c53e85899ffbb277616a8c">◆ </a></span>pn_sender()</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname">bool pn_link_advance </td>
+ <td class="memname"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a>* pn_sender </td>
<td>(</td>
- <td class="paramtype"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> * </td>
- <td class="paramname"><em>link</em></td><td>)</td>
+ <td class="paramtype"><a class="el" href="group__session.html#ga38ccb93b8f5c2892adafce5d5f0fbcd9">pn_session_t</a> * </td>
+ <td class="paramname"><em>session</em>, </td>
+ </tr>
+ <tr>
+ <td class="paramkey"></td>
+ <td></td>
+ <td class="paramtype">const char * </td>
+ <td class="paramname"><em>name</em> </td>
+ </tr>
+ <tr>
<td></td>
+ <td>)</td>
+ <td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
-<p>Advance the current delivery of a link to the next delivery on the link. </p>
-<p>For sending links this operation is used to finish sending message data for the current outgoing delivery and move on to the next outgoing delivery (if any).</p>
-<p>For receiving links, this operation is used to finish accessing message data from the current incoming delivery and move on to the next incoming delivery (if any).</p>
-<p>Each link maintains a sequence of deliveries in the order they were created, along with a pointer to the <em>current</em> delivery. The pn_link_advance operation will modify the <em>current</em> delivery on the link to point to the next delivery in the sequence. If there is no next delivery in the sequence, the current delivery will be set to NULL. This operation will return true if invoking it caused the value of the current delivery to change, even if it was set to NULL.</p>
+<p>Construct a new sender on a session. </p>
+<p>Each sending link between two AMQP containers must be uniquely named. Note that this uniqueness cannot be enforced at the API level, so some consideration should be taken in choosing link names.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
- <tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>a link object </td></tr>
+ <tr><td class="paramdir">[in]</td><td class="paramname">session</td><td>the session object </td></tr>
+ <tr><td class="paramdir">[in]</td><td class="paramname">name</td><td>the name of the link </td></tr>
</table>
</dd>
</dl>
-<dl class="section return"><dt>Returns</dt><dd>true if the current delivery was changed </dd></dl>
-<dl><dt><b>Examples: </b></dt><dd><a class="el" href="broker_8c-example.html#a9">broker.c</a>, <a class="el" href="receive_8c-example.html#a31">receive.c</a>, and <a class="el" href="send_8c-example.html#a30">send.c</a>.</dd>
+<dl class="section return"><dt>Returns</dt><dd>a newly constructed sender link or NULL on error </dd></dl>
+<dl><dt><b>Examples: </b></dt><dd><a class="el" href="send_8c-example.html#a31">send.c</a>.</dd>
</dl>
</div>
</div>
-<a class="anchor" id="ga8b19ffdb7934940fa7c5fd75c5fe2d69"></a>
+<a id="ga5e314b3e07b48ebcffbac63f265fa69f"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#ga5e314b3e07b48ebcffbac63f265fa69f">◆ </a></span>pn_receiver()</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname">pn_record_t* pn_link_attachments </td>
+ <td class="memname"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a>* pn_receiver </td>
<td>(</td>
- <td class="paramtype"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> * </td>
- <td class="paramname"><em>link</em></td><td>)</td>
+ <td class="paramtype"><a class="el" href="group__session.html#ga38ccb93b8f5c2892adafce5d5f0fbcd9">pn_session_t</a> * </td>
+ <td class="paramname"><em>session</em>, </td>
+ </tr>
+ <tr>
+ <td class="paramkey"></td>
+ <td></td>
+ <td class="paramtype">const char * </td>
+ <td class="paramname"><em>name</em> </td>
+ </tr>
+ <tr>
<td></td>
+ <td>)</td>
+ <td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
-<p>Get the attachments that are associated with a link object. </p>
+<p>Construct a new receiver on a session. </p>
+<p>Each receiving link between two AMQP containers must be uniquely named. Note that this uniqueness cannot be enforced at the API level, so some consideration should be taken in choosing link names.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
- <tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>the link whose attachments are to be returned. </td></tr>
+ <tr><td class="paramdir">[in]</td><td class="paramname">session</td><td>the session object </td></tr>
+ <tr><td class="paramdir">[in]</td><td class="paramname">name</td><td>the name of the link </td></tr>
</table>
</dd>
</dl>
-<dl class="section return"><dt>Returns</dt><dd>the attachments for the link object </dd></dl>
-
+<dl class="section return"><dt>Returns</dt><dd>a newly constructed receiver link or NULL on error </dd></dl>
+<dl><dt><b>Examples: </b></dt><dd><a class="el" href="receive_8c-example.html#a20">receive.c</a>.</dd>
+</dl>
</div>
</div>
-<a class="anchor" id="ga7f1742528b32c3c9609b97a3ed449639"></a>
+<a id="gadd3b8899fe023d3506fb88d228d6b1b7"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#gadd3b8899fe023d3506fb88d228d6b1b7">◆ </a></span>pn_link_free()</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname">int pn_link_available </td>
+ <td class="memname">void pn_link_free </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> * </td>
<td class="paramname"><em>link</em></td><td>)</td>
@@ -400,24 +438,26 @@ Functions</h2></td></tr>
</table>
</div><div class="memdoc">
-<p>Get the available deliveries hint for a link. </p>
-<p>The available count for a link provides a hint as to the number of deliveries that might be able to be sent if sufficient credit were issued by the receiving link endpoint. See <a class="el" href="group__link.html#gaef3f2e4bca87f9adc70e90dce7cd42b2" title="Signal the availability of deliveries for a link. ">pn_link_offered</a> for more details.</p>
+<p>Free a link object. </p>
+<p>When a link object is freed, all <a class="el" href="group__delivery.html#gacdfce854066c0a4ff4db9f9a0478f340" title="An AMQP Delivery object. ">pn_delivery_t</a> objects associated with the session are also freed. Freeing a link will settle any unsettled deliveries on the link.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
- <tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>a link object </td></tr>
+ <tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>a link object to free (or NULL) </td></tr>
</table>
</dd>
</dl>
-<dl class="section return"><dt>Returns</dt><dd>the available deliveries hint </dd></dl>
-
+<dl><dt><b>Examples: </b></dt><dd><a class="el" href="broker_8c-example.html#a78">broker.c</a>.</dd>
+</dl>
</div>
</div>
-<a class="anchor" id="ga4851693eb6a16fd9ab61e2df6f00770d"></a>
+<a id="ga93e6b527743f433da2ff367c1b2c500a"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#ga93e6b527743f433da2ff367c1b2c500a">◆ </a></span>pn_link_get_context()</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname">void pn_link_close </td>
+ <td class="memname">void* pn_link_get_context </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> * </td>
<td class="paramname"><em>link</em></td><td>)</td>
@@ -425,52 +465,65 @@ Functions</h2></td></tr>
</tr>
</table>
</div><div class="memdoc">
-
-<p>Close a link. </p>
-<p>Once this operation has completed, the PN_LOCAL_CLOSED state flag will be set. This may be called without calling <a class="el" href="group__link.html#gaabaca3f5d03970a122240eebc588add6" title="Open a link. ">pn_link_open</a>, in this case it is equivalent to calling <a class="el" href="group__link.html#gaabaca3f5d03970a122240eebc588add6" title="Open a link. ">pn_link_open</a> followed by <a class="el" href="group__link.html#ga4851693eb6a16fd9ab61e2df6f00770d" title="Close a link. ">pn_link_close</a>.</p>
+<dl class="deprecated"><dt><b><a class="el" href="deprecated.html#_deprecated000006">Deprecated:</a></b></dt><dd></dd></dl>
+<p>Get the application context that is associated with a link object.</p>
+<p>The application context for a link may be set using <a class="el" href="group__link.html#ga376f2cc18bbd771d95aa8222586d19b2">pn_link_set_context</a>.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
- <tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>a link object </td></tr>
+ <tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>the link whose context is to be returned. </td></tr>
</table>
</dd>
</dl>
-<dl><dt><b>Examples: </b></dt><dd><a class="el" href="broker_8c-example.html#a79">broker.c</a>, and <a class="el" href="receive_8c-example.html#a35">receive.c</a>.</dd>
-</dl>
+<dl class="section return"><dt>Returns</dt><dd>the application context for the link object </dd></dl>
+
</div>
</div>
-<a class="anchor" id="ga52c99044eabb7712efa2f1098c760804"></a>
+<a id="ga376f2cc18bbd771d95aa8222586d19b2"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#ga376f2cc18bbd771d95aa8222586d19b2">◆ </a></span>pn_link_set_context()</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname"><a class="el" href="group__condition.html#ga11eb7db7d2c205169fe3d47c996a95a5">pn_condition_t</a>* pn_link_condition </td>
+ <td class="memname">void pn_link_set_context </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> * </td>
- <td class="paramname"><em>link</em></td><td>)</td>
+ <td class="paramname"><em>link</em>, </td>
+ </tr>
+ <tr>
+ <td class="paramkey"></td>
+ <td></td>
+ <td class="paramtype">void * </td>
+ <td class="paramname"><em>context</em> </td>
+ </tr>
+ <tr>
<td></td>
+ <td>)</td>
+ <td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
-
-<p>Get the local condition associated with a link endpoint. </p>
-<p>The <a class="el" href="group__condition.html#ga11eb7db7d2c205169fe3d47c996a95a5" title="An AMQP Condition object. ">pn_condition_t</a> object retrieved may be modified prior to closing a link in order to indicate a particular condition exists when the link closes. This is normally used to communicate error conditions to the remote peer, however it may also be used in non error cases. See <a class="el" href="group__condition.html#ga11eb7db7d2c205169fe3d47c996a95a5" title="An AMQP Condition object. ">pn_condition_t</a> for more details.</p>
-<p>The pointer returned by this operation is valid until the link object is freed.</p>
+<dl class="deprecated"><dt><b><a class="el" href="deprecated.html#_deprecated000007">Deprecated:</a></b></dt><dd></dd></dl>
+<p>Set a new application context for a link object.</p>
+<p>The application context for a link object may be retrieved using <a class="el" href="group__link.html#ga93e6b527743f433da2ff367c1b2c500a">pn_link_get_context</a>.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>the link object </td></tr>
+ <tr><td class="paramdir">[in]</td><td class="paramname">context</td><td>the application context </td></tr>
</table>
</dd>
</dl>
-<dl class="section return"><dt>Returns</dt><dd>the link's local condition object </dd></dl>
</div>
</div>
-<a class="anchor" id="ga55428637f3b8c446efd5fea3f26c932d"></a>
+<a id="ga8b19ffdb7934940fa7c5fd75c5fe2d69"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#ga8b19ffdb7934940fa7c5fd75c5fe2d69">◆ </a></span>pn_link_attachments()</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname">int pn_link_credit </td>
+ <td class="memname">pn_record_t* pn_link_attachments </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> * </td>
<td class="paramname"><em>link</em></td><td>)</td>
@@ -479,26 +532,25 @@ Functions</h2></td></tr>
</table>
</div><div class="memdoc">
-<p>Get the credit balance for a link. </p>
-<p>Links use a credit based flow control scheme. Every receiver maintains a credit balance that corresponds to the number of deliveries that the receiver can accept at any given moment. As more capacity becomes available at the receiver (see <a class="el" href="group__link.html#gafec44cf1c79ec03f3ac009e1879e71a9" title="Grant credit for incoming deliveries on a receiver. ">pn_link_flow</a>), it adds credit to this balance and communicates the new balance to the sender. Whenever a delivery is sent/received, the credit balance maintained by the link is decremented by one. Once the credit balance at the sender reaches zero, the sender must pause sending until more credit is obtained from the receiver.</p>
-<p>Note that a sending link may still be used to send deliveries even if pn_link_credit reaches zero, however those deliveries will end up being buffered by the link until enough credit is obtained from the receiver to send them over the wire. In this case the balance reported by <a class="el" href="group__link.html#ga55428637f3b8c446efd5fea3f26c932d" title="Get the credit balance for a link. ">pn_link_credit</a> will go negative.</p>
+<p>Get the attachments that are associated with a link object. </p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
- <tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>a link object </td></tr>
+ <tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>the link whose attachments are to be returned. </td></tr>
</table>
</dd>
</dl>
-<dl class="section return"><dt>Returns</dt><dd>the credit balance for the link </dd></dl>
-<dl><dt><b>Examples: </b></dt><dd><a class="el" href="broker_8c-example.html#a17">broker.c</a>, <a class="el" href="receive_8c-example.html#a33">receive.c</a>, and <a class="el" href="send_8c-example.html#a24">send.c</a>.</dd>
-</dl>
+<dl class="section return"><dt>Returns</dt><dd>the attachments for the link object </dd></dl>
+
</div>
</div>
-<a class="anchor" id="gad7e426b0cc4759568b3fd2b4fb176260"></a>
+<a id="gaa44112980ebabbb5cbd002670073a751"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#gaa44112980ebabbb5cbd002670073a751">◆ </a></span>pn_link_name()</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname"><a class="el" href="group__delivery.html#gacdfce854066c0a4ff4db9f9a0478f340">pn_delivery_t</a>* pn_link_current </td>
+ <td class="memname">const char* pn_link_name </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> * </td>
<td class="paramname"><em>link</em></td><td>)</td>
@@ -507,24 +559,25 @@ Functions</h2></td></tr>
</table>
</div><div class="memdoc">
-<p>Get the current delivery for a link. </p>
-<p>Each link maintains a sequence of deliveries in the order they were created, along with a pointer to the <em>current</em> delivery. All send/recv operations on a link take place on the <em>current</em> delivery. If a link has no current delivery, the current delivery is automatically initialized to the next delivery created on the link. Once initialized, the current delivery remains the same until it is changed through use of <a class="el" href="group__link.html#ga93824a3859c37463e44458cd2f63d31f" title="Advance the current delivery of a link to the next delivery on the link. ">pn_link_advance</a> or until it is settled via <a class="el" href="group__delivery.html#ga98c275fd7158e8b9d7d48d70503d68df" title="Settle a delivery. ">pn_delivery_settle</a>.</p>
+<p>Get the name of a link. </p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>a link object </td></tr>
</table>
</dd>
</dl>
-<dl class="section return"><dt>Returns</dt><dd>the current delivery for the link, or NULL if there is none </dd></dl>
+<dl class="section return"><dt>Returns</dt><dd>the name of the link </dd></dl>
</div>
</div>
-<a class="anchor" id="ga1dc327c52ac24a0d65a17c88ce685b0b"></a>
+<a id="ga7c48ef214568267839aea04ed337926b"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#ga7c48ef214568267839aea04ed337926b">◆ </a></span>pn_link_is_sender()</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname">void pn_link_detach </td>
+ <td class="memname">bool pn_link_is_sender </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> * </td>
<td class="paramname"><em>link</em></td><td>)</td>
@@ -533,58 +586,54 @@ Functions</h2></td></tr>
</table>
</div><div class="memdoc">
-<p>Detach a link. </p>
+<p>Test if a link is a sender. </p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>a link object </td></tr>
</table>
</dd>
</dl>
-
+<dl class="section return"><dt>Returns</dt><dd>true if and only if the link is a sender </dd></dl>
+<dl><dt><b>Examples: </b></dt><dd><a class="el" href="broker_8c-example.html#a14">broker.c</a>, and <a class="el" href="direct_8c-example.html#a89">direct.c</a>.</dd>
+</dl>
</div>
</div>
-<a class="anchor" id="gad7ad9bc5c9ea7e8a21cd4fa472d2c8df"></a>
+<a id="gae7045dd02f2c9450ff8737e005628d81"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#gae7045dd02f2c9450ff8737e005628d81">◆ </a></span>pn_link_is_receiver()</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname">void pn_link_drain </td>
+ <td class="memname">bool pn_link_is_receiver </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> * </td>
- <td class="paramname"><em>receiver</em>, </td>
- </tr>
- <tr>
- <td class="paramkey"></td>
- <td></td>
- <td class="paramtype">int </td>
- <td class="paramname"><em>credit</em> </td>
- </tr>
- <tr>
+ <td class="paramname"><em>link</em></td><td>)</td>
<td></td>
- <td>)</td>
- <td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
-<p>Grant credit for incoming deliveries on a receiver, and set drain mode to true. </p>
-<p>Use <a class="el" href="group__link.html#gaeb417e6b7e99c76f61549f5ed5519395" title="Set the drain mode on a link. ">pn_link_set_drain</a> to set the drain mode explicitly.</p>
+<p>Test if a link is a receiver. </p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
- <tr><td class="paramdir">[in]</td><td class="paramname">receiver</td><td>a receiving link object </td></tr>
- <tr><td class="paramdir">[in]</td><td class="paramname">credit</td><td>the amount to increment the link credit </td></tr>
+ <tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>a link object </td></tr>
</table>
</dd>
</dl>
-
+<dl class="section return"><dt>Returns</dt><dd>true if and only if the link is a receiver </dd></dl>
+<dl><dt><b>Examples: </b></dt><dd><a class="el" href="broker_8c-example.html#a58">broker.c</a>.</dd>
+</dl>
</div>
</div>
-<a class="anchor" id="ga95c4018a1f1fe0e7c2e7fd02fe062d23"></a>
+<a id="gad502b38bc184ad0bfaa86dede81f62c9"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#gad502b38bc184ad0bfaa86dede81f62c9">◆ </a></span>pn_link_state()</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname">int pn_link_drained </td>
+ <td class="memname"><a class="el" href="group__connection.html#gaa83193a655e32bffc18624acc2c39233">pn_state_t</a> pn_link_state </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> * </td>
<td class="paramname"><em>link</em></td><td>)</td>
@@ -593,52 +642,54 @@ Functions</h2></td></tr>
</table>
</div><div class="memdoc">
-<p>Drain excess credit for a link. </p>
-<p>When a link is in drain mode, the sender must use all excess credit immediately, and release any excess credit back to the receiver if there are no deliveries available to send.</p>
-<p>When invoked on a sending link that is in drain mode, this operation will release all excess credit back to the receiver and return the number of credits released back to the sender. If the link is not in drain mode, this operation is a noop.</p>
-<p>When invoked on a receiving link, this operation will return and reset the number of credits the sender has released back to the receiver.</p>
+<p>Get the endpoint state flags for a link. </p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
- <tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>a link object </td></tr>
+ <tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>the link </td></tr>
</table>
</dd>
</dl>
-<dl class="section return"><dt>Returns</dt><dd>the number of credits drained </dd></dl>
+<dl class="section return"><dt>Returns</dt><dd>the link's state flags </dd></dl>
</div>
</div>
-<a class="anchor" id="ga4a821eaf6298b94522572fad73b8e2d1"></a>
+<a id="gaf6f11d778aa4622d8aa5db8962bb1f0a"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#gaf6f11d778aa4622d8aa5db8962bb1f0a">◆ </a></span>pn_link_error()</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname">bool pn_link_draining </td>
+ <td class="memname"><a class="el" href="group__error.html#ga24a289d5b32c9bd8a775600a5af83d52">pn_error_t</a>* pn_link_error </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> * </td>
- <td class="paramname"><em>receiver</em></td><td>)</td>
+ <td class="paramname"><em>link</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
-
-<p>Check if a link is currently draining. </p>
-<p>A link is defined to be draining when drain mode is set to true, and the sender still has excess credit.</p>
+<dl class="deprecated"><dt><b><a class="el" href="deprecated.html#_deprecated000008">Deprecated:</a></b></dt><dd></dd></dl>
+<p>Get additional error information associated with the link.</p>
+<p>Whenever a link operation fails (i.e. returns an error code), additional error details can be obtained using this function. The error object that is returned may also be used to clear the error condition.</p>
+<p>The pointer returned by this operation is valid until the link object is freed.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
- <tr><td class="paramdir">[in]</td><td class="paramname">receiver</td><td>a receiving link object </td></tr>
+ <tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>the link object </td></tr>
</table>
</dd>
</dl>
-<dl class="section return"><dt>Returns</dt><dd>true if the link is currently draining, false otherwise </dd></dl>
+<dl class="section return"><dt>Returns</dt><dd>the link's error object </dd></dl>
</div>
</div>
-<a class="anchor" id="gaf6f11d778aa4622d8aa5db8962bb1f0a"></a>
+<a id="ga52c99044eabb7712efa2f1098c760804"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#ga52c99044eabb7712efa2f1098c760804">◆ </a></span>pn_link_condition()</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname"><a class="el" href="group__error.html#ga24a289d5b32c9bd8a775600a5af83d52">pn_error_t</a>* pn_link_error </td>
+ <td class="memname"><a class="el" href="group__condition.html#ga11eb7db7d2c205169fe3d47c996a95a5">pn_condition_t</a>* pn_link_condition </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> * </td>
<td class="paramname"><em>link</em></td><td>)</td>
@@ -646,9 +697,9 @@ Functions</h2></td></tr>
</tr>
</table>
</div><div class="memdoc">
-<dl class="deprecated"><dt><b><a class="el" href="deprecated.html#_deprecated000008">Deprecated:</a></b></dt><dd></dd></dl>
-<p>Get additional error information associated with the link.</p>
-<p>Whenever a link operation fails (i.e. returns an error code), additional error details can be obtained using this function. The error object that is returned may also be used to clear the error condition.</p>
+
+<p>Get the local condition associated with a link endpoint. </p>
+<p>The <a class="el" href="group__condition.html#ga11eb7db7d2c205169fe3d47c996a95a5" title="An AMQP Condition object. ">pn_condition_t</a> object retrieved may be modified prior to closing a link in order to indicate a particular condition exists when the link closes. This is normally used to communicate error conditions to the remote peer, however it may also be used in non error cases. See <a class="el" href="group__condition.html#ga11eb7db7d2c205169fe3d47c996a95a5" title="An AMQP Condition object. ">pn_condition_t</a> for more details.</p>
<p>The pointer returned by this operation is valid until the link object is freed.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
@@ -656,52 +707,48 @@ Functions</h2></td></tr>
</table>
</dd>
</dl>
-<dl class="section return"><dt>Returns</dt><dd>the link's error object </dd></dl>
+<dl class="section return"><dt>Returns</dt><dd>the link's local condition object </dd></dl>
</div>
</div>
-<a class="anchor" id="gafec44cf1c79ec03f3ac009e1879e71a9"></a>
+<a id="ga97dc5133125c9b7e4afbb1b76e6efe7b"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#ga97dc5133125c9b7e4afbb1b76e6efe7b">◆ </a></span>pn_link_remote_condition()</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname">void pn_link_flow </td>
+ <td class="memname"><a class="el" href="group__condition.html#ga11eb7db7d2c205169fe3d47c996a95a5">pn_condition_t</a>* pn_link_remote_condition </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> * </td>
- <td class="paramname"><em>receiver</em>, </td>
- </tr>
- <tr>
- <td class="paramkey"></td>
- <td></td>
- <td class="paramtype">int </td>
- <td class="paramname"><em>credit</em> </td>
- </tr>
- <tr>
+ <td class="paramname"><em>link</em></td><td>)</td>
<td></td>
- <td>)</td>
- <td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
-<p>Grant credit for incoming deliveries on a receiver. </p>
+<p>Get the remote condition associated with a link endpoint. </p>
+<p>The <a class="el" href="group__condition.html#ga11eb7db7d2c205169fe3d47c996a95a5" title="An AMQP Condition object. ">pn_condition_t</a> object retrieved may be examined in order to determine whether the remote peer was indicating some sort of exceptional condition when the remote link endpoint was closed. The <a class="el" href="group__condition.html#ga11eb7db7d2c205169fe3d47c996a95a5" title="An AMQP Condition object. ">pn_condition_t</a> object returned may not be modified.</p>
+<p>The pointer returned by this operation is valid until the link object is freed.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
- <tr><td class="paramdir">[in]</td><td class="paramname">receiver</td><td>a receiving link object </td></tr>
- <tr><td class="paramdir">[in]</td><td class="paramname">credit</td><td>the amount to increment the link credit </td></tr>
+ <tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>the link object </td></tr>
</table>
</dd>
</dl>
-<dl><dt><b>Examples: </b></dt><dd><a class="el" href="broker_8c-example.html#a54">broker.c</a>, and <a class="el" href="receive_8c-example.html#a24">receive.c</a>.</dd>
+<dl class="section return"><dt>Returns</dt><dd>the link's remote condition object </dd></dl>
+<dl><dt><b>Examples: </b></dt><dd><a class="el" href="broker_8c-example.html#a76">broker.c</a>, <a class="el" href="direct_8c-example.html#a83">direct.c</a>, <a class="el" href="receive_8c-example.html#a48">receive.c</a>, and <a class="el" href="send_8c-example.html#a58">send.c</a>.</dd>
</dl>
</div>
</div>
-<a class="anchor" id="gadd3b8899fe023d3506fb88d228d6b1b7"></a>
+<a id="gac63e43305fb1a5e3b14399a9ddc8f24d"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#gac63e43305fb1a5e3b14399a9ddc8f24d">◆ </a></span>pn_link_session()</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname">void pn_link_free </td>
+ <td class="memname"><a class="el" href="group__session.html#ga38ccb93b8f5c2892adafce5d5f0fbcd9">pn_session_t</a>* pn_link_session </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> * </td>
<td class="paramname"><em>link</em></td><td>)</td>
@@ -710,79 +757,70 @@ Functions</h2></td></tr>
</table>
</div><div class="memdoc">
-<p>Free a link object. </p>
-<p>When a link object is freed, all <a class="el" href="group__delivery.html#gacdfce854066c0a4ff4db9f9a0478f340" title="An AMQP Delivery object. ">pn_delivery_t</a> objects associated with the session are also freed. Freeing a link will settle any unsettled deliveries on the link.</p>
+<p>Get the parent session for a link object. </p>
+<p>This operation retrieves the parent <a class="el" href="group__session.html#ga38ccb93b8f5c2892adafce5d5f0fbcd9" title="An AMQP Session object. ">pn_session_t</a> object that contains the given <a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0" title="An AMQP Link object. ">pn_link_t</a> object.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
- <tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>a link object to free (or NULL) </td></tr>
+ <tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>the link object </td></tr>
</table>
</dd>
</dl>
-<dl><dt><b>Examples: </b></dt><dd><a class="el" href="broker_8c-example.html#a80">broker.c</a>.</dd>
+<dl class="section return"><dt>Returns</dt><dd>the parent session object </dd></dl>
+<dl><dt><b>Examples: </b></dt><dd><a class="el" href="broker_8c-example.html#a2">broker.c</a>, <a class="el" href="direct_8c-example.html#a44">direct.c</a>, and <a class="el" href="receive_8c-example.html#a34">receive.c</a>.</dd>
</dl>
</div>
</div>
-<a class="anchor" id="ga93e6b527743f433da2ff367c1b2c500a"></a>
+<a id="ga7c9434c40eb653f007ff5721e2ebf73e"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#ga7c9434c40eb653f007ff5721e2ebf73e">◆ </a></span>pn_link_head()</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname">void* pn_link_get_context </td>
+ <td class="memname"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a>* pn_link_head </td>
<td>(</td>
- <td class="paramtype"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> * </td>
- <td class="paramname"><em>link</em></td><td>)</td>
- <td></td>
+ <td class="paramtype"><a class="el" href="group__connection.html#ga886351d81ff3a977a284a206526c5aff">pn_connection_t</a> * </td>
+ <td class="paramname"><em>connection</em>, </td>
+ </tr>
+ <tr>
+ <td class="paramkey"></td>
+ <td></td>
+ <td class="paramtype"><a class="el" href="group__connection.html#gaa83193a655e32bffc18624acc2c39233">pn_state_t</a> </td>
+ <td class="paramname"><em>state</em> </td>
</tr>
- </table>
-</div><div class="memdoc">
-<dl class="deprecated"><dt><b><a class="el" href="deprecated.html#_deprecated000006">Deprecated:</a></b></dt><dd></dd></dl>
-<p>Get the application context that is associated with a link object.</p>
-<p>The application context for a link may be set using <a class="el" href="group__link.html#ga376f2cc18bbd771d95aa8222586d19b2">pn_link_set_context</a>.</p>
-<dl class="params"><dt>Parameters</dt><dd>
- <table class="params">
- <tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>the link whose context is to be returned. </td></tr>
- </table>
- </dd>
-</dl>
-<dl class="section return"><dt>Returns</dt><dd>the application context for the link object </dd></dl>
-
-</div>
-</div>
-<a class="anchor" id="ga40dd26f3d035c54056e2649aeb78d8ac"></a>
-<div class="memitem">
-<div class="memproto">
- <table class="memname">
<tr>
- <td class="memname">bool pn_link_get_drain </td>
- <td>(</td>
- <td class="paramtype"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> * </td>
- <td class="paramname"><em>link</em></td><td>)</td>
<td></td>
+ <td>)</td>
+ <td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
-<p>Get the drain flag for a link. </p>
-<p>If a link is in drain mode, then the sending endpoint of a link must immediately use up all available credit on the link. If this is not possible, the excess credit must be returned by invoking <a class="el" href="group__link.html#ga95c4018a1f1fe0e7c2e7fd02fe062d23" title="Drain excess credit for a link. ">pn_link_drained</a>. Only the receiving endpoint can set the drain mode. See <a class="el" href="group__link.html#gaeb417e6b7e99c76f61549f5ed5519395" title="Set the drain mode on a link. ">pn_link_set_drain</a> for details.</p>
+<p>Retrieve the first link that matches the given state mask. </p>
+<p>Examines the state of each link owned by the connection and returns the first link that matches the given state mask. If state contains both local and remote flags, then an exact match against those flags is performed. If state contains only local or only remote flags, then a match occurs if any of the local or remote flags are set respectively. state==0 matches all links.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
- <tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>a link object </td></tr>
+ <tr><td class="paramdir">[in]</td><td class="paramname">connection</td><td>to be searched for matching Links </td></tr>
+ <tr><td class="paramdir">[in]</td><td class="paramname">state</td><td>mask to match </td></tr>
</table>
</dd>
</dl>
-<dl class="section return"><dt>Returns</dt><dd>true if and only if the link is in drain mode </dd></dl>
-
+<dl class="section return"><dt>Returns</dt><dd>the first link owned by the connection that matches the mask, else NULL if no links match </dd></dl>
+<dl><dt><b>Examples: </b></dt><dd><a class="el" href="broker_8c-example.html#a18">broker.c</a>.</dd>
+</dl>
</div>
</div>
-<a class="anchor" id="ga7c9434c40eb653f007ff5721e2ebf73e"></a>
+<a id="ga9b2a9cfa00dfdae4e01bf75483433925"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#ga9b2a9cfa00dfdae4e01bf75483433925">◆ </a></span>pn_link_next()</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a>* pn_link_head </td>
+ <td class="memname"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a>* pn_link_next </td>
<td>(</td>
- <td class="paramtype"><a class="el" href="group__connection.html#ga886351d81ff3a977a284a206526c5aff">pn_connection_t</a> * </td>
- <td class="paramname"><em>connection</em>, </td>
+ <td class="paramtype"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> * </td>
+ <td class="paramname"><em>link</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
@@ -798,26 +836,28 @@ Functions</h2></td></tr>
</table>
</div><div class="memdoc">
-<p>Retrieve the first link that matches the given state mask. </p>
-<p>Examines the state of each link owned by the connection and returns the first link that matches the given state mask. If state contains both local and remote flags, then an exact match against those flags is performed. If state contains only local or only remote flags, then a match occurs if any of the local or remote flags are set respectively. state==0 matches all links.</p>
+<p>Retrieve the next link that matches the given state mask. </p>
+<p>When used with pn_link_head, the application can access all links on the connection that match the given state. See pn_link_head for description of match behavior.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
- <tr><td class="paramdir">[in]</td><td class="paramname">connection</td><td>to be searched for matching Links </td></tr>
+ <tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>the previous link obtained from pn_link_head or pn_link_next </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">state</td><td>mask to match </td></tr>
</table>
</dd>
</dl>
-<dl class="section return"><dt>Returns</dt><dd>the first link owned by the connection that matches the mask, else NULL if no links match </dd></dl>
-<dl><dt><b>Examples: </b></dt><dd><a class="el" href="broker_8c-example.html#a20">broker.c</a>.</dd>
+<dl class="section return"><dt>Returns</dt><dd>the next session owned by the connection that matches the mask, else NULL if no sessions match </dd></dl>
+<dl><dt><b>Examples: </b></dt><dd><a class="el" href="broker_8c-example.html#a19">broker.c</a>.</dd>
</dl>
</div>
</div>
-<a class="anchor" id="gae7045dd02f2c9450ff8737e005628d81"></a>
+<a id="gaabaca3f5d03970a122240eebc588add6"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#gaabaca3f5d03970a122240eebc588add6">◆ </a></span>pn_link_open()</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname">bool pn_link_is_receiver </td>
+ <td class="memname">void pn_link_open </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> * </td>
<td class="paramname"><em>link</em></td><td>)</td>
@@ -826,24 +866,26 @@ Functions</h2></td></tr>
</table>
</div><div class="memdoc">
-<p>Test if a link is a receiver. </p>
+<p>Open a link. </p>
+<p>Once this operation has completed, the PN_LOCAL_ACTIVE state flag will be set.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>a link object </td></tr>
</table>
</dd>
</dl>
-<dl class="section return"><dt>Returns</dt><dd>true if and only if the link is a receiver </dd></dl>
-<dl><dt><b>Examples: </b></dt><dd><a class="el" href="broker_8c-example.html#a60">broker.c</a>.</dd>
+<dl><dt><b>Examples: </b></dt><dd><a class="el" href="broker_8c-example.html#a53">broker.c</a>, <a class="el" href="direct_8c-example.html#a33">direct.c</a>, <a class="el" href="receive_8c-example.html#a23">receive.c</a>, and <a class="el" href="send_8c-example.html#a34">send.c</a>.</dd>
</dl>
</div>
</div>
-<a class="anchor" id="ga7c48ef214568267839aea04ed337926b"></a>
+<a id="ga4851693eb6a16fd9ab61e2df6f00770d"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#ga4851693eb6a16fd9ab61e2df6f00770d">◆ </a></span>pn_link_close()</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname">bool pn_link_is_sender </td>
+ <td class="memname">void pn_link_close </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> * </td>
<td class="paramname"><em>link</em></td><td>)</td>
@@ -852,24 +894,26 @@ Functions</h2></td></tr>
</table>
</div><div class="memdoc">
-<p>Test if a link is a sender. </p>
+<p>Close a link. </p>
+<p>Once this operation has completed, the PN_LOCAL_CLOSED state flag will be set. This may be called without calling <a class="el" href="group__link.html#gaabaca3f5d03970a122240eebc588add6" title="Open a link. ">pn_link_open</a>, in this case it is equivalent to calling <a class="el" href="group__link.html#gaabaca3f5d03970a122240eebc588add6" title="Open a link. ">pn_link_open</a> followed by <a class="el" href="group__link.html#ga4851693eb6a16fd9ab61e2df6f00770d" title="Close a link. ">pn_link_close</a>.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>a link object </td></tr>
</table>
</dd>
</dl>
-<dl class="section return"><dt>Returns</dt><dd>true if and only if the link is a sender </dd></dl>
-<dl><dt><b>Examples: </b></dt><dd><a class="el" href="broker_8c-example.html#a16">broker.c</a>.</dd>
+<dl><dt><b>Examples: </b></dt><dd><a class="el" href="broker_8c-example.html#a77">broker.c</a>, <a class="el" href="direct_8c-example.html#a45">direct.c</a>, and <a class="el" href="receive_8c-example.html#a35">receive.c</a>.</dd>
</dl>
</div>
</div>
-<a class="anchor" id="gaa44112980ebabbb5cbd002670073a751"></a>
+<a id="ga1dc327c52ac24a0d65a17c88ce685b0b"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#ga1dc327c52ac24a0d65a17c88ce685b0b">◆ </a></span>pn_link_detach()</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname">const char* pn_link_name </td>
+ <td class="memname">void pn_link_detach </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> * </td>
<td class="paramname"><em>link</em></td><td>)</td>
@@ -878,96 +922,82 @@ Functions</h2></td></tr>
</table>
</div><div class="memdoc">
-<p>Get the name of a link. </p>
+<p>Detach a link. </p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>a link object </td></tr>
</table>
</dd>
</dl>
-<dl class="section return"><dt>Returns</dt><dd>the name of the link </dd></dl>
</div>
</div>
-<a class="anchor" id="ga9b2a9cfa00dfdae4e01bf75483433925"></a>
+<a id="ga2c8985a9d44a813ab1739a91ae3708a3"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#ga2c8985a9d44a813ab1739a91ae3708a3">◆ </a></span>pn_link_source()</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a>* pn_link_next </td>
+ <td class="memname"><a class="el" href="group__terminus.html#gad202baf5c904d6991e13521b7c93fdc2">pn_terminus_t</a>* pn_link_source </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> * </td>
- <td class="paramname"><em>link</em>, </td>
- </tr>
- <tr>
- <td class="paramkey"></td>
- <td></td>
- <td class="paramtype"><a class="el" href="group__connection.html#gaa83193a655e32bffc18624acc2c39233">pn_state_t</a> </td>
- <td class="paramname"><em>state</em> </td>
- </tr>
- <tr>
+ <td class="paramname"><em>link</em></td><td>)</td>
<td></td>
- <td>)</td>
- <td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
-<p>Retrieve the next link that matches the given state mask. </p>
-<p>When used with pn_link_head, the application can access all links on the connection that match the given state. See pn_link_head for description of match behavior.</p>
+<p>Access the locally defined source definition for a link. </p>
+<p>The pointer returned by this operation is valid until the link object is freed.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
- <tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>the previous link obtained from pn_link_head or pn_link_next </td></tr>
- <tr><td class="paramdir">[in]</td><td class="paramname">state</td><td>mask to match </td></tr>
+ <tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>a link object </td></tr>
</table>
</dd>
</dl>
-<dl class="section return"><dt>Returns</dt><dd>the next session owned by the connection that matches the mask, else NULL if no sessions match </dd></dl>
-<dl><dt><b>Examples: </b></dt><dd><a class="el" href="broker_8c-example.html#a21">broker.c</a>.</dd>
+<dl class="section return"><dt>Returns</dt><dd>a pointer to a source terminus </dd></dl>
+<dl><dt><b>Examples: </b></dt><dd><a class="el" href="broker_8c-example.html#a17">broker.c</a>, and <a class="el" href="receive_8c-example.html#a22">receive.c</a>.</dd>
</dl>
</div>
</div>
-<a class="anchor" id="gaef3f2e4bca87f9adc70e90dce7cd42b2"></a>
+<a id="ga997c85388b9fb30151ea3b40b946e958"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#ga997c85388b9fb30151ea3b40b946e958">◆ </a></span>pn_link_target()</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname">void pn_link_offered </td>
+ <td class="memname"><a class="el" href="group__terminus.html#gad202baf5c904d6991e13521b7c93fdc2">pn_terminus_t</a>* pn_link_target </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> * </td>
- <td class="paramname"><em>sender</em>, </td>
- </tr>
- <tr>
- <td class="paramkey"></td>
- <td></td>
- <td class="paramtype">int </td>
- <td class="paramname"><em>credit</em> </td>
- </tr>
- <tr>
+ <td class="paramname"><em>link</em></td><td>)</td>
<td></td>
- <td>)</td>
- <td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
-<p>Signal the availability of deliveries for a link. </p>
+<p>Access the locally defined target definition for a link. </p>
+<p>The pointer returned by this operation is valid until the link object is freed.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
- <tr><td class="paramdir">[in]</td><td class="paramname">sender</td><td>a sender link object </td></tr>
- <tr><td class="paramdir">[in]</td><td class="paramname">credit</td><td>the number of deliveries potentially available for transfer </td></tr>
+ <tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>a link object </td></tr>
</table>
</dd>
</dl>
-
+<dl class="section return"><dt>Returns</dt><dd>a pointer to a target terminus </dd></dl>
+<dl><dt><b>Examples: </b></dt><dd><a class="el" href="broker_8c-example.html#a51">broker.c</a>, <a class="el" href="direct_8c-example.html#a49">direct.c</a>, and <a class="el" href="send_8c-example.html#a33">send.c</a>.</dd>
+</dl>
</div>
</div>
-<a class="anchor" id="gaabaca3f5d03970a122240eebc588add6"></a>
+<a id="gadf6b8ff6223465f21a481e9287f60671"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#gadf6b8ff6223465f21a481e9287f60671">◆ </a></span>pn_link_remote_source()</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname">void pn_link_open </td>
+ <td class="memname"><a class="el" href="group__terminus.html#gad202baf5c904d6991e13521b7c93fdc2">pn_terminus_t</a>* pn_link_remote_source </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> * </td>
<td class="paramname"><em>link</em></td><td>)</td>
@@ -976,24 +1006,27 @@ Functions</h2></td></tr>
</table>
</div><div class="memdoc">
-<p>Open a link. </p>
-<p>Once this operation has completed, the PN_LOCAL_ACTIVE state flag will be set.</p>
+<p>Access the remotely defined source definition for a link. </p>
+<p>The pointer returned by this operation is valid until the link object is freed. The remotely defined terminus will be empty until the link is remotely opened as indicated by the PN_REMOTE_ACTIVE flag.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>a link object </td></tr>
</table>
</dd>
</dl>
-<dl><dt><b>Examples: </b></dt><dd><a class="el" href="broker_8c-example.html#a55">broker.c</a>, <a class="el" href="receive_8c-example.html#a23">receive.c</a>, and <a class="el" href="send_8c-example.html#a41">send.c</a>.</dd>
+<dl class="section return"><dt>Returns</dt><dd>a pointer to the remotely defined source terminus </dd></dl>
+<dl><dt><b>Examples: </b></dt><dd><a class="el" href="broker_8c-example.html#a48">broker.c</a>.</dd>
</dl>
</div>
</div>
-<a class="anchor" id="ga57a00950e2eeef378fd6c0a3b3b5bfe9"></a>
+<a id="gabf61668a66ae189dbb4820da6ee30d90"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#gabf61668a66ae189dbb4820da6ee30d90">◆ </a></span>pn_link_remote_target()</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname">int pn_link_queued </td>
+ <td class="memname"><a class="el" href="group__terminus.html#gad202baf5c904d6991e13521b7c93fdc2">pn_terminus_t</a>* pn_link_remote_target </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> * </td>
<td class="paramname"><em>link</em></td><td>)</td>
@@ -1002,24 +1035,27 @@ Functions</h2></td></tr>
</table>
</div><div class="memdoc">
-<p>Get the number of queued deliveries for a link. </p>
-<p>Links may queue deliveries for a number of reasons, for example there may be insufficient credit to send them to the receiver (see <a class="el" href="group__link.html#ga55428637f3b8c446efd5fea3f26c932d" title="Get the credit balance for a link. ">pn_link_credit</a>), or they simply may not have yet had a chance to be written to the wire. This operation will return the number of queued deliveries on a link.</p>
+<p>Access the remotely defined target definition for a link. </p>
+<p>The pointer returned by this operation is valid until the link object is freed. The remotely defined terminus will be empty until the link is remotely opened as indicated by the PN_REMOTE_ACTIVE flag.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>a link object </td></tr>
</table>
</dd>
</dl>
-<dl class="section return"><dt>Returns</dt><dd>the number of queued deliveries for the link </dd></dl>
-
+<dl class="section return"><dt>Returns</dt><dd>a pointer to the remotely defined target terminus </dd></dl>
+<dl><dt><b>Examples: </b></dt><dd><a class="el" href="broker_8c-example.html#a50">broker.c</a>.</dd>
+</dl>
</div>
</div>
-<a class="anchor" id="ga0bc65ff494e2860e6227f68c72468101"></a>
+<a id="gad7e426b0cc4759568b3fd2b4fb176260"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#gad7e426b0cc4759568b3fd2b4fb176260">◆ </a></span>pn_link_current()</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname"><a class="el" href="group__link.html#gad1c2388cdae687be26222a5d66fd2d58">pn_rcv_settle_mode_t</a> pn_link_rcv_settle_mode </td>
+ <td class="memname"><a class="el" href="group__delivery.html#gacdfce854066c0a4ff4db9f9a0478f340">pn_delivery_t</a>* pn_link_current </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> * </td>
<td class="paramname"><em>link</em></td><td>)</td>
@@ -1028,69 +1064,57 @@ Functions</h2></td></tr>
</table>
</div><div class="memdoc">
-<p>Get the local receiver settle mode for a link. </p>
+<p>Get the current delivery for a link. </p>
+<p>Each link maintains a sequence of deliveries in the order they were created, along with a pointer to the <em>current</em> delivery. All send/recv operations on a link take place on the <em>current</em> delivery. If a link has no current delivery, the current delivery is automatically initialized to the next delivery created on the link. Once initialized, the current delivery remains the same until it is changed through use of <a class="el" href="group__link.html#ga93824a3859c37463e44458cd2f63d31f" title="Advance the current delivery of a link to the next delivery on the link. ">pn_link_advance</a> or until it is settled via <a class="el" href="group__delivery.html#ga98c275fd7158e8b9d7d48d70503d68df" title="Settle a delivery. ">pn_delivery_settle</a>.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>a link object </td></tr>
</table>
</dd>
</dl>
-<dl class="section return"><dt>Returns</dt><dd>the local receiver settle mode </dd></dl>
+<dl class="section return"><dt>Returns</dt><dd>the current delivery for the link, or NULL if there is none </dd></dl>
</div>
</div>
-<a class="anchor" id="ga06c97ce7396973dca0d311567f25f95a"></a>
+<a id="ga93824a3859c37463e44458cd2f63d31f"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#ga93824a3859c37463e44458cd2f63d31f">◆ </a></span>pn_link_advance()</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname">ssize_t pn_link_recv </td>
+ <td class="memname">bool pn_link_advance </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> * </td>
- <td class="paramname"><em>receiver</em>, </td>
- </tr>
- <tr>
- <td class="paramkey"></td>
- <td></td>
- <td class="paramtype">char * </td>
- <td class="paramname"><em>bytes</em>, </td>
- </tr>
- <tr>
- <td class="paramkey"></td>
- <td></td>
- <td class="paramtype">size_t </td>
- <td class="paramname"><em>n</em> </td>
- </tr>
- <tr>
+ <td class="paramname"><em>link</em></td><td>)</td>
<td></td>
- <td>)</td>
- <td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
-<p>Receive message data for the current delivery on a link. </p>
-<p>Use <a class="el" href="group__delivery.html#ga17523835dbc8d1906bd71df69d09cc40" title="Get the amount of pending message data for a delivery. ">pn_delivery_pending</a> on the current delivery to figure out how much buffer space is needed.</p>
-<p>Note that the link API can be used to stream large messages across the network, so just because there is no data to read does not imply the message is complete. To ensure the entirety of the message data has been read, either invoke <a class="el" href="group__link.html#ga06c97ce7396973dca0d311567f25f95a" title="Receive message data for the current delivery on a link. ">pn_link_recv</a> until PN_EOS is returned, or verify that <a class="el" href="group__delivery.html#ga23c7b3c678228ccb21378e7c8ec9a72d" title="Check if a delivery only has partial message data. ">pn_delivery_partial</a> is false, and <a class="el" href="group__delivery.html#ga17523835dbc8d1906bd71df69d09cc40" title="Get the amount of pending message data for a delivery. ">pn_delivery_pending</a> is 0.</p>
+<p>Advance the current delivery of a link to the next delivery on the link. </p>
+<p>For sending links this operation is used to finish sending message data for the current outgoing delivery and move on to the next outgoing delivery (if any).</p>
+<p>For receiving links, this operation is used to finish accessing message data from the current incoming delivery and move on to the next incoming delivery (if any).</p>
+<p>Each link maintains a sequence of deliveries in the order they were created, along with a pointer to the <em>current</em> delivery. The pn_link_advance operation will modify the <em>current</em> delivery on the link to point to the next delivery in the sequence. If there is no next delivery in the sequence, the current delivery will be set to NULL. This operation will return true if invoking it caused the value of the current delivery to change, even if it was set to NULL.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
- <tr><td class="paramdir">[in]</td><td class="paramname">receiver</td><td>a receiving link object </td></tr>
- <tr><td class="paramdir">[in]</td><td class="paramname">bytes</td><td>a pointer to an empty buffer </td></tr>
- <tr><td class="paramdir">[in]</td><td class="paramname">n</td><td>the buffer capacity </td></tr>
+ <tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>a link object </td></tr>
</table>
</dd>
</dl>
-<dl class="section return"><dt>Returns</dt><dd>the number of bytes received, PN_EOS, or an error code </dd></dl>
-<dl><dt><b>Examples: </b></dt><dd><a class="el" href="broker_8c-example.html#a64">broker.c</a>, and <a class="el" href="receive_8c-example.html#a7">receive.c</a>.</dd>
+<dl class="section return"><dt>Returns</dt><dd>true if the current delivery was changed </dd></dl>
+<dl><dt><b>Examples: </b></dt><dd><a class="el" href="broker_8c-example.html#a8">broker.c</a>, <a class="el" href="direct_8c-example.html#a41">direct.c</a>, <a class="el" href="receive_8c-example.html#a31">receive.c</a>, and <a class="el" href="send_8c-example.html#a43">send.c</a>.</dd>
</dl>
</div>
</div>
-<a class="anchor" id="ga97dc5133125c9b7e4afbb1b76e6efe7b"></a>
+<a id="ga55428637f3b8c446efd5fea3f26c932d"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#ga55428637f3b8c446efd5fea3f26c932d">◆ </a></span>pn_link_credit()</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname"><a class="el" href="group__condition.html#ga11eb7db7d2c205169fe3d47c996a95a5">pn_condition_t</a>* pn_link_remote_condition </td>
+ <td class="memname">int pn_link_credit </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> * </td>
<td class="paramname"><em>link</em></td><td>)</td>
@@ -1099,26 +1123,28 @@ Functions</h2></td></tr>
</table>
</div><div class="memdoc">
-<p>Get the remote condition associated with a link endpoint. </p>
-<p>The <a class="el" href="group__condition.html#ga11eb7db7d2c205169fe3d47c996a95a5" title="An AMQP Condition object. ">pn_condition_t</a> object retrieved may be examined in order to determine whether the remote peer was indicating some sort of exceptional condition when the remote link endpoint was closed. The <a class="el" href="group__condition.html#ga11eb7db7d2c205169fe3d47c996a95a5" title="An AMQP Condition object. ">pn_condition_t</a> object returned may not be modified.</p>
-<p>The pointer returned by this operation is valid until the link object is freed.</p>
+<p>Get the credit balance for a link. </p>
+<p>Links use a credit based flow control scheme. Every receiver maintains a credit balance that corresponds to the number of deliveries that the receiver can accept at any given moment. As more capacity becomes available at the receiver (see <a class="el" href="group__link.html#gafec44cf1c79ec03f3ac009e1879e71a9" title="Grant credit for incoming deliveries on a receiver. ">pn_link_flow</a>), it adds credit to this balance and communicates the new balance to the sender. Whenever a delivery is sent/received, the credit balance maintained by the link is decremented by one. Once the credit balance at the sender reaches zero, the sender must pause sending until more credit is obtained from the receiver.</p>
+<p>Note that a sending link may still be used to send deliveries even if pn_link_credit reaches zero, however those deliveries will end up being buffered by the link until enough credit is obtained from the receiver to send them over the wire. In this case the balance reported by <a class="el" href="group__link.html#ga55428637f3b8c446efd5fea3f26c932d" title="Get the credit balance for a link. ">pn_link_credit</a> will go negative.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
- <tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>the link object </td></tr>
+ <tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>a link object </td></tr>
</table>
</dd>
</dl>
-<dl class="section return"><dt>Returns</dt><dd>the link's remote condition object </dd></dl>
-<dl><dt><b>Examples: </b></dt><dd><a class="el" href="broker_8c-example.html#a78">broker.c</a>, <a class="el" href="receive_8c-example.html#a49">receive.c</a>, and <a class="el" href="send_8c-example.html#a64">send.c</a>.</dd>
+<dl class="section return"><dt>Returns</dt><dd>the credit balance for the link </dd></dl>
+<dl><dt><b>Examples: </b></dt><dd><a class="el" href="broker_8c-example.html#a15">broker.c</a>, <a class="el" href="direct_8c-example.html#a43">direct.c</a>, <a class="el" href="receive_8c-example.html#a33">receive.c</a>, and <a class="el" href="send_8c-example.html#a37">send.c</a>.</dd>
</dl>
</div>
</div>
-<a class="anchor" id="gab16f14d071548c5c9ab22924ee5b1ebb"></a>
+<a id="ga57a00950e2eeef378fd6c0a3b3b5bfe9"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#ga57a00950e2eeef378fd6c0a3b3b5bfe9">◆ </a></span>pn_link_queued()</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname">int pn_link_remote_credit </td>
+ <td class="memname">int pn_link_queued </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> * </td>
<td class="paramname"><em>link</em></td><td>)</td>
@@ -1127,24 +1153,26 @@ Functions</h2></td></tr>
</table>
</div><div class="memdoc">
-<p>Get the remote view of the credit for a link. </p>
-<p>The remote view of the credit for a link differs from local view of credit for a link by the number of queued deliveries. In other words <a class="el" href="group__link.html#gab16f14d071548c5c9ab22924ee5b1ebb" title="Get the remote view of the credit for a link. ">pn_link_remote_credit</a> is defined to be <a class="el" href="group__link.html#ga55428637f3b8c446efd5fea3f26c932d" title="Get the credit balance for a link. ">pn_link_credit</a> - <a class="el" href="group__link.html#ga57a00950e2eeef378fd6c0a3b3b5bfe9" title="Get the number of queued deliveries for a link. ">pn_link_queued</a>.</p>
+<p>Get the number of queued deliveries for a link. </p>
+<p>Links may queue deliveries for a number of reasons, for example there may be insufficient credit to send them to the receiver (see <a class="el" href="group__link.html#ga55428637f3b8c446efd5fea3f26c932d" title="Get the credit balance for a link. ">pn_link_credit</a>), or they simply may not have yet had a chance to be written to the wire. This operation will return the number of queued deliveries on a link.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>a link object </td></tr>
</table>
</dd>
</dl>
-<dl class="section return"><dt>Returns</dt><dd>the remote view of the credit for a link </dd></dl>
+<dl class="section return"><dt>Returns</dt><dd>the number of queued deliveries for the link </dd></dl>
</div>
</div>
-<a class="anchor" id="ga378e4bb5a0519a75c3c151c15809dda5"></a>
+<a id="gab16f14d071548c5c9ab22924ee5b1ebb"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#gab16f14d071548c5c9ab22924ee5b1ebb">◆ </a></span>pn_link_remote_credit()</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname"><a class="el" href="group__link.html#gad1c2388cdae687be26222a5d66fd2d58">pn_rcv_settle_mode_t</a> pn_link_remote_rcv_settle_mode </td>
+ <td class="memname">int pn_link_remote_credit </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> * </td>
<td class="paramname"><em>link</em></td><td>)</td>
@@ -1153,23 +1181,26 @@ Functions</h2></td></tr>
</table>
</div><div class="memdoc">
-<p>Get the remote receiver settle mode for a link. </p>
+<p>Get the remote view of the credit for a link. </p>
+<p>The remote view of the credit for a link differs from local view of credit for a link by the number of queued deliveries. In other words <a class="el" href="group__link.html#gab16f14d071548c5c9ab22924ee5b1ebb" title="Get the remote view of the credit for a link. ">pn_link_remote_credit</a> is defined to be <a class="el" href="group__link.html#ga55428637f3b8c446efd5fea3f26c932d" title="Get the credit balance for a link. ">pn_link_credit</a> - <a class="el" href="group__link.html#ga57a00950e2eeef378fd6c0a3b3b5bfe9" title="Get the number of queued deliveries for a link. ">pn_link_queued</a>.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>a link object </td></tr>
</table>
</dd>
</dl>
-<dl class="section return"><dt>Returns</dt><dd>the remote receiver settle mode </dd></dl>
+<dl class="section return"><dt>Returns</dt><dd>the remote view of the credit for a link </dd></dl>
</div>
</div>
-<a class="anchor" id="ga92592155f2afcf6b9aabfb4fc64c140f"></a>
+<a id="ga40dd26f3d035c54056e2649aeb78d8ac"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#ga40dd26f3d035c54056e2649aeb78d8ac">◆ </a></span>pn_link_get_drain()</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname"><a class="el" href="group__link.html#ga3fb58bd0b88d37407ebb615c2630e608">pn_snd_settle_mode_t</a> pn_link_remote_snd_settle_mode </td>
+ <td class="memname">bool pn_link_get_drain </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> * </td>
<td class="paramname"><em>link</em></td><td>)</td>
@@ -1178,23 +1209,26 @@ Functions</h2></td></tr>
</table>
</div><div class="memdoc">
-<p>Get the remote sender settle mode for a link. </p>
+<p>Get the drain flag for a link. </p>
+<p>If a link is in drain mode, then the sending endpoint of a link must immediately use up all available credit on the link. If this is not possible, the excess credit must be returned by invoking <a class="el" href="group__link.html#ga95c4018a1f1fe0e7c2e7fd02fe062d23" title="Drain excess credit for a link. ">pn_link_drained</a>. Only the receiving endpoint can set the drain mode. See <a class="el" href="group__link.html#gaeb417e6b7e99c76f61549f5ed5519395" title="Set the drain mode on a link. ">pn_link_set_drain</a> for details.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>a link object </td></tr>
</table>
</dd>
</dl>
-<dl class="section return"><dt>Returns</dt><dd>the remote sender settle mode </dd></dl>
+<dl class="section return"><dt>Returns</dt><dd>true if and only if the link is in drain mode </dd></dl>
</div>
</div>
-<a class="anchor" id="gadf6b8ff6223465f21a481e9287f60671"></a>
+<a id="ga95c4018a1f1fe0e7c2e7fd02fe062d23"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#ga95c4018a1f1fe0e7c2e7fd02fe062d23">◆ </a></span>pn_link_drained()</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname"><a class="el" href="group__terminus.html#gad202baf5c904d6991e13521b7c93fdc2">pn_terminus_t</a>* pn_link_remote_source </td>
+ <td class="memname">int pn_link_drained </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> * </td>
<td class="paramname"><em>link</em></td><td>)</td>
@@ -1203,25 +1237,28 @@ Functions</h2></td></tr>
</table>
</div><div class="memdoc">
-<p>Access the remotely defined source definition for a link. </p>
-<p>The pointer returned by this operation is valid until the link object is freed. The remotely defined terminus will be empty until the link is remotely opened as indicated by the PN_REMOTE_ACTIVE flag.</p>
+<p>Drain excess credit for a link. </p>
+<p>When a link is in drain mode, the sender must use all excess credit immediately, and release any excess credit back to the receiver if there are no deliveries available to send.</p>
+<p>When invoked on a sending link that is in drain mode, this operation will release all excess credit back to the receiver and return the number of credits released back to the sender. If the link is not in drain mode, this operation is a noop.</p>
+<p>When invoked on a receiving link, this operation will return and reset the number of credits the sender has released back to the receiver.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>a link object </td></tr>
</table>
</dd>
</dl>
-<dl class="section return"><dt>Returns</dt><dd>a pointer to the remotely defined source terminus </dd></dl>
-<dl><dt><b>Examples: </b></dt><dd><a class="el" href="broker_8c-example.html#a50">broker.c</a>.</dd>
-</dl>
+<dl class="section return"><dt>Returns</dt><dd>the number of credits drained </dd></dl>
+
</div>
</div>
-<a class="anchor" id="gabf61668a66ae189dbb4820da6ee30d90"></a>
+<a id="ga7f1742528b32c3c9609b97a3ed449639"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#ga7f1742528b32c3c9609b97a3ed449639">◆ </a></span>pn_link_available()</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname"><a class="el" href="group__terminus.html#gad202baf5c904d6991e13521b7c93fdc2">pn_terminus_t</a>* pn_link_remote_target </td>
+ <td class="memname">int pn_link_available </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> * </td>
<td class="paramname"><em>link</em></td><td>)</td>
@@ -1230,69 +1267,53 @@ Functions</h2></td></tr>
</table>
</div><div class="memdoc">
-<p>Access the remotely defined target definition for a link. </p>
-<p>The pointer returned by this operation is valid until the link object is freed. The remotely defined terminus will be empty until the link is remotely opened as indicated by the PN_REMOTE_ACTIVE flag.</p>
+<p>Get the available deliveries hint for a link. </p>
+<p>The available count for a link provides a hint as to the number of deliveries that might be able to be sent if sufficient credit were issued by the receiving link endpoint. See <a class="el" href="group__link.html#gaef3f2e4bca87f9adc70e90dce7cd42b2" title="Signal the availability of deliveries for a link. ">pn_link_offered</a> for more details.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>a link object </td></tr>
</table>
</dd>
</dl>
-<dl class="section return"><dt>Returns</dt><dd>a pointer to the remotely defined target terminus </dd></dl>
-<dl><dt><b>Examples: </b></dt><dd><a class="el" href="broker_8c-example.html#a52">broker.c</a>.</dd>
-</dl>
+<dl class="section return"><dt>Returns</dt><dd>the available deliveries hint </dd></dl>
+
</div>
</div>
-<a class="anchor" id="gaa825fac21730f3f9fff37d156e5f88e9"></a>
+<a id="gacef130ca5cc6eb3eec2dd48c8bf5c7e6"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#gacef130ca5cc6eb3eec2dd48c8bf5c7e6">◆ </a></span>pn_link_snd_settle_mode()</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname">ssize_t pn_link_send </td>
+ <td class="memname"><a class="el" href="group__link.html#ga3fb58bd0b88d37407ebb615c2630e608">pn_snd_settle_mode_t</a> pn_link_snd_settle_mode </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> * </td>
- <td class="paramname"><em>sender</em>, </td>
- </tr>
- <tr>
- <td class="paramkey"></td>
- <td></td>
- <td class="paramtype">const char * </td>
- <td class="paramname"><em>bytes</em>, </td>
- </tr>
- <tr>
- <td class="paramkey"></td>
- <td></td>
- <td class="paramtype">size_t </td>
- <td class="paramname"><em>n</em> </td>
- </tr>
- <tr>
- <td></td>
- <td>)</td>
- <td></td><td></td>
+ <td class="paramname"><em>link</em></td><td>)</td>
+ <td></td>
</tr>
</table>
</div><div class="memdoc">
-<p>Send message data for the current delivery on a link. </p>
+<p>Get the local sender settle mode for a link. </p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
- <tr><td class="paramdir">[in]</td><td class="paramname">sender</td><td>a sender link object </td></tr>
- <tr><td class="paramdir">[in]</td><td class="paramname">bytes</td><td>the start of the message data </td></tr>
- <tr><td class="paramdir">[in]</td><td class="paramname">n</td><td>the number of bytes of message data </td></tr>
+ <tr><td class="paramdir">[in]</td><td class="paramname">link</td><td>a link object </td></tr>
</table>
</dd>
</dl>
-<dl class="section return"><dt>Returns</dt><dd>the number of bytes sent, or an error code </dd></dl>
-<dl><dt><b>Examples: </b></dt><dd><a class="el" href="broker_8c-example.html#a7">broker.c</a>, and <a class="el" href="send_8c-example.html#a27">send.c</a>.</dd>
-</dl>
+<dl class="section return"><dt>Returns</dt><dd>the local sender settle mode </dd></dl>
+
</div>
</div>
-<a class="anchor" id="gac63e43305fb1a5e3b14399a9ddc8f24d"></a>
+<a id="ga0bc65ff494e2860e6227f68c72468101"></a>
+<h2 class="memtitle"><span class="permalink"><a href="#ga0bc65ff494e2860e6227f68c72468101">◆ </a></span>pn_link_rcv_settle_mode()</h2>
+
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
- <td class="memname"><a class="el" href="group__session.html#ga38ccb93b8f5c2892adafce5d5f0fbcd9">pn_session_t</a>* pn_link_session </td>
+ <td class="memname"><a class="el" href="group__link.html#gad1c2388cdae687be26222a5d66fd2d58">pn_rcv_settle_mode_t</a> pn_link_rcv_settle_mode </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__link.html#ga89dad3aa7934329a7ff467c636687bc0">pn_link_t</a> * </td>
<td class="paramname"><em>link</em></td><td>)</td>
@@ -1301,25 +1322,25 @@ Functions</h2></td></tr>
</table>
</div><div class="memdoc">
-<p>Get the parent session f
<TRUNCATED>
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org