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