input/releases/qpid-proton-0.32.0/proton/cpp/api/overview_page.html - qpid-site - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml">
 <head>
 <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
 <meta http-equiv="X-UA-Compatible" content="IE=9"/>
 <meta name="generator" content="Doxygen 1.8.20"/>
 <meta name="viewport" content="width=device-width, initial-scale=1"/>
 <title>Qpid Proton C++ API: Overview</title>
 <link href="tabs.css" rel="stylesheet" type="text/css"/>
 <script type="text/javascript" src="jquery.js"></script>
 <script type="text/javascript" src="dynsections.js"></script>
 <link href="navtree.css" rel="stylesheet" type="text/css"/>
 <script type="text/javascript" src="resize.js"></script>
 <script type="text/javascript" src="navtreedata.js"></script>
 <script type="text/javascript" src="navtree.js"></script>
 <link href="search/search.css" rel="stylesheet" type="text/css"/>
 <script type="text/javascript" src="search/searchdata.js"></script>
 <script type="text/javascript" src="search/search.js"></script>
 <script type="text/javascript">
 /* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
   $(document).ready(function() { init_search(); });
 /* @license-end */
 </script>
 <link href="doxygen.css" rel="stylesheet" type="text/css" />
 </head>
 <body>
 <div id="top"><!-- do not remove this div, it is closed by doxygen! -->
 <div id="titlearea">
 <table cellspacing="0" cellpadding="0">
  <tbody>
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">Qpid Proton C++ API
    &#160;<span id="projectnumber">0.32.0</span>
    </div>
   </td>
    <td>        <div id="MSearchBox" class="MSearchBoxInactive">
         <span class="left">
           <img id="MSearchSelect" src="search/mag_sel.svg"
                onmouseover="return searchBox.OnSearchSelectShow()"
                onmouseout="return searchBox.OnSearchSelectHide()"
                alt=""/>
           <input type="text" id="MSearchField" value="Search" accesskey="S"
                onfocus="searchBox.OnSearchFieldFocus(true)"
                onblur="searchBox.OnSearchFieldFocus(false)"
                onkeyup="searchBox.OnSearchFieldChange(event)"/>
           </span><span class="right">
             <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a>
           </span>
         </div>
 </td>
  </tr>
  </tbody>
 </table>
 </div>
 <!-- end header part -->
 <!-- Generated by Doxygen 1.8.20 -->
 <script type="text/javascript">
 /* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
 var searchBox = new SearchBox("searchBox", "search",false,'Search');
 /* @license-end */
 </script>
 </div><!-- top -->
 <div id="side-nav" class="ui-resizable side-nav-resizable">
   <div id="nav-tree">
     <div id="nav-tree-contents">
       <div id="nav-sync" class="sync"></div>
     </div>
   </div>
   <div id="splitbar" style="-moz-user-select:none;"
        class="ui-resizable-handle">
   </div>
 </div>
 <script type="text/javascript">
 /* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
 $(document).ready(function(){initNavTree('overview_page.html',''); initResizable(); });
 /* @license-end */
 </script>
 <div id="doc-content">
 <!-- window showing the filter options -->
 <div id="MSearchSelectWindow"
      onmouseover="return searchBox.OnSearchSelectShow()"
      onmouseout="return searchBox.OnSearchSelectHide()"
      onkeydown="return searchBox.OnSearchSelectKey(event)">
 </div>

 <!-- iframe showing the search results (closed by default) -->
 <div id="MSearchResultsWindow">
 <iframe src="javascript:void(0)" frameborder="0"
         name="MSearchResults" id="MSearchResults">
 </iframe>
 </div>

 <div class="PageDoc"><div class="header">
   <div class="headertitle">
 <div class="title">Overview </div>  </div>
 </div><!--header-->
 <div class="contents">
 <div class="textblock"><p><a class="anchor" id="md__tmp_rgemmell_transom_qpid-proton-0"></a>.32.0_cpp_docs_overview</p>
 <p>Qpid Proton's concepts and capabilities closely match those of its wire protocol, AMQP. See <a href="https://qpid.apache.org/amqp/index.html">the Qpid AMQP page</a> and <a href="http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-overview-v1.0-os.html">the AMQP 1.0 spec</a> for more information.</p>
 <h1><a class="anchor" id="autotoc_md8"></a>
 Key concepts</h1>
 <p>A <code><a class="el" href="classproton_1_1message.html" title="An AMQP message.">proton::message</a></code> has a <em>body</em> (the main content), application properties where you can store additional data, and specific properties defined by AMQP.</p>
 <p>Messages are transferred over <em>links</em>. The sending end of a link is a <code><a class="el" href="classproton_1_1sender.html" title="A channel for sending messages.">proton::sender</a></code>, and the receiving end is a <code><a class="el" href="classproton_1_1receiver.html" title="A channel for receiving messages.">proton::receiver</a></code>. Links have a <em>source</em> and <em>target</em> address, as explained <a href="#sources-and-targets">below</a>.</p>
 <p>Links are grouped in a <code><a class="el" href="classproton_1_1session.html" title="A container of senders and receivers.">proton::session</a></code>. Messages in the same session are sent sequentially, while those on different sessions can be interleaved. A large message being sent on one session does not block messages being sent on another session.</p>
 <p>Sessions belong to a <code><a class="el" href="classproton_1_1connection.html" title="A connection to a remote AMQP peer.">proton::connection</a></code>. If you don't need multiple sessions, a connection will create links directly using a default session.</p>
 <p>A <code><a class="el" href="classproton_1_1delivery.html" title="A received message.">proton::delivery</a></code> represents the transfer of a message and allows the receiver to accept or reject it. The sender can use a <code><a class="el" href="classproton_1_1tracker.html" title="A tracker for a sent message.">proton::tracker</a></code> to track the status of a sent message and find out if it was accepted.</p>
 <p>A delivery is <em>settled</em> when both ends are done with it. Different settlement methods give different levels of reliability: <em>at-most-once</em>, <em>at-least-once</em>, and <em>exactly-once</em>. See <a href="#delivery-guarantees">below</a>.</p>
 <h1><a class="anchor" id="autotoc_md9"></a>
 The anatomy of a Proton application</h1>
 <p><code><a class="el" href="classproton_1_1container.html" title="A top-level container of connections, sessions, and links.">proton::container</a></code> is the top-level object in a Proton application. A client uses <code><a class="el" href="classproton_1_1container.html#a32d867e171bce707cc73c7003ec489db" title="Connect using the default Connection Configuration file.">proton::container::connect()</a></code> to establish connections. A server uses <code><a class="el" href="classproton_1_1container.html#a9e138b28e9589583915cf5c5e0e7a524" title="Listen for new connections on listen_url.">proton::container::listen()</a></code> to accept connections.</p>
 <p>Proton is an event-driven API. You implement a subclass of <code><a class="el" href="classproton_1_1messaging__handler.html" title="Handler for Proton messaging events.">proton::messaging_handler</a></code> and override functions to handle AMQP events, such as <code>on_container_open()</code> or <code>on_message()</code>. Each connection is associated with a handler for its events. <code><a class="el" href="classproton_1_1container.html#a13a43e6d814de94978c515cb084873b1" title="Run the container in the current thread.">proton::container::run()</a></code> polls all connections and listeners and dispatches events to your handlers.</p>
 <p>A message body can be a string or byte sequence encoded any way you like. However, AMQP also provides standard, interoperable encodings for basic data types and structures such as maps and lists. You can use this encoding for your message bodies via <code><a class="el" href="classproton_1_1value.html" title="A holder for any AMQP value, simple or complex.">proton::value</a></code> and <code><a class="el" href="classproton_1_1scalar.html" title="A holder for an instance of any scalar AMQP type.">proton::scalar</a></code>, which convert C++ types to their AMQP equivalents.</p>
 <h1><a class="anchor" id="autotoc_md10"></a>
 Sources and targets</h1>
 <p>Every link has two addresses, <em>source</em> and <em>target</em>. The most common pattern for using these addresses is as follows.</p>
 <p>When a client creates a <em>receiver</em> link, it sets the <em>source</em> address. This means "I want to receive messages from this
 source". This is often referred to as "subscribing" to the source. When a client creates a <em>sender</em> link, it sets the <em>target</em> address. This means "I want to send to this target".</p>
 <p>In the case of a broker, the source or target usually refers to a queue or topic. In general they can refer to any AMQP-capable node.</p>
 <p>In the <em>request-response</em> pattern, a request message carries a <em>reply-to</em> address for the response message. This can be any AMQP address, but it is often useful to create a temporary address for the response message. The client creates a <em>receiver</em> with no source address and the <em>dynamic</em> flag set. The server generates a unique <em>source</em> address for the receiver, which is discarded when the link closes. The client uses this source address as the reply-to when it sends the request, so the response is delivered to the client's receiver.</p>
 <p>The <a class="el" href="server_direct_8cpp-example.html">server_direct.cpp</a> example shows how to implement a request-response server.</p>
 <h1><a class="anchor" id="autotoc_md11"></a>
 Delivery guarantees</h1>
 <p>Proton offers three levels of message delivery guarantee: <em>at-most-once</em>, <em>at-least-once</em>, and <em>exactly-once</em>.</p>
 <p>For <em>at-most-once</em>, the sender settles the message as soon as it sends it. If the connection is lost before the message is received by the receiver, the message will not be delivered.</p>
 <p>For <em>at-least-once</em>, the receiver accepts and settles the message on receipt. If the connection is lost before the sender is informed of the settlement, then the delivery is considered in-doubt and should be retried. This will ensure it eventually gets delivered (provided of course the connection and link can be reestablished). It may mean that it is delivered multiple times, however.</p>
 <p>Finally, for <em>exactly-once</em>, the receiver accepts the message but doesn't settle it. The sender settles once it is aware that the receiver accepted it. In this way the receiver retains knowledge of an accepted message until it is sure the sender knows it has been accepted. If the connection is lost before settlement, the receiver informs the sender of all the unsettled deliveries it knows about, and from this the sender can deduce which need to be redelivered. The sender likewise informs the receiver which deliveries it knows about, from which the receiver can deduce which have already been settled.</p>
 </div></div><!-- contents -->
 </div><!-- PageDoc -->
 </div><!-- doc-content -->
 <!-- start footer part -->
 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
   <ul>
     <li class="footer">Generated by <a href="http://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.8.20 </li>
   </ul>
 </div>
 </body>
 </html>
	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
	<meta http-equiv="X-UA-Compatible" content="IE=9"/>
	<meta name="generator" content="Doxygen 1.8.20"/>
	<meta name="viewport" content="width=device-width, initial-scale=1"/>
	<title>Qpid Proton C++ API: Overview</title>
	<link href="tabs.css" rel="stylesheet" type="text/css"/>
	<script type="text/javascript" src="jquery.js"></script>
	<script type="text/javascript" src="dynsections.js"></script>
	<link href="navtree.css" rel="stylesheet" type="text/css"/>
	<script type="text/javascript" src="resize.js"></script>
	<script type="text/javascript" src="navtreedata.js"></script>
	<script type="text/javascript" src="navtree.js"></script>
	<link href="search/search.css" rel="stylesheet" type="text/css"/>
	<script type="text/javascript" src="search/searchdata.js"></script>
	<script type="text/javascript" src="search/search.js"></script>
	<script type="text/javascript">
	/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
	$(document).ready(function() { init_search(); });
	/* @license-end */
	</script>
	<link href="doxygen.css" rel="stylesheet" type="text/css" />
	</head>
	<body>
	<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
	<div id="titlearea">
	<table cellspacing="0" cellpadding="0">
	<tbody>
	<tr style="height: 56px;">
	<td id="projectalign" style="padding-left: 0.5em;">
	<div id="projectname">Qpid Proton C++ API
	<span id="projectnumber">0.32.0</span>
	</div>
	</td>
	<td> <div id="MSearchBox" class="MSearchBoxInactive">
	<span class="left">
	<img id="MSearchSelect" src="search/mag_sel.svg"
	onmouseover="return searchBox.OnSearchSelectShow()"
	onmouseout="return searchBox.OnSearchSelectHide()"
	alt=""/>
	<input type="text" id="MSearchField" value="Search" accesskey="S"
	onfocus="searchBox.OnSearchFieldFocus(true)"
	onblur="searchBox.OnSearchFieldFocus(false)"
	onkeyup="searchBox.OnSearchFieldChange(event)"/>
	</span><span class="right">
	<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a>
	</span>
	</div>
	</td>
	</tr>
	</tbody>
	</table>
	</div>
	<!-- end header part -->
	<!-- Generated by Doxygen 1.8.20 -->
	<script type="text/javascript">
	/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
	var searchBox = new SearchBox("searchBox", "search",false,'Search');
	/* @license-end */
	</script>
	</div><!-- top -->
	<div id="side-nav" class="ui-resizable side-nav-resizable">
	<div id="nav-tree">
	<div id="nav-tree-contents">
	<div id="nav-sync" class="sync"></div>
	</div>
	</div>
	<div id="splitbar" style="-moz-user-select:none;"
	class="ui-resizable-handle">
	</div>
	</div>
	<script type="text/javascript">
	/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
	$(document).ready(function(){initNavTree('overview_page.html',''); initResizable(); });
	/* @license-end */
	</script>
	<div id="doc-content">
	<!-- window showing the filter options -->
	<div id="MSearchSelectWindow"
	onmouseover="return searchBox.OnSearchSelectShow()"
	onmouseout="return searchBox.OnSearchSelectHide()"
	onkeydown="return searchBox.OnSearchSelectKey(event)">
	</div>

	<!-- iframe showing the search results (closed by default) -->
	<div id="MSearchResultsWindow">
	<iframe src="javascript:void(0)" frameborder="0"
	name="MSearchResults" id="MSearchResults">
	</iframe>
	</div>

	<div class="PageDoc"><div class="header">
	<div class="headertitle">
	<div class="title">Overview </div> </div>
	</div><!--header-->
	<div class="contents">
	<div class="textblock"><p><a class="anchor" id="md__tmp_rgemmell_transom_qpid-proton-0"></a>.32.0_cpp_docs_overview</p>
	<p>Qpid Proton's concepts and capabilities closely match those of its wire protocol, AMQP. See <a href="https://qpid.apache.org/amqp/index.html">the Qpid AMQP page</a> and <a href="http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-overview-v1.0-os.html">the AMQP 1.0 spec</a> for more information.</p>
	<h1><a class="anchor" id="autotoc_md8"></a>
	Key concepts</h1>
	<p>A <code><a class="el" href="classproton_1_1message.html" title="An AMQP message.">proton::message</a></code> has a <em>body</em> (the main content), application properties where you can store additional data, and specific properties defined by AMQP.</p>
	<p>Messages are transferred over <em>links</em>. The sending end of a link is a <code><a class="el" href="classproton_1_1sender.html" title="A channel for sending messages.">proton::sender</a></code>, and the receiving end is a <code><a class="el" href="classproton_1_1receiver.html" title="A channel for receiving messages.">proton::receiver</a></code>. Links have a <em>source</em> and <em>target</em> address, as explained <a href="#sources-and-targets">below</a>.</p>
	<p>Links are grouped in a <code><a class="el" href="classproton_1_1session.html" title="A container of senders and receivers.">proton::session</a></code>. Messages in the same session are sent sequentially, while those on different sessions can be interleaved. A large message being sent on one session does not block messages being sent on another session.</p>
	<p>Sessions belong to a <code><a class="el" href="classproton_1_1connection.html" title="A connection to a remote AMQP peer.">proton::connection</a></code>. If you don't need multiple sessions, a connection will create links directly using a default session.</p>
	<p>A <code><a class="el" href="classproton_1_1delivery.html" title="A received message.">proton::delivery</a></code> represents the transfer of a message and allows the receiver to accept or reject it. The sender can use a <code><a class="el" href="classproton_1_1tracker.html" title="A tracker for a sent message.">proton::tracker</a></code> to track the status of a sent message and find out if it was accepted.</p>
	<p>A delivery is <em>settled</em> when both ends are done with it. Different settlement methods give different levels of reliability: <em>at-most-once</em>, <em>at-least-once</em>, and <em>exactly-once</em>. See <a href="#delivery-guarantees">below</a>.</p>
	<h1><a class="anchor" id="autotoc_md9"></a>
	The anatomy of a Proton application</h1>
	<p><code><a class="el" href="classproton_1_1container.html" title="A top-level container of connections, sessions, and links.">proton::container</a></code> is the top-level object in a Proton application. A client uses <code><a class="el" href="classproton_1_1container.html#a32d867e171bce707cc73c7003ec489db" title="Connect using the default Connection Configuration file.">proton::container::connect()</a></code> to establish connections. A server uses <code><a class="el" href="classproton_1_1container.html#a9e138b28e9589583915cf5c5e0e7a524" title="Listen for new connections on listen_url.">proton::container::listen()</a></code> to accept connections.</p>
	<p>Proton is an event-driven API. You implement a subclass of <code><a class="el" href="classproton_1_1messaging__handler.html" title="Handler for Proton messaging events.">proton::messaging_handler</a></code> and override functions to handle AMQP events, such as <code>on_container_open()</code> or <code>on_message()</code>. Each connection is associated with a handler for its events. <code><a class="el" href="classproton_1_1container.html#a13a43e6d814de94978c515cb084873b1" title="Run the container in the current thread.">proton::container::run()</a></code> polls all connections and listeners and dispatches events to your handlers.</p>
	<p>A message body can be a string or byte sequence encoded any way you like. However, AMQP also provides standard, interoperable encodings for basic data types and structures such as maps and lists. You can use this encoding for your message bodies via <code><a class="el" href="classproton_1_1value.html" title="A holder for any AMQP value, simple or complex.">proton::value</a></code> and <code><a class="el" href="classproton_1_1scalar.html" title="A holder for an instance of any scalar AMQP type.">proton::scalar</a></code>, which convert C++ types to their AMQP equivalents.</p>
	<h1><a class="anchor" id="autotoc_md10"></a>
	Sources and targets</h1>
	<p>Every link has two addresses, <em>source</em> and <em>target</em>. The most common pattern for using these addresses is as follows.</p>
	<p>When a client creates a <em>receiver</em> link, it sets the <em>source</em> address. This means "I want to receive messages from this
	source". This is often referred to as "subscribing" to the source. When a client creates a <em>sender</em> link, it sets the <em>target</em> address. This means "I want to send to this target".</p>
	<p>In the case of a broker, the source or target usually refers to a queue or topic. In general they can refer to any AMQP-capable node.</p>
	<p>In the <em>request-response</em> pattern, a request message carries a <em>reply-to</em> address for the response message. This can be any AMQP address, but it is often useful to create a temporary address for the response message. The client creates a <em>receiver</em> with no source address and the <em>dynamic</em> flag set. The server generates a unique <em>source</em> address for the receiver, which is discarded when the link closes. The client uses this source address as the reply-to when it sends the request, so the response is delivered to the client's receiver.</p>
	<p>The <a class="el" href="server_direct_8cpp-example.html">server_direct.cpp</a> example shows how to implement a request-response server.</p>
	<h1><a class="anchor" id="autotoc_md11"></a>
	Delivery guarantees</h1>
	<p>Proton offers three levels of message delivery guarantee: <em>at-most-once</em>, <em>at-least-once</em>, and <em>exactly-once</em>.</p>
	<p>For <em>at-most-once</em>, the sender settles the message as soon as it sends it. If the connection is lost before the message is received by the receiver, the message will not be delivered.</p>
	<p>For <em>at-least-once</em>, the receiver accepts and settles the message on receipt. If the connection is lost before the sender is informed of the settlement, then the delivery is considered in-doubt and should be retried. This will ensure it eventually gets delivered (provided of course the connection and link can be reestablished). It may mean that it is delivered multiple times, however.</p>
	<p>Finally, for <em>exactly-once</em>, the receiver accepts the message but doesn't settle it. The sender settles once it is aware that the receiver accepted it. In this way the receiver retains knowledge of an accepted message until it is sure the sender knows it has been accepted. If the connection is lost before settlement, the receiver informs the sender of all the unsettled deliveries it knows about, and from this the sender can deduce which need to be redelivered. The sender likewise informs the receiver which deliveries it knows about, from which the receiver can deduce which have already been settled.</p>
	</div></div><!-- contents -->
	</div><!-- PageDoc -->
	</div><!-- doc-content -->
	<!-- start footer part -->
	<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
	<ul>
	<li class="footer">Generated by <a href="http://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.8.20 </li>
	</ul>
	</div>
	</body>
	</html>