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