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
proton-c
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 Mon Jun 2 2014 22:59:05 for proton by
1.8.1.2