proton
0
Main Page
Related Pages
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Macros
Pages
include
proton
messenger.h
Go to the documentation of this file.
1
#ifndef PROTON_MESSENGER_H
2
#define PROTON_MESSENGER_H 1
3
4
/*
5
*
6
* Licensed to the Apache Software Foundation (ASF) under one
7
* or more contributor license agreements. See the NOTICE file
8
* distributed with this work for additional information
9
* regarding copyright ownership. The ASF licenses this file
10
* to you under the Apache License, Version 2.0 (the
11
* "License"); you may not use this file except in compliance
12
* with the License. You may obtain a copy of the License at
13
*
14
* http://www.apache.org/licenses/LICENSE-2.0
15
*
16
* Unless required by applicable law or agreed to in writing,
17
* software distributed under the License is distributed on an
18
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
19
* KIND, either express or implied. See the License for the
20
* specific language governing permissions and limitations
21
* under the License.
22
*
23
*/
24
25
#include <
proton/import_export.h
>
26
#include <
proton/message.h
>
27
28
#ifdef __cplusplus
29
extern
"C"
{
30
#endif
31
32
/** @file
33
* The messenger API provides a high level interface for sending and
34
* receiving AMQP messages.
35
*/
36
37
typedef
struct
pn_messenger_t
pn_messenger_t
;
/**< Messenger*/
38
typedef
struct
pn_subscription_t
pn_subscription_t
;
/**< Subscription*/
39
typedef
int64_t
pn_tracker_t
;
40
41
typedef
enum
{
42
PN_STATUS_UNKNOWN
= 0,
43
PN_STATUS_PENDING
= 1,
44
PN_STATUS_ACCEPTED
= 2,
45
PN_STATUS_REJECTED
= 3,
46
PN_STATUS_MODIFIED
= 4
47
}
pn_status_t
;
48
49
/** Construct a new Messenger with the given name. The name is global.
50
* If a NULL name is supplied, a UUID based name will be chosen.
51
*
52
* @param[in] name the name of the messenger or NULL
53
*
54
* @return pointer to a new Messenger
55
*/
56
PN_EXTERN
pn_messenger_t
*
pn_messenger
(
const
char
*name);
57
58
/** Retrieves the name of a Messenger.
59
*
60
* @param[in] messenger the messenger
61
*
62
* @return the name of the messenger
63
*/
64
PN_EXTERN
const
char
*
pn_messenger_name
(
pn_messenger_t
*messenger);
65
66
/** Provides a certificate that will be used to identify the local
67
* Messenger to the peer.
68
*
69
* @param[in] messenger the messenger
70
* @param[in] certificate a path to a certificate file
71
*
72
* @return an error code of zero if there is no error
73
*/
74
PN_EXTERN
int
pn_messenger_set_certificate
(
pn_messenger_t
*messenger,
const
char
*certificate);
75
76
/** Gets the certificate file for a Messenger.
77
*
78
* @param[in] messenger the messenger
79
* @return the certificate file path
80
*/
81
PN_EXTERN
const
char
*
pn_messenger_get_certificate
(
pn_messenger_t
*messenger);
82
83
/** Provides the private key that was used to sign the certificate.
84
* See ::pn_messenger_set_certificate
85
*
86
* @param[in] messenger the Messenger
87
* @param[in] private_key a path to a private key file
88
*
89
* @return an error code of zero if there is no error
90
*/
91
PN_EXTERN
int
pn_messenger_set_private_key
(
pn_messenger_t
*messenger,
const
char
*private_key);
92
93
/** Gets the private key file for a Messenger.
94
*
95
* @param[in] messenger the messenger
96
* @return the private key file path
97
*/
98
PN_EXTERN
const
char
*
pn_messenger_get_private_key
(
pn_messenger_t
*messenger);
99
100
/** Sets the private key password for a Messenger.
101
*
102
* @param[in] messenger the messenger
103
* @param[in] password the password for the private key file
104
*
105
* @return an error code of zero if there is no error
106
*/
107
PN_EXTERN
int
pn_messenger_set_password
(
pn_messenger_t
*messenger,
const
char
*password);
108
109
/** Gets the private key file password for a Messenger.
110
*
111
* @param[in] messenger the messenger
112
* @return password for the private key file
113
*/
114
PN_EXTERN
const
char
*
pn_messenger_get_password
(
pn_messenger_t
*messenger);
115
116
/** Sets the trusted certificates database for a Messenger. Messenger
117
* will use this database to validate the certificate provided by the
118
* peer.
119
*
120
* @param[in] messenger the messenger
121
* @param[in] cert_db a path to the certificates database
122
*
123
* @return an error code of zero if there is no error
124
*/
125
PN_EXTERN
int
pn_messenger_set_trusted_certificates
(
pn_messenger_t
*messenger,
const
char
*cert_db);
126
127
/** Gets the trusted certificates database for a Messenger.
128
*
129
* @param[in] messenger the messenger
130
* @return path to the trusted certificates database
131
*/
132
PN_EXTERN
const
char
*
pn_messenger_get_trusted_certificates
(
pn_messenger_t
*messenger);
133
134
/** Sets the timeout for a Messenger. A negative timeout means
135
* infinite.
136
*
137
* @param[in] messenger the messenger
138
* @param[in] timeout the new timeout for the messenger, in milliseconds
139
*
140
* @return an error code or zero if there is no error
141
*/
142
PN_EXTERN
int
pn_messenger_set_timeout
(
pn_messenger_t
*messenger,
int
timeout);
143
144
/** Retrieves the timeout for a Messenger.
145
*
146
* @param[in] messenger the messenger
147
*
148
* @return the timeout for the messenger, in milliseconds
149
*/
150
PN_EXTERN
int
pn_messenger_get_timeout
(
pn_messenger_t
*messenger);
151
152
PN_EXTERN
bool
pn_messenger_is_blocking
(
pn_messenger_t
*messenger);
153
PN_EXTERN
int
pn_messenger_set_blocking
(
pn_messenger_t
*messenger,
bool
blocking);
154
155
/** Frees a Messenger.
156
*
157
* @param[in] messenger the messenger to free, no longer valid on
158
* return
159
*/
160
PN_EXTERN
void
pn_messenger_free
(
pn_messenger_t
*messenger);
161
162
/** Returns the error code for the Messenger.
163
*
164
* @param[in] messenger the messenger to check for errors
165
*
166
* @return an error code or zero if there is no error
167
* @see error.h
168
*/
169
PN_EXTERN
int
pn_messenger_errno
(
pn_messenger_t
*messenger);
170
171
/** Returns the error info for a Messenger.
172
*
173
* @param[in] messenger the messenger to check for errors
174
*
175
* @return a pointer to the messenger's error descriptor
176
* @see error.h
177
*/
178
PN_EXTERN
pn_error_t
*
pn_messenger_error
(
pn_messenger_t
*messenger);
179
180
/** Gets the outgoing window for a Messenger. @see
181
* ::pn_messenger_set_outgoing_window
182
*
183
* @param[in] messenger the messenger
184
*
185
* @return the outgoing window
186
*/
187
PN_EXTERN
int
pn_messenger_get_outgoing_window
(
pn_messenger_t
*messenger);
188
189
/** Sets the outgoing window for a Messenger. If the outgoing window
190
* is set to a positive value, then after each call to
191
* pn_messenger_send, the Messenger will track the status of that
192
* many deliveries. @see ::pn_messenger_status
193
*
194
* @param[in] messenger the Messenger
195
* @param[in] window the number of deliveries to track
196
*
197
* @return an error or zero on success
198
* @see error.h
199
*/
200
PN_EXTERN
int
pn_messenger_set_outgoing_window
(
pn_messenger_t
*messenger,
int
window);
201
202
/** Gets the incoming window for a Messenger. @see
203
* ::pn_messenger_set_incoming_window
204
*
205
* @param[in] messenger the Messenger
206
*
207
* @return the incoming window
208
*/
209
PN_EXTERN
int
pn_messenger_get_incoming_window
(
pn_messenger_t
*messenger);
210
211
/** Sets the incoming window for a Messenger. If the incoming window
212
* is set to a positive value, then after each call to
213
* pn_messenger_accept or pn_messenger_reject, the Messenger will
214
* track the status of that many deliveries. @see
215
* ::pn_messenger_status
216
*
217
* @param[in] messenger the Messenger
218
* @param[in] window the number of deliveries to track
219
*
220
* @return an error or zero on success
221
* @see error.h
222
*/
223
PN_EXTERN
int
pn_messenger_set_incoming_window
(
pn_messenger_t
*messenger,
int
window);
224
225
/** Starts a messenger. A messenger cannot send or recv messages until
226
* it is started.
227
*
228
* @param[in] messenger the messenger to start
229
*
230
* @return an error code or zero on success
231
* @see error.h
232
*/
233
PN_EXTERN
int
pn_messenger_start
(
pn_messenger_t
*messenger);
234
235
/** Stops a messenger. A messenger cannot send or recv messages when
236
* it is stopped.
237
*
238
* @param[in] messenger the messenger to stop
239
*
240
* @return an error code or zero on success
241
* @see error.h
242
*/
243
PN_EXTERN
int
pn_messenger_stop
(
pn_messenger_t
*messenger);
244
245
PN_EXTERN
bool
pn_messenger_stopped
(
pn_messenger_t
*messenger);
246
247
/** Subscribes a messenger to messages from the specified source.
248
*
249
* @param[in] messenger the messenger to subscribe
250
* @param[in] source
251
*
252
* @return a subscription
253
*/
254
PN_EXTERN
pn_subscription_t
*
pn_messenger_subscribe
(
pn_messenger_t
*messenger,
const
char
*source);
255
256
PN_EXTERN
void
*
pn_subscription_get_context
(
pn_subscription_t
*sub);
257
258
PN_EXTERN
void
pn_subscription_set_context
(
pn_subscription_t
*sub,
void
*context);
259
260
/** Puts a message on the outgoing message queue for a messenger.
261
*
262
* @param[in] messenger the messenger
263
* @param[in] msg the message to put on the outgoing queue
264
*
265
* @return an error code or zero on success
266
* @see error.h
267
*/
268
PN_EXTERN
int
pn_messenger_put
(
pn_messenger_t
*messenger,
pn_message_t
*msg);
269
270
/** Gets the last known remote state of the delivery associated with
271
* the given tracker.
272
*
273
* @param[in] messenger the messenger
274
* @param[in] tracker the tracker identify the delivery
275
*
276
* @return a status code for the delivery
277
*/
278
PN_EXTERN
pn_status_t
pn_messenger_status
(
pn_messenger_t
*messenger, pn_tracker_t tracker);
279
280
/** Frees a Messenger from tracking the status associated with a given
281
* tracker. Use the PN_CUMULATIVE flag to indicate everything up to
282
* (and including) the given tracker.
283
*
284
* @param[in] messenger the Messenger
285
* @param[in] tracker identifies a delivery
286
* @param[in] flags 0 or PN_CUMULATIVE
287
*
288
* @return an error code or zero on success
289
* @see error.h
290
*/
291
PN_EXTERN
int
pn_messenger_settle
(
pn_messenger_t
*messenger, pn_tracker_t tracker,
int
flags);
292
293
/** Gets the tracker for the message most recently provided to
294
* pn_messenger_put.
295
*
296
* @param[in] messenger the messenger
297
*
298
* @return a pn_tracker_t or an undefined value if pn_messenger_get
299
* has never been called for the given messenger
300
*/
301
PN_EXTERN
pn_tracker_t
pn_messenger_outgoing_tracker
(
pn_messenger_t
*messenger);
302
303
/** Sends or receives any outstanding messages queued for a messenger.
304
* This will block for the indicated timeout.
305
*
306
* @param[in] messenger the Messenger
307
* @param[in] timeout the maximum time to block
308
*/
309
PN_EXTERN
int
pn_messenger_work
(
pn_messenger_t
*messenger,
int
timeout);
310
311
/** Interrupts a messenger that is blocking. This method may be safely
312
* called from a different thread than the one that is blocking.
313
*
314
* @param[in] messenger the Messenger
315
*/
316
PN_EXTERN
int
pn_messenger_interrupt
(
pn_messenger_t
*messenger);
317
318
/** Sends messages in the outgoing message queue for a messenger. This
319
* call will block until the indicated number of messages have been
320
* sent. If n is -1 this call will block until all outgoing messages
321
* have been sent. If n is 0 then this call won't block.
322
*
323
* @param[in] messenger the messager
324
* @param[in] n the number of messages to send
325
*
326
* @return an error code or zero on success
327
* @see error.h
328
*/
329
PN_EXTERN
int
pn_messenger_send
(
pn_messenger_t
*messenger,
int
n);
330
331
/** Instructs the messenger to receives up to limit messages into the
332
* incoming message queue of a messenger. If limit is -1, Messenger
333
* will receive as many messages as it can buffer internally. If the
334
* messenger is in blocking mode, this call will block until at least
335
* one message is available in the incoming queue.
336
*
337
* Each call to pn_messenger_recv replaces the previos receive
338
* operation, so pn_messenger_recv(messenger, 0) will cancel any
339
* outstanding receive.
340
*
341
* @param[in] messenger the messenger
342
* @param[in] limit the maximum number of messages to receive or -1 to
343
* to receive as many messages as it can buffer
344
* internally.
345
*
346
* @return an error code or zero on success
347
* @see error.h
348
*/
349
PN_EXTERN
int
pn_messenger_recv
(
pn_messenger_t
*messenger,
int
limit);
350
351
/** Returns the number of messages currently being received by a
352
* messenger.
353
*
354
* @param[in] messenger the messenger
355
*/
356
PN_EXTERN
int
pn_messenger_receiving
(
pn_messenger_t
*messenger);
357
358
/** Gets a message from the head of the incoming message queue of a
359
* messenger.
360
*
361
* @param[in] messenger the messenger
362
* @param[out] msg upon return contains the message from the head of the queue
363
*
364
* @return an error code or zero on success
365
* @see error.h
366
*/
367
PN_EXTERN
int
pn_messenger_get
(
pn_messenger_t
*messenger,
pn_message_t
*msg);
368
369
/** Gets the tracker for the message most recently fetched by
370
* pn_messenger_get.
371
*
372
* @param[in] messenger the messenger
373
*
374
* @return a pn_tracker_t or an undefined value if pn_messenger_get
375
* has never been called for the given messenger
376
*/
377
PN_EXTERN
pn_tracker_t
pn_messenger_incoming_tracker
(
pn_messenger_t
*messenger);
378
379
PN_EXTERN
pn_subscription_t
*
pn_messenger_incoming_subscription
(
pn_messenger_t
*messenger);
380
381
#define PN_CUMULATIVE (0x1)
382
383
/** Accepts the incoming messages identified by the tracker. Use the
384
* PN_CUMULATIVE flag to accept everything prior to the supplied
385
* tracker.
386
*
387
* @param[in] messenger the messenger
388
* @param[in] tracker an incoming tracker
389
* @param[in] flags 0 or PN_CUMULATIVE
390
*
391
* @return an error code or zero on success
392
* @see error.h
393
*/
394
PN_EXTERN
int
pn_messenger_accept
(
pn_messenger_t
*messenger, pn_tracker_t tracker,
int
flags);
395
396
/** Rejects the incoming messages identified by the tracker. Use the
397
* PN_CUMULATIVE flag to reject everything prior to the supplied
398
* tracker.
399
*
400
* @param[in] messenger the Messenger
401
* @param[in] tracker an incoming tracker
402
* @param[in] flags 0 or PN_CUMULATIVE
403
*
404
* @return an error code or zero on success
405
* @see error.h
406
*/
407
PN_EXTERN
int
pn_messenger_reject
(
pn_messenger_t
*messenger, pn_tracker_t tracker,
int
flags);
408
409
/** Returns the number of messages in the outgoing message queue of a messenger.
410
*
411
* @param[in] messenger the Messenger
412
*
413
* @return the outgoing queue depth
414
*/
415
PN_EXTERN
int
pn_messenger_outgoing
(
pn_messenger_t
*messenger);
416
417
/** Returns the number of messages in the incoming message queue of a messenger.
418
*
419
* @param[in] messenger the Messenger
420
*
421
* @return the incoming queue depth
422
*/
423
PN_EXTERN
int
pn_messenger_incoming
(
pn_messenger_t
*messenger);
424
425
/** Adds a routing rule to a Messenger's internal routing table.
426
*
427
* The route procedure may be used to influence how a messenger will
428
* internally treat a given address or class of addresses. Every call
429
* to the route procedure will result in messenger appending a routing
430
* rule to its internal routing table.
431
*
432
* Whenever a message is presented to a messenger for delivery, it
433
* will match the address of this message against the set of routing
434
* rules in order. The first rule to match will be triggered, and
435
* instead of routing based on the address presented in the message,
436
* the messenger will route based on the address supplied in the rule.
437
*
438
* The pattern matching syntax supports two types of matches, a '%'
439
* will match any character except a '/', and a '*' will match any
440
* character including a '/'.
441
*
442
* A routing address is specified as a normal AMQP address, however it
443
* may additionally use substitution variables from the pattern match
444
* that triggered the rule.
445
*
446
* Any message sent to "foo" will be routed to "amqp://foo.com":
447
*
448
* pn_messenger_route("foo", "amqp://foo.com");
449
*
450
* Any message sent to "foobar" will be routed to
451
* "amqp://foo.com/bar":
452
*
453
* pn_messenger_route("foobar", "amqp://foo.com/bar");
454
*
455
* Any message sent to bar/<path> will be routed to the corresponding
456
* path within the amqp://bar.com domain:
457
*
458
* pn_messenger_route("bar/*", "amqp://bar.com/$1");
459
*
460
* Route all messages over TLS:
461
*
462
* pn_messenger_route("amqp:*", "amqps:$1")
463
*
464
* Supply credentials for foo.com:
465
*
466
* pn_messenger_route("amqp://foo.com/*", "amqp://user:password@foo.com/$1");
467
*
468
* Supply credentials for all domains:
469
*
470
* pn_messenger_route("amqp://*", "amqp://user:password@$1");
471
*
472
* Route all addresses through a single proxy while preserving the
473
* original destination:
474
*
475
* pn_messenger_route("amqp://%/*", "amqp://user:password@proxy/$1/$2");
476
*
477
* Route any address through a single broker:
478
*
479
* pn_messenger_route("*", "amqp://user:password@broker/$1");
480
*
481
* @param[in] messenger the Messenger
482
* @param[in] pattern a glob pattern
483
* @param[in] address an address indicating alternative routing
484
*
485
* @return an error code or zero on success
486
* @see error.h
487
*
488
*/
489
PN_EXTERN
int
pn_messenger_route
(
pn_messenger_t
*messenger,
const
char
*pattern,
490
const
char
*address);
491
492
PN_EXTERN
int
pn_messenger_rewrite
(
pn_messenger_t
*messenger,
const
char
*pattern,
493
const
char
*address);
494
495
#ifdef __cplusplus
496
}
497
#endif
498
499
#endif
/* messenger.h */
Generated on Wed Oct 9 2013 22:14:58 for proton by
1.8.3.1