1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
|
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<title>Qpid C++ API Reference</title>
<link href="doxygen.css" rel="stylesheet" type="text/css">
<link href="tabs.css" rel="stylesheet" type="text/css">
</head>
<body bgcolor="#FFFFFF">
<table border="0" width="90%" align="center">
<tr>
<td align="left">
<a title="Apache Qpid Project Page" href="http://qpid.apache.org">Apache Qpid - AMQP Messaging for Java JMS, C++, Python, Ruby, and .NET</a>
</td>
<td align="right">
<a title="Apache Qpid Documentation" href="http://qpid.apache.org/documentation.html">Apache Qpid Documentation</a>
</td>
</tr>
</table>
<!-- Generated by Doxygen 1.7.5 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li class="current"><a href="index.html"><span>Main Page</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
</div>
<div class="header">
<div class="headertitle">
<div class="title">Qpid C++ API Reference </div> </div>
</div>
<div class="contents">
<div class="textblock"><h2>Messaging Client API classes</h2>
<ul>
<li>
<p class="startli"></p>
<p class="endli"><a class="el" href="a00596.html">Qpid C++ Client API</a> </p>
</li>
<li>
<p class="startli"></p>
<p class="endli"><a class="el" href="a00597.html">Qpid Management Framework C++ API</a> </p>
</li>
</ul>
<h2>Code for common tasks</h2>
<h3>Includes and Namespaces</h3>
<pre>
#include <<a class="el" href="a00463.html">qpid/messaging/Connection.h</a>>
#include <<a class="el" href="a00420.html">qpid/messaging/Message.h</a>>
#include <<a class="el" href="a00545.html">qpid/messaging/Receiver.h</a>>
#include <<a class="el" href="a00546.html">qpid/messaging/Sender.h</a>>
#include <<a class="el" href="a00477.html">qpid/messaging/Session.h</a>></pre><pre> #include <iostream></pre><pre> using namespace <a class="el" href="a00591.html">qpid::messaging</a>;
</pre><h3>Opening Sessions and Connections</h3>
<pre>
int main(int argc, char** argv) {
<a class="el" href="a00345.html" title="STL class.">std::string</a> broker = argc > 1 ? argv[1] : "localhost:5672";
<a class="el" href="a00345.html" title="STL class.">std::string</a> address = argc > 2 ? argv[2] : "amq.topic";
Connection connection(broker);
try {
connection.open();
Session session = connection.createSession();</pre><pre> // ### Your Code Here ###</pre><pre> connection.close();
return 0;
} catch(const std::exception& error) {
std::cerr << error.what() << std::endl;
connection.close();
return 1;
}
}
</pre><h3>Creating and Sending a Message</h3>
<pre>
Sender sender = session.createSender(address);
sender.send(Message("Hello world!"));
</pre><h3>Setting Message Content</h3>
<pre>
Message message;
message.setContent("Hello world!");</pre><pre> // In some applications, you should also set the content type,
// which is a MIME type
message.setContentType("text/plain");
</pre><h3>Receiving a Message</h3>
<pre>
Receiver receiver = session.createReceiver(address);
Message message = receiver.fetch(Duration::SECOND * 1); // timeout is optional
session.acknowledge(); // acknowledge message receipt
std::cout << message.getContent() << std::endl;
</pre><h3>Receiving Messages from Multiple Sources</h3>
<p>To receive messages from multiple sources, create a receiver for each source, and use session.nextReceiver().fetch() to fetch messages. session.nextReceiver() is guaranteed to return the receiver responsible for the first available message on the session.</p>
<pre>
Receiver receiver1 = session.createReceiver(address1);
Receiver receiver2 = session.createReceiver(address2);</pre><pre> Message message = session.nextReceiver().fetch();
session.acknowledge(); // acknowledge message receipt
std::cout << message.getContent() << std::endl;
</pre><h3>Replying to a message:</h3>
<pre>
// Server creates a service queue and waits for messages
// If it gets a request, it sends a response to the reply to address</pre><pre> Receiver receiver = session.createReceiver("service_queue; {create: always}");
Message request = receiver.fetch();
const Address& address = request.getReplyTo(); // Get "reply-to" from request ...
if (address) {
Sender sender = session.createSender(address); // ... send response to "reply-to"
Message response("pong!");
sender.send(response);
session.acknowledge();
}</pre><pre> // Client creates a private response queue - the # gets converted
// to a unique string for the response queue name. Client uses the
// name of this queue as its reply-to.</pre><pre> Sender sender = session.createSender("service_queue");
Address responseQueue("#response-queue; {create:always, delete:always}");
Receiver receiver = session.createReceiver(responseQueue);</pre><pre> Message request;
request.setReplyTo(responseQueue);
request.setContent("ping");
sender.send(request);
Message response = receiver.fetch();
std::cout << request.getContent() << " -> " << response.getContent() << std::endl;
</pre><h3>Getting and Setting Standard Message Properties</h3>
<p>This shows some of the most commonly used message properties, it is not complete.</p>
<pre>
Message message("Hello world!");
message.setContentType("text/plain");
message.setSubject("greeting");
message.setReplyTo("response-queue");
message.setTtl(100); // milliseconds
message.setDurable(1);</pre><pre> std::cout << "Content: " << message.getContent() << std::endl
<< "Content Type: " << message.getContentType()
<< "Subject: " << message.getSubject()
<< "ReplyTo: " << message.getReplyTo()
<< "Time To Live (in milliseconds) " << message.getTtl()
<< "Durability: " << message.getDurable();
</pre><h3>Getting and Setting Application-Defined Message Properties</h3>
<pre>
<a class="el" href="a00345.html" title="STL class.">std::string</a> name = "weekday";
<a class="el" href="a00345.html" title="STL class.">std::string</a> value = "Thursday";
message.getProperties()[name] = value;</pre><pre> std:string s = message.getProperties()["weekday"];
</pre><h3>Transparent Failover</h3>
<p>If a connection opened using the reconnect option, it will transparently reconnect if the connection is lost.</p>
<pre>
Connection connection(broker);
connection.setOption("reconnect", true);
try {
connection.open();
....
</pre><h3>Maps</h3>
<p>Maps provide a simple way to exchange binary data portably, across languages and platforms. Maps can contain simple types, lists, or maps.</p>
<pre>
// Sender</pre><pre> Variant::Map content;
content["id"] = 987654321;
content["name"] = "Widget";
content["probability"] = 0.43;
Variant::List colours;
colours.push_back(Variant("red"));
colours.push_back(Variant("green"));
colours.push_back(Variant("white"));
content["colours"] = colours;
content["uuid"] = Uuid(true);</pre><pre> Message message;
encode(content, message);</pre><pre> sender.send(message);
</pre><pre>
// Receiver</pre><pre> Variant::Map content;
decode(receiver.fetch(), content);
</pre><h3>Guaranteed Delivery</h3>
<p>If a queue is durable, the queue survives a messaging broker crash, as well as any durable messages that have been placed on the queue. These messages will be delivered when the messaging broker is restarted. Delivery is not guaranteed unless both the message and the queue are durable.</p>
<pre>
Sender sender = session.createSender("durable-queue");</pre><pre> Message message("Hello world!");
message.setDurable(1);</pre><pre> sender.send(Message("Hello world!"));
</pre><h3>Transactions</h3>
<p>Transactions cover enqueues and dequeues.</p>
<p>When sending messages, a transaction tracks enqueues without actually delivering the messages, a commit places messages on their queues, and a rollback discards the enqueues.</p>
<p>When receiving messages, a transaction tracks dequeues without actually removing acknowledged messages, a commit removes all acknowledged messages, and a rollback discards acknowledgements. A rollback does not release the message, it must be explicitly released to return it to the queue.</p>
<pre>
Connection connection(broker);
Session session = connection.createTransactionalSession();
...
if (looksOk)
session.commit();
else
session.rollback();
</pre><h3>Exceptions</h3>
<p>All exceptions for the messaging API have MessagingException as their base class.</p>
<p>A common class of exception are those related to processing addresses used to create senders and/or receivers. These all have AddressError as their base class.</p>
<p>Where there is a syntax error in the address itself, a MalformedAddress will be thrown. Where the address is valid, but there is an error in interpreting (i.e. resolving) it, a ResolutionError - or a sub-class of it - will be thrown. If the address has assertions enabled for a given context and the asserted node properties are not in fact correct then AssertionFailed will be thrown. If the node is not found, NotFound will be thrown.</p>
<p>The loss of the underlying connection (e.g. the TCP connection) results in TransportFailure being thrown. If automatic reconnect is enabled, this will be caught be the library which will then try to reconnect. If reconnection - as configured by the connection options - fails, then TransportFailure will be thrown. This can occur on any call to the messaging API.</p>
<p>Sending a message may also result in an exception (e.g. TargetCapacityExceeded if a queue to which the message is delivered cannot enqueue it due to lack of capacity). For asynchronous send the exception may not be thrown on the send invocation that actually triggers it, but on a subsequent method call on the API.</p>
<p>Certain exceptions may render the session invalid; once these occur, subsequent calls on the session will throw the same class of exception. This is not an intrinsic property of the class of exception, but is a result of the current mapping of the API to the underlying AMQP 0-10 protocol. You can test whether the session is valid at any time using the hasError() and/or checkError() methods on Session.</p>
<h3>Logging</h3>
<p>The Qpidd broker and C++ clients can both use environment variables to enable logging. Use QPID_LOG_ENABLE to set the level of logging you are interested in (trace, debug, info, notice, warning, error, or critical):</p>
<pre>
export QPID_LOG_ENABLE="warning+"
</pre><p>Use QPID_LOG_OUTPUT to determine where logging output should be sent. This is either a file name or the special values stderr, stdout, or syslog:</p>
<pre>
export QPID_LOG_TO_FILE="/tmp/myclient.out"
</pre> </div></div>
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<hr size="1">
<address style="text-align: left;"><small>
Qpid C++ API Reference</small></address>
<address style="text-align: right;">
<small>
Generated on Thu May 10 2012 for Qpid C++ Client API by <a href="http://www.doxygen.org/index.html"><img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.7.5</small>
</address>
</body>
</html>
|
