proton  0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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/&lt;path&gt; 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  */
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  */
898 
899 /**
900  * @}
901  */
902 
903 #ifdef __cplusplus
904 }
905 #endif
906 
907 #endif /* messenger.h */