proton
0
Main Page
Related Pages
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Macros
Groups
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
#include <
proton/selectable.h
>
28
29
#ifdef __cplusplus
30
extern
"C"
{
31
#endif
32
33
/**
34
* @file
35
*
36
* The messenger API provides a high level interface for sending and
37
* receiving AMQP messages.
38
*
39
* @defgroup messenger Messenger
40
* @{
41
*/
42
43
/**
44
* A ::pn_messenger_t provides a high level interface for sending and
45
* receiving messages (See ::pn_message_t).
46
*
47
* Every messenger contains a single logical queue of incoming
48
* messages and a single logical queue of outgoing messages. The
49
* messages in these queues may be destined for, or originate from, a
50
* variety of addresses.
51
*
52
* The messenger interface is single-threaded. All methods except one
53
* (::pn_messenger_interrupt()) are intended to be used by one thread
54
* at a time.
55
*
56
*
57
* Address Syntax
58
* ==============
59
*
60
* An address has the following form::
61
*
62
* [ amqp[s]:// ] [user[:password]@] domain [/[name]]
63
*
64
* Where domain can be one of::
65
*
66
* host | host:port | ip | ip:port | name
67
*
68
* The following are valid examples of addresses:
69
*
70
* - example.org
71
* - example.org:1234
72
* - amqp://example.org
73
* - amqps://example.org
74
* - example.org/incoming
75
* - amqps://example.org/outgoing
76
* - amqps://fred:trustno1@example.org
77
* - 127.0.0.1:1234
78
* - amqps://127.0.0.1:1234
79
*
80
* Sending & Receiving Messages
81
* ============================
82
*
83
* The messenger API works in conjuction with the ::pn_message_t API.
84
* A ::pn_message_t is a mutable holder of message content.
85
*
86
* The ::pn_messenger_put() operation copies content from the supplied
87
* ::pn_message_t to the outgoing queue, and may send queued messages
88
* if it can do so without blocking. The ::pn_messenger_send()
89
* operation blocks until it has sent the requested number of
90
* messages, or until a timeout interrupts the attempt.
91
*
92
*
93
* pn_messenger_t *messenger = pn_messenger(NULL);
94
* pn_message_t *message = pn_message();
95
* char subject[1024];
96
* for (int i = 0; i < 3; i++) {
97
* pn_message_set_address(message, "amqp://host/queue");
98
* sprintf(subject, "Hello World! %i", i);
99
* pn_message_set_subject(message, subject);
100
* pn_messenger_put(messenger, message)
101
* pn_messenger_send(messenger);
102
*
103
* Similarly, the ::pn_messenger_recv() method receives messages into
104
* the incoming queue, and may block as it attempts to receive up to
105
* the requested number of messages, or until the timeout is reached.
106
* It may receive fewer than the requested number. The
107
* ::pn_messenger_get() method pops the eldest message off the
108
* incoming queue and copies its content into the supplied
109
* ::pn_message_t object. It will not block.
110
*
111
*
112
* pn_messenger_t *messenger = pn_messenger(NULL);
113
* pn_message_t *message = pn_message()
114
* pn_messenger_recv(messenger):
115
* while (pn_messenger_incoming(messenger) > 0) {
116
* pn_messenger_get(messenger, message);
117
* printf("%s", message.subject);
118
* }
119
*
120
* Output:
121
* Hello World 0
122
* Hello World 1
123
* Hello World 2
124
*
125
* The blocking flag allows you to turn off blocking behavior
126
* entirely, in which case ::pn_messenger_send() and
127
* ::pn_messenger_recv() will do whatever they can without blocking,
128
* and then return. You can then look at the number of incoming and
129
* outgoing messages to see how much outstanding work still remains.
130
*/
131
typedef
struct
pn_messenger_t
pn_messenger_t
;
132
133
/**
134
* A subscription is a request for incoming messages.
135
*
136
* @todo currently the subscription API is under developed, this
137
* should allow more explicit control over subscription properties and
138
* behaviour
139
*/
140
typedef
struct
pn_subscription_t
pn_subscription_t
;
141
142
/**
143
* Trackers provide a lightweight handle used to track the status of
144
* incoming and outgoing deliveries.
145
*/
146
typedef
int64_t
pn_tracker_t
;
147
148
/**
149
* Describes all the possible states for a message associated with a
150
* given tracker.
151
*/
152
typedef
enum
{
153
PN_STATUS_UNKNOWN
= 0,
/**< The tracker is unknown. */
154
PN_STATUS_PENDING
= 1,
/**< The message is in flight. For outgoing
155
messages, use ::pn_messenger_buffered to
156
see if it has been sent or not. */
157
PN_STATUS_ACCEPTED
= 2,
/**< The message was accepted. */
158
PN_STATUS_REJECTED
= 3,
/**< The message was rejected. */
159
PN_STATUS_RELEASED
= 4,
/**< The message was released. */
160
PN_STATUS_MODIFIED
= 5,
/**< The message was modified. */
161
PN_STATUS_ABORTED
= 6,
/**< The message was aborted. */
162
PN_STATUS_SETTLED
= 7
/**< The remote party has settled the message. */
163
}
pn_status_t
;
164
165
/**
166
* Construct a new ::pn_messenger_t with the given name. The name is
167
* global. If a NULL name is supplied, a UUID based name will be
168
* chosen.
169
*
170
* @param[in] name the name of the messenger or NULL
171
*
172
* @return pointer to a new ::pn_messenger_t
173
*/
174
PN_EXTERN
pn_messenger_t
*
pn_messenger
(
const
char
*name);
175
176
/**
177
* Get the name of a messenger.
178
*
179
* @param[in] messenger a messenger object
180
* @return the name of the messenger
181
*/
182
PN_EXTERN
const
char
*
pn_messenger_name
(
pn_messenger_t
*messenger);
183
184
/**
185
* Sets the path that will be used to get the certificate that will be
186
* used to identify this messenger to its peers. The validity of the
187
* path is not checked by this function.
188
*
189
* @param[in] messenger the messenger
190
* @param[in] certificate a path to a certificate file
191
* @return an error code of zero if there is no error
192
*/
193
PN_EXTERN
int
pn_messenger_set_certificate
(
pn_messenger_t
*messenger,
const
char
*certificate);
194
195
/**
196
* Get the certificate path. This value may be set by
197
* pn_messenger_set_certificate. The default certificate path is null.
198
*
199
* @param[in] messenger the messenger
200
* @return the certificate file path
201
*/
202
PN_EXTERN
const
char
*
pn_messenger_get_certificate
(
pn_messenger_t
*messenger);
203
204
/**
205
* Set path to the private key that was used to sign the certificate.
206
* See ::pn_messenger_set_certificate
207
*
208
* @param[in] messenger a messenger object
209
* @param[in] private_key a path to a private key file
210
* @return an error code of zero if there is no error
211
*/
212
PN_EXTERN
int
pn_messenger_set_private_key
(
pn_messenger_t
*messenger,
const
char
*private_key);
213
214
/**
215
* Gets the private key file for a messenger.
216
*
217
* @param[in] messenger a messenger object
218
* @return the messenger's private key file path
219
*/
220
PN_EXTERN
const
char
*
pn_messenger_get_private_key
(
pn_messenger_t
*messenger);
221
222
/**
223
* Sets the private key password for a messenger.
224
*
225
* @param[in] messenger a messenger object
226
* @param[in] password the password for the private key file
227
*
228
* @return an error code of zero if there is no error
229
*/
230
PN_EXTERN
int
pn_messenger_set_password
(
pn_messenger_t
*messenger,
const
char
*password);
231
232
/**
233
* Gets the private key file password for a messenger.
234
*
235
* @param[in] messenger a messenger object
236
* @return password for the private key file
237
*/
238
PN_EXTERN
const
char
*
pn_messenger_get_password
(
pn_messenger_t
*messenger);
239
240
/**
241
* Sets the trusted certificates database for a messenger.
242
*
243
* The messenger will use this database to validate the certificate
244
* provided by the peer.
245
*
246
* @param[in] messenger a messenger object
247
* @param[in] cert_db a path to the certificates database
248
*
249
* @return an error code of zero if there is no error
250
*/
251
PN_EXTERN
int
pn_messenger_set_trusted_certificates
(
pn_messenger_t
*messenger,
const
char
*cert_db);
252
253
/**
254
* Gets the trusted certificates database for a messenger.
255
*
256
* @param[in] messenger a messenger object
257
* @return path to the trusted certificates database
258
*/
259
PN_EXTERN
const
char
*
pn_messenger_get_trusted_certificates
(
pn_messenger_t
*messenger);
260
261
/**
262
* Set the default timeout for a messenger.
263
*
264
* Any messenger call that blocks during execution will stop blocking
265
* and return control when this timeout is reached, if you have set it
266
* to a value greater than zero. The timeout is expressed in
267
* milliseconds.
268
*
269
* @param[in] messenger a messenger object
270
* @param[in] timeout a new timeout for the messenger, in milliseconds
271
* @return an error code or zero if there is no error
272
*/
273
PN_EXTERN
int
pn_messenger_set_timeout
(
pn_messenger_t
*messenger,
int
timeout);
274
275
/**
276
* Gets the timeout for a messenger object.
277
*
278
* See ::pn_messenger_set_timeout() for details.
279
*
280
* @param[in] messenger a messenger object
281
* @return the timeout for the messenger, in milliseconds
282
*/
283
PN_EXTERN
int
pn_messenger_get_timeout
(
pn_messenger_t
*messenger);
284
285
/**
286
* Check if a messenger is in blocking mode.
287
*
288
* @param[in] messenger a messenger object
289
* @return true if blocking has been enabled, false otherwise
290
*/
291
PN_EXTERN
bool
pn_messenger_is_blocking
(
pn_messenger_t
*messenger);
292
293
/**
294
* Enable or disable blocking behavior for a messenger during calls to
295
* ::pn_messenger_send and ::pn_messenger_recv.
296
*
297
* @param[in] messenger a messenger object
298
* @param[in] blocking the value of the blocking flag
299
* @return an error code or zero if there is no error
300
*/
301
PN_EXTERN
int
pn_messenger_set_blocking
(
pn_messenger_t
*messenger,
bool
blocking);
302
303
/**
304
* Check if a messenger is in passive mode.
305
*
306
* A messenger that is in passive mode will never attempt to perform
307
* I/O internally, but instead will make all internal file descriptors
308
* accessible through ::pn_messenger_selectable() to be serviced
309
* externally. This can be useful for integrating messenger into an
310
* external event loop.
311
*
312
* @param[in] messenger a messenger object
313
* @return true if the messenger is in passive mode, false otherwise
314
*/
315
PN_EXTERN
bool
pn_messenger_is_passive
(
pn_messenger_t
*messenger);
316
317
/**
318
* Set the passive mode for a messenger.
319
*
320
* See ::pn_messenger_is_passive() for details on passive mode.
321
*
322
* @param[in] messenger a messenger object
323
* @param[in] passive true to enable passive mode, false to disable
324
* passive mode
325
* @return an error code or zero on success
326
*/
327
PN_EXTERN
int
pn_messenger_set_passive
(
pn_messenger_t
*messenger,
bool
passive);
328
329
/** Frees a Messenger.
330
*
331
* @param[in] messenger the messenger to free (or NULL), no longer
332
* valid on return
333
*/
334
PN_EXTERN
void
pn_messenger_free
(
pn_messenger_t
*messenger);
335
336
/**
337
* Get the code for a messenger's most recent error.
338
*
339
* The error code is initialized to zero at messenger creation. The
340
* error number is "sticky" i.e. error codes are not reset to 0 at the
341
* end of successful API calls. You can use ::pn_messenger_error to
342
* access the messenger's error object and clear explicitly if
343
* desired.
344
*
345
* @param[in] messenger the messenger to check for errors
346
* @return an error code or zero if there is no error
347
* @see error.h
348
*/
349
PN_EXTERN
int
pn_messenger_errno
(
pn_messenger_t
*messenger);
350
351
/**
352
* Get a messenger's error object.
353
*
354
* Returns a pointer to a pn_error_t that is valid until the messenger
355
* is freed. The pn_error_* API allows you to access the text, error
356
* number, and lets you set or clear the error code explicitly.
357
*
358
* @param[in] messenger the messenger to check for errors
359
* @return a pointer to the messenger's error descriptor
360
* @see error.h
361
*/
362
PN_EXTERN
pn_error_t
*
pn_messenger_error
(
pn_messenger_t
*messenger);
363
364
/**
365
* Get the size of a messenger's outgoing window.
366
*
367
* The size of the outgoing window limits the number of messages whose
368
* status you can check with a tracker. A message enters this window
369
* when you call pn_messenger_put on the message. For example, if your
370
* outgoing window size is 10, and you call pn_messenger_put 12 times,
371
* new status information will no longer be available for the first 2
372
* messages.
373
*
374
* The default outgoing window size is 0.
375
*
376
* @param[in] messenger a messenger object
377
* @return the outgoing window for the messenger
378
*/
379
PN_EXTERN
int
pn_messenger_get_outgoing_window
(
pn_messenger_t
*messenger);
380
381
/**
382
* Set the size of a messenger's outgoing window.
383
*
384
* See ::pn_messenger_get_outgoing_window() for details.
385
*
386
* @param[in] messenger a messenger object
387
* @param[in] window the number of deliveries to track
388
* @return an error or zero on success
389
* @see error.h
390
*/
391
PN_EXTERN
int
pn_messenger_set_outgoing_window
(
pn_messenger_t
*messenger,
int
window);
392
393
/**
394
* Get the size of a messenger's incoming window.
395
*
396
* The size of a messenger's incoming window limits the number of
397
* messages that can be accepted or rejected using trackers. Messages
398
* *do not* enter this window when they have been received
399
* (::pn_messenger_recv) onto you incoming queue. Messages only enter
400
* this window only when you access them using pn_messenger_get. If
401
* your incoming window size is N, and you get N+1 messages without
402
* explicitly accepting or rejecting the oldest message, then it will
403
* be implicitly accepted when it falls off the edge of the incoming
404
* window.
405
*
406
* The default incoming window size is 0.
407
*
408
* @param[in] messenger a messenger object
409
* @return the incoming window for the messenger
410
*/
411
PN_EXTERN
int
pn_messenger_get_incoming_window
(
pn_messenger_t
*messenger);
412
413
/**
414
* Set the size of a messenger's incoming window.
415
*
416
* See ::pn_messenger_get_incoming_window() for details.
417
*
418
* @param[in] messenger a messenger object
419
* @param[in] window the number of deliveries to track
420
* @return an error or zero on success
421
* @see error.h
422
*/
423
PN_EXTERN
int
pn_messenger_set_incoming_window
(
pn_messenger_t
*messenger,
424
int
window);
425
426
/**
427
* Currently a no-op placeholder. For future compatibility, do not
428
* send or receive messages before starting the messenger.
429
*
430
* @param[in] messenger the messenger to start
431
* @return an error code or zero on success
432
* @see error.h
433
*/
434
PN_EXTERN
int
pn_messenger_start
(
pn_messenger_t
*messenger);
435
436
/**
437
* Stops a messenger.
438
*
439
* Stopping a messenger will perform an orderly shutdown of all
440
* underlying connections. This may require some time. If the
441
* messenger is in non blocking mode (see ::pn_messenger_is_blocking),
442
* this operation will return PN_INPROGRESS if it cannot finish
443
* immediately. In that case, you can use ::pn_messenger_stopped() to
444
* determine when the messenger has finished stopping.
445
*
446
* @param[in] messenger the messenger to stop
447
* @return an error code or zero on success
448
* @see error.h
449
*/
450
PN_EXTERN
int
pn_messenger_stop
(
pn_messenger_t
*messenger);
451
452
/**
453
* Returns true if a messenger is in the stopped state. This function
454
* does not block.
455
*
456
* @param[in] messenger the messenger to stop
457
*
458
*/
459
PN_EXTERN
bool
pn_messenger_stopped
(
pn_messenger_t
*messenger);
460
461
/**
462
* Subscribes a messenger to messages from the specified source.
463
*
464
* @param[in] messenger the messenger to subscribe
465
* @param[in] source
466
* @return a subscription
467
*/
468
PN_EXTERN
pn_subscription_t
*
pn_messenger_subscribe
(
pn_messenger_t
*messenger,
const
char
*source);
469
470
/**
471
* Get a subscription's application context.
472
*
473
* See ::pn_subscription_set_context().
474
*
475
* @param[in] sub a subscription object
476
* @return the subscription's application context
477
*/
478
PN_EXTERN
void
*
pn_subscription_get_context
(
pn_subscription_t
*sub);
479
480
/**
481
* Set an application context for a subscription.
482
*
483
* @param[in] sub a subscription object
484
* @param[in] context the application context for the subscription
485
*/
486
PN_EXTERN
void
pn_subscription_set_context
(
pn_subscription_t
*sub,
void
*context);
487
488
/**
489
* Get the source address of a subscription.
490
*
491
* @param[in] sub a subscription object
492
* @return the subscription's source address
493
*/
494
PN_EXTERN
const
char
*
pn_subscription_address
(
pn_subscription_t
*sub);
495
496
/**
497
* Puts a message onto the messenger's outgoing queue. The message may
498
* also be sent if transmission would not cause blocking. This call
499
* will not block.
500
*
501
* @param[in] messenger a messenger object
502
* @param[in] msg a message to put on the messenger's outgoing queue
503
* @return an error code or zero on success
504
* @see error.h
505
*/
506
PN_EXTERN
int
pn_messenger_put
(
pn_messenger_t
*messenger,
pn_message_t
*msg);
507
508
/**
509
* Track the status of a delivery.
510
*
511
* Get the current status of the delivery associated with the supplied
512
* tracker. This may return PN_STATUS_UNKOWN if the tracker has fallen
513
* outside the incoming/outgoing tracking windows of the messenger.
514
*
515
* @param[in] messenger the messenger
516
* @param[in] tracker the tracker identifying the delivery
517
* @return a status code for the delivery
518
*/
519
PN_EXTERN
pn_status_t
pn_messenger_status
(
pn_messenger_t
*messenger, pn_tracker_t tracker);
520
521
/**
522
* Check if the delivery associated with a given tracker is still
523
* waiting to be sent.
524
*
525
* Note that returning false does not imply that the delivery was
526
* actually sent over the wire.
527
*
528
* @param[in] messenger the messenger
529
* @param[in] tracker the tracker identifying the delivery
530
*
531
* @return true if the delivery is still buffered
532
*/
533
PN_EXTERN
bool
pn_messenger_buffered
(
pn_messenger_t
*messenger, pn_tracker_t tracker);
534
535
/**
536
* Frees a Messenger from tracking the status associated with a given
537
* tracker. Use the PN_CUMULATIVE flag to indicate everything up to
538
* (and including) the given tracker.
539
*
540
* @param[in] messenger the Messenger
541
* @param[in] tracker identifies a delivery
542
* @param[in] flags 0 or PN_CUMULATIVE
543
*
544
* @return an error code or zero on success
545
* @see error.h
546
*/
547
PN_EXTERN
int
pn_messenger_settle
(
pn_messenger_t
*messenger, pn_tracker_t tracker,
int
flags);
548
549
/**
550
* Get a tracker for the outgoing message most recently given to
551
* pn_messenger_put.
552
*
553
* This tracker may be used with pn_messenger_status to determine the
554
* delivery status of the message, as long as the message is still
555
* within your outgoing window.
556
*
557
* @param[in] messenger the messenger
558
*
559
* @return a pn_tracker_t or an undefined value if pn_messenger_get
560
* has never been called for the given messenger
561
*/
562
PN_EXTERN
pn_tracker_t
pn_messenger_outgoing_tracker
(
pn_messenger_t
*messenger);
563
564
/**
565
* Sends or receives any outstanding messages queued for a messenger.
566
* This will block for the indicated timeout.
567
*
568
* @param[in] messenger the Messenger
569
* @param[in] timeout the maximum time to block in milliseconds, -1 ==
570
* forever, 0 == do not block
571
*
572
* @return 0 if no work to do, < 0 if error, or 1 if work was done.
573
*/
574
PN_EXTERN
int
pn_messenger_work
(
pn_messenger_t
*messenger,
int
timeout);
575
576
/**
577
* Interrupt a messenger object that may be blocking in another
578
* thread.
579
*
580
* The messenger interface is single-threaded. This is the only
581
* messenger function intended to be concurrently called from another
582
* thread. It will interrupt any messenger function which is currently
583
* blocking and cause it to return with a status of ::PN_INTR.
584
*
585
* @param[in] messenger the Messenger to interrupt
586
*/
587
PN_EXTERN
int
pn_messenger_interrupt
(
pn_messenger_t
*messenger);
588
589
/**
590
* Send messages from a messenger's outgoing queue.
591
*
592
* If a messenger is in blocking mode (see
593
* ::pn_messenger_is_blocking()), this operation will block until N
594
* messages have been sent from the outgoing queue. A value of -1 for
595
* N means "all messages in the outgoing queue". See below for a full
596
* definition of what sent from the outgoing queue means.
597
*
598
* Any blocking will end once the messenger's configured timeout (if
599
* any) has been reached. When this happens an error code of
600
* ::PN_TIMEOUT is returned.
601
*
602
* If the messenger is in non blocking mode, this call will return an
603
* error code of ::PN_INPROGRESS if it is unable to send the requested
604
* number of messages without blocking.
605
*
606
* A message is considered to be sent from the outgoing queue when its
607
* status has been fully determined. This does not necessarily mean
608
* the message was successfully sent to the final recipient though,
609
* for example of the receiver rejects the message, the final status
610
* will be ::PN_STATUS_REJECTED. Similarly, if a message is sent to an
611
* invalid address, it may be removed from the outgoing queue without
612
* ever even being transmitted. In this case the final status will be
613
* ::PN_STATUS_ABORTED.
614
*
615
* @param[in] messenger a messenger object
616
* @param[in] n the number of messages to send
617
*
618
* @return an error code or zero on success
619
* @see error.h
620
*/
621
PN_EXTERN
int
pn_messenger_send
(
pn_messenger_t
*messenger,
int
n);
622
623
/**
624
* Retrieve messages into a messenger's incoming queue.
625
*
626
* Instructs a messenger to receive up to @c limit messages into the
627
* incoming message queue of a messenger. If @c limit is -1, the
628
* messenger will receive as many messages as it can buffer
629
* internally. If the messenger is in blocking mode, this call will
630
* block until at least one message is available in the incoming
631
* queue.
632
*
633
* Each call to pn_messenger_recv replaces the previous receive
634
* operation, so pn_messenger_recv(messenger, 0) will cancel any
635
* outstanding receive.
636
*
637
* After receiving messages onto your incoming queue use
638
* ::pn_messenger_get() to access message content.
639
*
640
* @param[in] messenger the messenger
641
* @param[in] limit the maximum number of messages to receive or -1 to
642
* to receive as many messages as it can buffer
643
* internally.
644
* @return an error code or zero on success
645
* @see error.h
646
*/
647
PN_EXTERN
int
pn_messenger_recv
(
pn_messenger_t
*messenger,
int
limit);
648
649
/**
650
* Get the capacity of the incoming message queue of a messenger.
651
*
652
* Note this count does not include those messages already available
653
* on the incoming queue (@see pn_messenger_incoming()). Rather it
654
* returns the number of incoming queue entries available for
655
* receiving messages.
656
*
657
* @param[in] messenger the messenger
658
*/
659
PN_EXTERN
int
pn_messenger_receiving
(
pn_messenger_t
*messenger);
660
661
/**
662
* Get the next message from the head of a messenger's incoming queue.
663
*
664
* The get operation copies the message data from the head of the
665
* messenger's incoming queue into the provided ::pn_message_t object.
666
* If provided ::pn_message_t pointer is NULL, the head essage will be
667
* discarded. This operation will return ::PN_EOS if there are no
668
* messages left on the incoming queue.
669
*
670
* @param[in] messenger a messenger object
671
* @param[out] message upon return contains the message from the head of the queue
672
* @return an error code or zero on success
673
* @see error.h
674
*/
675
PN_EXTERN
int
pn_messenger_get
(
pn_messenger_t
*messenger,
pn_message_t
*message);
676
677
/**
678
* Get a tracker for the message most recently retrieved by
679
* ::pn_messenger_get().
680
*
681
* A tracker for an incoming message allows you to accept or reject
682
* the associated message. It can also be used for cumulative
683
* accept/reject operations for the associated message and all prior
684
* messages as well.
685
*
686
* @param[in] messenger a messenger object
687
* @return a pn_tracker_t or an undefined value if pn_messenger_get
688
* has never been called for the given messenger
689
*/
690
PN_EXTERN
pn_tracker_t
pn_messenger_incoming_tracker
(
pn_messenger_t
*messenger);
691
692
/**
693
* Get the subscription of the message most recently retrieved by ::pn_messenger_get().
694
*
695
* This operation will return NULL if ::pn_messenger_get() has never
696
* been succesfully called.
697
*
698
* @param[in] messenger a messenger object
699
* @return a pn_subscription_t or NULL
700
*/
701
PN_EXTERN
pn_subscription_t
*
pn_messenger_incoming_subscription
(
pn_messenger_t
*messenger);
702
703
/**
704
* Indicates that an accept or reject should operate cumulatively.
705
*/
706
#define PN_CUMULATIVE (0x1)
707
708
/**
709
* Signal successful processing of message(s).
710
*
711
* With no flags this operation will signal the sender that the
712
* message referenced by the tracker was accepted. If the
713
* PN_CUMULATIVE flag is set, this operation will also reject all
714
* pending messages prior to the message indicated by the tracker.
715
*
716
* Note that when a message is accepted or rejected multiple times,
717
* either explicitly, or implicitly through use of the ::PN_CUMULATIVE
718
* flag, only the first outcome applies. For example if a sequence of
719
* three messages are received: M1, M2, M3, and M2 is rejected, and M3
720
* is cumulatively accepted, M2 will remain rejected and only M1 and
721
* M3 will be considered accepted.
722
*
723
* @param[in] messenger a messenger object
724
* @param[in] tracker an incoming tracker
725
* @param[in] flags 0 or PN_CUMULATIVE
726
* @return an error code or zero on success
727
* @see error.h
728
*/
729
PN_EXTERN
int
pn_messenger_accept
(
pn_messenger_t
*messenger, pn_tracker_t tracker,
int
flags);
730
731
/**
732
* Signal unsuccessful processing of message(s).
733
*
734
* With no flags this operation will signal the sender that the
735
* message indicated by the tracker was rejected. If the PN_CUMULATIVE
736
* flag is used this operation will also reject all pending messages
737
* prior to the message indicated by the tracker.
738
*
739
* Note that when a message is accepted or rejected multiple times,
740
* either explicitly, or implicitly through use of the ::PN_CUMULATIVE
741
* flag, only the first outcome applies. For example if a sequence of
742
* three messages are received: M1, M2, M3, and M2 is accepted, and M3
743
* is cumulatively rejected, M2 will remain accepted and only M1 and
744
* M3 will be considered rejected.
745
*
746
* @param[in] messenger a messenger object
747
* @param[in] tracker an incoming tracker
748
* @param[in] flags 0 or PN_CUMULATIVE
749
* @return an error code or zero on success
750
* @see error.h
751
*/
752
PN_EXTERN
int
pn_messenger_reject
(
pn_messenger_t
*messenger, pn_tracker_t tracker,
int
flags);
753
754
/**
755
* Get the number of messages in the outgoing message queue of a
756
* messenger.
757
*
758
* @param[in] messenger a messenger object
759
* @return the outgoing queue depth
760
*/
761
PN_EXTERN
int
pn_messenger_outgoing
(
pn_messenger_t
*messenger);
762
763
/**
764
* Get the number of messages in the incoming message queue of a messenger.
765
*
766
* @param[in] messenger a messenger object
767
* @return the incoming queue depth
768
*/
769
PN_EXTERN
int
pn_messenger_incoming
(
pn_messenger_t
*messenger);
770
771
//! Adds a routing rule to a Messenger's internal routing table.
772
//!
773
//! The route procedure may be used to influence how a messenger will
774
//! internally treat a given address or class of addresses. Every call
775
//! to the route procedure will result in messenger appending a routing
776
//! rule to its internal routing table.
777
//!
778
//! Whenever a message is presented to a messenger for delivery, it
779
//! will match the address of this message against the set of routing
780
//! rules in order. The first rule to match will be triggered, and
781
//! instead of routing based on the address presented in the message,
782
//! the messenger will route based on the address supplied in the rule.
783
//!
784
//! The pattern matching syntax supports two types of matches, a '%'
785
//! will match any character except a '/', and a '*' will match any
786
//! character including a '/'.
787
//!
788
//! A routing address is specified as a normal AMQP address, however it
789
//! may additionally use substitution variables from the pattern match
790
//! that triggered the rule.
791
//!
792
//! Any message sent to "foo" will be routed to "amqp://foo.com":
793
//!
794
//! pn_messenger_route("foo", "amqp://foo.com");
795
//!
796
//! Any message sent to "foobar" will be routed to
797
//! "amqp://foo.com/bar":
798
//!
799
//! pn_messenger_route("foobar", "amqp://foo.com/bar");
800
//!
801
//! Any message sent to bar/<path> will be routed to the corresponding
802
//! path within the amqp://bar.com domain:
803
//!
804
//! pn_messenger_route("bar/*", "amqp://bar.com/$1");
805
//!
806
//! Route all messages over TLS:
807
//!
808
//! pn_messenger_route("amqp:*", "amqps:$1")
809
//!
810
//! Supply credentials for foo.com:
811
//!
812
//! pn_messenger_route("amqp://foo.com/*", "amqp://user:password@foo.com/$1");
813
//!
814
//! Supply credentials for all domains:
815
//!
816
//! pn_messenger_route("amqp://*", "amqp://user:password@$1");
817
//!
818
//! Route all addresses through a single proxy while preserving the
819
//! original destination:
820
//!
821
//! pn_messenger_route("amqp://%/*", "amqp://user:password@proxy/$1/$2");
822
//!
823
//! Route any address through a single broker:
824
//!
825
//! pn_messenger_route("*", "amqp://user:password@broker/$1");
826
//!
827
//! @param[in] messenger the Messenger
828
//! @param[in] pattern a glob pattern
829
//! @param[in] address an address indicating alternative routing
830
//!
831
//! @return an error code or zero on success
832
//! @see error.h
833
PN_EXTERN
int
pn_messenger_route
(
pn_messenger_t
*messenger,
const
char
*pattern,
834
const
char
*address);
835
836
/**
837
* Rewrite message addresses prior to transmission.
838
*
839
* This operation is similar to pn_messenger_route, except that the
840
* destination of the message is determined before the message address
841
* is rewritten.
842
*
843
* The outgoing address is only rewritten after routing has been
844
* finalized. If a message has an outgoing address of
845
* "amqp://0.0.0.0:5678", and a rewriting rule that changes its
846
* outgoing address to "foo", it will still arrive at the peer that
847
* is listening on "amqp://0.0.0.0:5678", but when it arrives there,
848
* the receiver will see its outgoing address as "foo".
849
*
850
* The default rewrite rule removes username and password from
851
* addresses before they are transmitted.
852
*
853
* @param[in] messenger a messenger object
854
* @param[in] pattern a glob pattern to select messages
855
* @param[in] address an address indicating outgoing address rewrite
856
* @return an error code or zero on success
857
*/
858
PN_EXTERN
int
pn_messenger_rewrite
(
pn_messenger_t
*messenger,
const
char
*pattern,
859
const
char
*address);
860
861
/**
862
* Extract @link pn_selectable_t selectables @endlink from a passive
863
* messenger.
864
*
865
* A messenger that is in passive mode (see
866
* ::pn_messenger_is_passive()) will never attempt to perform any I/O
867
* internally, but instead make its internal file descriptors
868
* available for external processing via the
869
* ::pn_messenger_selectable() operation.
870
*
871
* An application wishing to perform I/O on behalf of a passive
872
* messenger must extract all available selectables by calling this
873
* operation until it returns NULL. The ::pn_selectable_t interface
874
* may then be used by the application to perform I/O outside the
875
* messenger.
876
*
877
* All selectables returned by this operation must be serviced until
878
* they reach a terminal state and then freed. See
879
* ::pn_selectable_is_terminal() for more details.
880
*
881
* By default any given selectable will only ever be returned once by
882
* this operation, however if the selectable's registered flag is set
883
* to true (see ::pn_selectable_set_registered()), then the selectable
884
* will be returned whenever its interest set may have changed.
885
*
886
* @param[in] messenger a messenger object
887
* @return the next selectable, or NULL if there are none left
888
*/
889
PN_EXTERN
pn_selectable_t
*
pn_messenger_selectable
(
pn_messenger_t
*messenger);
890
891
/**
892
* Get the nearest deadline for selectables associated with a messenger.
893
*
894
* @param[in] messenger a messenger object
895
* @return the nearest deadline
896
*/
897
PN_EXTERN
pn_timestamp_t
pn_messenger_deadline
(
pn_messenger_t
*messenger);
898
899
/**
900
* @}
901
*/
902
903
#ifdef __cplusplus
904
}
905
#endif
906
907
#endif
/* messenger.h */
Generated on Thu Jul 10 2014 02:10:59 for proton by
1.8.3.1