proton  0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros 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 
28 #ifdef __cplusplus
29 extern "C" {
30 #endif
31 
32 /** @file
33  * The messenger API provides a high level interface for sending and
34  * receiving AMQP messages.
35  */
36 
37 typedef struct pn_messenger_t pn_messenger_t; /**< Messenger*/
38 typedef struct pn_subscription_t pn_subscription_t; /**< Subscription*/
39 typedef int64_t pn_tracker_t;
40 
41 typedef enum {
50 } pn_status_t;
51 
52 /** Construct a new Messenger with the given name. The name is global.
53  * If a NULL name is supplied, a UUID based name will be chosen.
54  *
55  * @param[in] name the name of the messenger or NULL
56  *
57  * @return pointer to a new Messenger
58  */
59 PN_EXTERN pn_messenger_t *pn_messenger(const char *name);
60 
61 /** Retrieves the name of a Messenger.
62  *
63  * @param[in] messenger the messenger
64  *
65  * @return the name of the messenger
66  */
67 PN_EXTERN const char *pn_messenger_name(pn_messenger_t *messenger);
68 
69 /** Sets the path that will be used to get the certificate
70  * that will be used to identify this messenger to its
71  * peers. The validity of the path is not checked by
72  * this function.
73  *
74  * @param[in] messenger the messenger
75  * @param[in] certificate a path to a certificate file
76  *
77  * @return an error code of zero if there is no error
78  */
79 PN_EXTERN int pn_messenger_set_certificate(pn_messenger_t *messenger, const char *certificate);
80 
81 /** Return the certificate path. This value may be set by
82  * pn_messenger_set_certificate. The default certificate
83  * path is null.
84  *
85  * @param[in] messenger the messenger
86  * @return the certificate file path
87  */
89 
90 /** Provides the private key that was used to sign the certificate.
91  * See ::pn_messenger_set_certificate
92  *
93  * @param[in] messenger the Messenger
94  * @param[in] private_key a path to a private key file
95  *
96  * @return an error code of zero if there is no error
97  */
98 PN_EXTERN int pn_messenger_set_private_key(pn_messenger_t *messenger, const char *private_key);
99 
100 /** Gets the private key file for a Messenger.
101  *
102  * @param[in] messenger the messenger
103  * @return the private key file path
104  */
106 
107 /** Sets the private key password for a Messenger.
108  *
109  * @param[in] messenger the messenger
110  * @param[in] password the password for the private key file
111  *
112  * @return an error code of zero if there is no error
113  */
114 PN_EXTERN int pn_messenger_set_password(pn_messenger_t *messenger, const char *password);
115 
116 /** Gets the private key file password for a Messenger.
117  *
118  * @param[in] messenger the messenger
119  * @return password for the private key file
120  */
121 PN_EXTERN const char *pn_messenger_get_password(pn_messenger_t *messenger);
122 
123 /** Sets the trusted certificates database for a Messenger. Messenger
124  * will use this database to validate the certificate provided by the
125  * peer.
126  *
127  * @param[in] messenger the messenger
128  * @param[in] cert_db a path to the certificates database
129  *
130  * @return an error code of zero if there is no error
131  */
132 PN_EXTERN int pn_messenger_set_trusted_certificates(pn_messenger_t *messenger, const char *cert_db);
133 
134 /** Gets the trusted certificates database for a Messenger.
135  *
136  * @param[in] messenger the messenger
137  * @return path to the trusted certificates database
138  */
140 
141 /** Any messenger call that blocks during execution will stop
142  * blocking and return control when this timeout is reached,
143  * if you have set it to a value greater than zero.
144  * Expressed in milliseconds.
145  *
146  * @param[in] messenger the messenger
147  * @param[in] timeout the new timeout for the messenger, in milliseconds
148  *
149  * @return an error code or zero if there is no error
150  */
151 PN_EXTERN int pn_messenger_set_timeout(pn_messenger_t *messenger, int timeout);
152 
153 /** Retrieves the timeout for a Messenger.
154  *
155  * @param[in] messenger the messenger
156  *
157  * @return the timeout for the messenger, in milliseconds
158  */
160 
161 /** Accessor for messenger blocking mode.
162  *
163  * @param[in] messenger the messenger
164  *
165  * @return true if blocking has been enabled.
166  */
168 
169 /** Enable or disable blocking behavior during calls to
170  * pn_messenger_send and pn_messenger_recv.
171  *
172  * @param[in] messenger the messenger
173  *
174  * @return true if blocking has been enabled.
175  */
176 PN_EXTERN int pn_messenger_set_blocking(pn_messenger_t *messenger, bool blocking);
177 
178 /** Frees a Messenger.
179  *
180  * @param[in] messenger the messenger to free, no longer valid on
181  * return
182  */
184 
185 /** Return the code for the most recent error,
186  * initialized to zero at messenger creation.
187  * The error number is "sticky" i.e. are not reset to 0
188  * at the end of successful API calls.
189  *
190  * @param[in] messenger the messenger to check for errors
191  *
192  * @return an error code or zero if there is no error
193  * @see error.h
194  */
196 
197 /** Returns a pointer to a pn_error_t. The pn_error_* API
198  * allows you to access the text, error number, and lets you
199  * set or clear the error code explicitly.
200  *
201  * @param[in] messenger the messenger to check for errors
202  *
203  * @return a pointer to the messenger's error descriptor
204  * @see error.h
205  */
207 
208 /** Returns the size of the incoming window that was
209  * set with pn_messenger_set_incoming_window. The
210  * default is 0.
211  *
212  * @param[in] messenger the messenger
213  *
214  * @return the outgoing window
215  */
217 
218 /** The size of the outgoing window limits the number of messages whose
219  * status you can check with a tracker. A message enters this window
220  * when you call pn_messenger_put on the message. If your outgoing window
221  * size is 10, and you call pn_messenger_put 12, new status information
222  * will no longer be available for the first 2 messages.
223  *
224  * @param[in] messenger the Messenger
225  * @param[in] window the number of deliveries to track
226  *
227  * @return an error or zero on success
228  * @see error.h
229  */
230 PN_EXTERN int pn_messenger_set_outgoing_window(pn_messenger_t *messenger, int window);
231 
232 /** Returns the size of the incoming window that was
233  * set with pn_messenger_set_incoming_window.
234  * The default is 0.
235  *
236  * @param[in] messenger the Messenger
237  *
238  * @return the incoming window
239  */
241 
242 /** The size of your incoming window limits the number of messages
243  * that can be accepted or rejected using trackers. Messages do
244  * not enter this window when they have been received (pn_messenger_recv)
245  * onto you incoming queue.
246  *
247  * Messages enter this window only when you
248  * take them into your application using pn_messenger_get.
249  * If your incoming window size is N, and you get N+1 messages without
250  * explicitly accepting or rejecting the oldest message, then it will be
251  * implicitly accepted when it falls off the edge of the incoming window.
252  *
253  * @param[in] messenger the Messenger
254  * @param[in] window the number of deliveries to track
255  *
256  * @return an error or zero on success
257  * @see error.h
258  */
259 PN_EXTERN int pn_messenger_set_incoming_window(pn_messenger_t *messenger, int window);
260 
261 /** Currently a no-op placeholder.
262  * For future compatibility, do not send or receive messages
263  * before starting the messenger.
264  *
265  * @param[in] messenger the messenger to start
266  *
267  * @return an error code or zero on success
268  * @see error.h
269  */
271 
272 /** Stops a messenger. A messenger cannot send or
273  * receive messages after it is stopped. The messenger may require
274  * some time to stop if it is busy, and in that case will return
275  * PN_INPROGRESS. In that case, call pn_messenger_stopped to see
276  * if it has fully stopped.
277  *
278  * @param[in] messenger the messenger to stop
279  *
280  * @return an error code or zero on success
281  * @see error.h
282  */
284 
285 /** Returns true if a messenger is in the stopped state.
286  * This function does not block.
287  *
288  * @param[in] messenger the messenger to stop
289  *
290  */
292 
293 /** Subscribes a messenger to messages from the specified source.
294  *
295  * @param[in] messenger the messenger to subscribe
296  * @param[in] source
297  *
298  * @return a subscription
299  */
300 PN_EXTERN pn_subscription_t *pn_messenger_subscribe(pn_messenger_t *messenger, const char *source);
301 
303 
305 
307 
308 /** Puts the message onto the messenger's outgoing queue.
309  * The message may also be sent if transmission would not cause
310  * blocking. This call will not block.
311  *
312  * @param[in] messenger the messenger
313  * @param[in] msg the message to put on the outgoing queue
314  *
315  * @return an error code or zero on success
316  * @see error.h
317  */
319 
320 /** Find the current delivery status of the outgoing message
321  * associated with this tracker, as long as the message is still
322  * within your outgoing window.within your outgoing window.
323  *
324  * @param[in] messenger the messenger
325  * @param[in] tracker the tracker identifying the delivery
326  *
327  * @return a status code for the delivery
328  */
329 PN_EXTERN pn_status_t pn_messenger_status(pn_messenger_t *messenger, pn_tracker_t tracker);
330 
331 /** Checks if the delivery associated with the given tracker is still
332  * waiting to be sent.
333  *
334  * @param[in] messenger the messenger
335  * @param[in] tracker the tracker identifying the delivery
336  *
337  * @return true if delivery is still buffered
338  */
339 PN_EXTERN bool pn_messenger_buffered(pn_messenger_t *messenger, pn_tracker_t tracker);
340 
341 /** Frees a Messenger from tracking the status associated with a given
342  * tracker. Use the PN_CUMULATIVE flag to indicate everything up to
343  * (and including) the given tracker.
344  *
345  * @param[in] messenger the Messenger
346  * @param[in] tracker identifies a delivery
347  * @param[in] flags 0 or PN_CUMULATIVE
348  *
349  * @return an error code or zero on success
350  * @see error.h
351  */
352 PN_EXTERN int pn_messenger_settle(pn_messenger_t *messenger, pn_tracker_t tracker, int flags);
353 
354 /** Returns a tracker for the outgoing message most recently given
355  * to pn_messenger_put. Use this tracker with pn_messenger_status
356  * to determine the delivery status of the message, as long as the
357  * message is still within your outgoing window.
358  *
359  * @param[in] messenger the messenger
360  *
361  * @return a pn_tracker_t or an undefined value if pn_messenger_get
362  * has never been called for the given messenger
363  */
365 
366 /** Sends or receives any outstanding messages queued for a messenger.
367  * This will block for the indicated timeout.
368  *
369  * @param[in] messenger the Messenger
370  * @param[in] timeout the maximum time to block in milliseconds, -1 ==
371  * forever, 0 == do not block
372  *
373  * @return 0 if no work to do, < 0 if error, or 1 if work was done.
374  */
375 PN_EXTERN int pn_messenger_work(pn_messenger_t *messenger, int timeout);
376 
377 /** The messenger interface is single-threaded.
378  * This is the only messenger function intended to be called
379  * from outside of the messenger thread.
380  * It will interrupt any messenger function which is currently blocking.
381  *
382  * @param[in] messenger the Messenger
383  */
385 
386 /** If blocking has been set with pn_messenger_set_blocking, this call
387  * will block until N messages have been sent. A value of -1 for N means
388  * "all messages in the outgoing queue".
389  *
390  * In addition, if a nonzero size has been set for the outgoing window,
391  * this call will block until all messages within that window have
392  * been settled, or until all N messages have been settled, whichever
393  * comes first.
394  *
395  * Any blocking will end upon timeout, if one has been set by
396  * pn_messenger_timeout.
397  *
398  * If blocking has not been enabled, this call will stop transmitting
399  * messages when further transmission would require blocking, or when
400  * the outgoing queue is empty, or when n messages have been sent.
401  *
402  * @param[in] messenger the messager
403  * @param[in] n the number of messages to send
404  *
405  * @return an error code or zero on success
406  * @see error.h
407  */
408 PN_EXTERN int pn_messenger_send(pn_messenger_t *messenger, int n);
409 
410 /** Instructs the messenger to receives up to limit messages into the
411  * incoming message queue of a messenger. If limit is -1, Messenger
412  * will receive as many messages as it can buffer internally. If the
413  * messenger is in blocking mode, this call will block until at least
414  * one message is available in the incoming queue.
415  *
416  * Each call to pn_messenger_recv replaces the previous receive
417  * operation, so pn_messenger_recv(messenger, 0) will cancel any
418  * outstanding receive.
419  *
420  * @param[in] messenger the messenger
421  * @param[in] limit the maximum number of messages to receive or -1 to
422  * to receive as many messages as it can buffer
423  * internally.
424  *
425  * After receiving messages onto your incoming queue
426  * use pn_messenger_get to bring messages into your application code.
427  *
428  * @return an error code or zero on success
429  * @see error.h
430  */
431 PN_EXTERN int pn_messenger_recv(pn_messenger_t *messenger, int limit);
432 
433 /** Returns the capacity of the incoming message queue of
434  * messenger. Note this count does not include those messages already
435  * available on the incoming queue (@see
436  * pn_messenger_incoming()). Rather it returns the number of incoming
437  * queue entries available for receiving messages
438  *
439  * @param[in] messenger the messenger
440  */
442 
443 /** Pop the oldest message off your incoming message queue,
444  * and copy it into the given message structure.
445  * If the given pointer to a message structure is NULL,
446  * the popped message is discarded.
447  * Returns PN_EOS if there are no messages to get.
448  * Returns an error code only if there is a problem in
449  * decoding the message.
450  *
451  * @param[in] messenger the messenger
452  * @param[out] msg upon return contains the message from the head of the queue
453  *
454  * @return an error code or zero on success
455  * @see error.h
456  */
458 
459 /** Returns a tracker for the message most recently fetched by
460  * pn_messenger_get. The tracker allows you to accept or reject its
461  * message, or its message plus all prior messages that are still within
462  * your incoming window.
463  *
464  * @param[in] messenger the messenger
465  *
466  * @return a pn_tracker_t or an undefined value if pn_messenger_get
467  * has never been called for the given messenger
468  */
470 
471 /** Returns a pointer to the subscription of the message returned by the
472  * most recent call to pn_messenger_get, or NULL if pn_messenger_get
473  * has not yet been called.
474  *
475  * @param[in] messenger the messenger
476  *
477  * @return a pn_subscription_t or NULL if pn_messenger_get
478  * has never been called for the given messenger
479  */
481 
482 #define PN_CUMULATIVE (0x1)
483 
484 /** Signal the sender that you have acted on the message
485  * pointed to by the tracker. If the PN_CUMULATIVE flag is set, all
486  * messages prior to the tracker will also be accepted, back to the
487  * beginning of your incoming window.
488  *
489  * @param[in] messenger the messenger
490  * @param[in] tracker an incoming tracker
491  * @param[in] flags 0 or PN_CUMULATIVE
492  *
493  * @return an error code or zero on success
494  * @see error.h
495  */
496 PN_EXTERN int pn_messenger_accept(pn_messenger_t *messenger, pn_tracker_t tracker, int flags);
497 
498 /** Rejects the message indicated by the tracker. If the PN_CUMULATIVE
499  * flag is used this call will also reject all prior messages that
500  * have not already been settled. The semantics of message rejection
501  * are application-specific.
502  *
503  * @param[in] messenger the Messenger
504  * @param[in] tracker an incoming tracker
505  * @param[in] flags 0 or PN_CUMULATIVE
506  *
507  * @return an error code or zero on success
508  * @see error.h
509  */
510 PN_EXTERN int pn_messenger_reject(pn_messenger_t *messenger, pn_tracker_t tracker, int flags);
511 
512 /** Returns the number of messages in the outgoing message queue of a messenger.
513  *
514  * @param[in] messenger the Messenger
515  *
516  * @return the outgoing queue depth
517  */
519 
520 /** Returns the number of messages in the incoming message queue of a messenger.
521  *
522  * @param[in] messenger the Messenger
523  *
524  * @return the incoming queue depth
525  */
527 
528 //! Adds a routing rule to a Messenger's internal routing table.
529 //!
530 //! The route procedure may be used to influence how a messenger will
531 //! internally treat a given address or class of addresses. Every call
532 //! to the route procedure will result in messenger appending a routing
533 //! rule to its internal routing table.
534 //!
535 //! Whenever a message is presented to a messenger for delivery, it
536 //! will match the address of this message against the set of routing
537 //! rules in order. The first rule to match will be triggered, and
538 //! instead of routing based on the address presented in the message,
539 //! the messenger will route based on the address supplied in the rule.
540 //!
541 //! The pattern matching syntax supports two types of matches, a '%'
542 //! will match any character except a '/', and a '*' will match any
543 //! character including a '/'.
544 //!
545 //! A routing address is specified as a normal AMQP address, however it
546 //! may additionally use substitution variables from the pattern match
547 //! that triggered the rule.
548 //!
549 //! Any message sent to "foo" will be routed to "amqp://foo.com":
550 //!
551 //! pn_messenger_route("foo", "amqp://foo.com");
552 //!
553 //! Any message sent to "foobar" will be routed to
554 //! "amqp://foo.com/bar":
555 //!
556 //! pn_messenger_route("foobar", "amqp://foo.com/bar");
557 //!
558 //! Any message sent to bar/<path> will be routed to the corresponding
559 //! path within the amqp://bar.com domain:
560 //!
561 //! pn_messenger_route("bar/*", "amqp://bar.com/$1");
562 //!
563 //! Route all messages over TLS:
564 //!
565 //! pn_messenger_route("amqp:*", "amqps:$1")
566 //!
567 //! Supply credentials for foo.com:
568 //!
569 //! pn_messenger_route("amqp://foo.com/*", "amqp://user:password@foo.com/$1");
570 //!
571 //! Supply credentials for all domains:
572 //!
573 //! pn_messenger_route("amqp://*", "amqp://user:password@$1");
574 //!
575 //! Route all addresses through a single proxy while preserving the
576 //! original destination:
577 //!
578 //! pn_messenger_route("amqp://%/*", "amqp://user:password@proxy/$1/$2");
579 //!
580 //! Route any address through a single broker:
581 //!
582 //! pn_messenger_route("*", "amqp://user:password@broker/$1");
583 //!
584 //! @param[in] messenger the Messenger
585 //! @param[in] pattern a glob pattern
586 //! @param[in] address an address indicating alternative routing
587 //!
588 //! @return an error code or zero on success
589 //! @see error.h
590 PN_EXTERN int pn_messenger_route(pn_messenger_t *messenger, const char *pattern,
591  const char *address);
592 
593 /** Similar to pn_messenger_route, except that the destination of
594  * the message is determined before the message address is rewritten.
595  *
596  * The outgoing address is only rewritten after routing has been
597  * finalized. If a message has an outgoing address of
598  * "amqp://0.0.0.0:5678", and a rewriting rule that changes its
599  * outgoing address to "foo", it will still arrive at the peer that
600  * is listening on "amqp://0.0.0.0:5678", but when it arrives there,
601  * the receiver will see its outgoing address as "foo".
602  *
603  * The default rewrite rule removes username and password from addresses
604  * before they are transmitted.
605  *
606  * @param[in] messenger the Messenger
607  * @param[in] pattern a glob pattern to select messages
608  * @param[in] address an address indicating outgoing address rewrite
609  *
610  */
611 PN_EXTERN int pn_messenger_rewrite(pn_messenger_t *messenger, const char *pattern,
612  const char *address);
613 
614 #ifdef __cplusplus
615 }
616 #endif
617 
618 #endif /* messenger.h */
PN_EXTERN int pn_messenger_get_outgoing_window(pn_messenger_t *messenger)
Returns the size of the incoming window that was set with pn_messenger_set_incoming_window.
PN_EXTERN const char * pn_messenger_get_certificate(pn_messenger_t *messenger)
Return the certificate path.
PN_EXTERN const char * pn_messenger_get_private_key(pn_messenger_t *messenger)
Gets the private key file for a Messenger.
Definition: messenger.h:49
Definition: messenger.h:48
Definition: messenger.h:47
int64_t pn_tracker_t
Definition: messenger.h:39
PN_EXTERN int pn_messenger_send(pn_messenger_t *messenger, int n)
If blocking has been set with pn_messenger_set_blocking, this call will block until N messages have b...
PN_EXTERN int pn_messenger_set_private_key(pn_messenger_t *messenger, const char *private_key)
Provides the private key that was used to sign the certificate.
PN_EXTERN pn_error_t * pn_messenger_error(pn_messenger_t *messenger)
Returns a pointer to a pn_error_t.
PN_EXTERN int pn_messenger_interrupt(pn_messenger_t *messenger)
The messenger interface is single-threaded.
PN_EXTERN int pn_messenger_set_blocking(pn_messenger_t *messenger, bool blocking)
Enable or disable blocking behavior during calls to pn_messenger_send and pn_messenger_recv.
PN_EXTERN const char * pn_subscription_address(pn_subscription_t *sub)
PN_EXTERN const char * pn_messenger_get_trusted_certificates(pn_messenger_t *messenger)
Gets 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_get_timeout(pn_messenger_t *messenger)
Retrieves the timeout for a Messenger.
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 int pn_messenger_receiving(pn_messenger_t *messenger)
Returns the capacity of the incoming message queue of messenger.
PN_EXTERN int pn_messenger_stop(pn_messenger_t *messenger)
Stops a messenger.
pn_status_t
Definition: messenger.h:41
PN_EXTERN int pn_messenger_set_password(pn_messenger_t *messenger, const char *password)
Sets the private key password for a Messenger.
Definition: messenger.h:44
struct pn_messenger_t pn_messenger_t
Messenger.
Definition: messenger.h:37
PN_EXTERN int pn_messenger_set_timeout(pn_messenger_t *messenger, int timeout)
Any messenger call that blocks during execution will stop blocking and return control when this timeo...
Definition: messenger.h:46
Definition: messenger.h:43
PN_EXTERN void * pn_subscription_get_context(pn_subscription_t *sub)
PN_EXTERN int pn_messenger_put(pn_messenger_t *messenger, pn_message_t *msg)
Puts the message onto the messenger&#39;s outgoing queue.
PN_EXTERN bool pn_messenger_buffered(pn_messenger_t *messenger, pn_tracker_t tracker)
Checks if the delivery associated with the given tracker is still waiting to be sent.
PN_EXTERN pn_tracker_t pn_messenger_incoming_tracker(pn_messenger_t *messenger)
Returns a tracker for the message most recently fetched by pn_messenger_get.
struct pn_error_t pn_error_t
Definition: error.h:32
PN_EXTERN bool pn_messenger_is_blocking(pn_messenger_t *messenger)
Accessor for messenger blocking mode.
PN_EXTERN int pn_messenger_accept(pn_messenger_t *messenger, pn_tracker_t tracker, int flags)
Signal the sender that you have acted on the message pointed to by the tracker.
PN_EXTERN int pn_messenger_incoming(pn_messenger_t *messenger)
Returns the number of messages in the incoming message queue of a messenger.
Definition: messenger.h:42
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 pn_messenger_t * pn_messenger(const char *name)
Construct a new Messenger with the given name.
PN_EXTERN void pn_subscription_set_context(pn_subscription_t *sub, void *context)
Definition: messenger.h:45
PN_EXTERN int pn_messenger_get_incoming_window(pn_messenger_t *messenger)
Returns the size of the incoming window that was set with pn_messenger_set_incoming_window.
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 bool pn_messenger_stopped(pn_messenger_t *messenger)
Returns true if a messenger is in the stopped state.
PN_EXTERN int pn_messenger_outgoing(pn_messenger_t *messenger)
Returns the number of messages in the outgoing message queue of a messenger.
struct pn_message_t pn_message_t
Definition: message.h:38
PN_EXTERN pn_subscription_t * pn_messenger_incoming_subscription(pn_messenger_t *messenger)
Returns a pointer to the subscription of the message returned by the most recent call to pn_messenger...
PN_EXTERN int pn_messenger_recv(pn_messenger_t *messenger, int limit)
Instructs the messenger to receives up to limit messages into the incoming message queue of a messeng...
PN_EXTERN int pn_messenger_start(pn_messenger_t *messenger)
Currently a no-op placeholder.
PN_EXTERN int pn_messenger_set_outgoing_window(pn_messenger_t *messenger, int window)
The size of the outgoing window limits the number of messages whose status you can check with a track...
PN_EXTERN const char * pn_messenger_get_password(pn_messenger_t *messenger)
Gets the private key file password for a Messenger.
PN_EXTERN pn_status_t pn_messenger_status(pn_messenger_t *messenger, pn_tracker_t tracker)
Find the current delivery status of the outgoing message associated with this tracker, as long as the message is still within your outgoing window.within your outgoing window.
PN_EXTERN int pn_messenger_reject(pn_messenger_t *messenger, pn_tracker_t tracker, int flags)
Rejects the message indicated by the tracker.
#define PN_EXTERN
Definition: import_export.h:53
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_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_get(pn_messenger_t *messenger, pn_message_t *msg)
Pop the oldest message off your incoming message queue, and copy it into the given message structure...
PN_EXTERN int pn_messenger_errno(pn_messenger_t *messenger)
Return the code for the most recent error, initialized to zero at messenger creation.
PN_EXTERN int pn_messenger_set_incoming_window(pn_messenger_t *messenger, int window)
The size of your incoming window limits the number of messages that can be accepted or rejected using...
PN_EXTERN const char * pn_messenger_name(pn_messenger_t *messenger)
Retrieves the name 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 pn_tracker_t pn_messenger_outgoing_tracker(pn_messenger_t *messenger)
Returns a tracker for the outgoing message most recently given to pn_messenger_put.
PN_EXTERN int pn_messenger_rewrite(pn_messenger_t *messenger, const char *pattern, const char *address)
Similar to pn_messenger_route, except that the destination of the message is determined before the me...
struct pn_subscription_t pn_subscription_t
Subscription.
Definition: messenger.h:38