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 {
47 } pn_status_t;
48 
49 /** Construct a new Messenger with the given name. The name is global.
50  * If a NULL name is supplied, a UUID based name will be chosen.
51  *
52  * @param[in] name the name of the messenger or NULL
53  *
54  * @return pointer to a new Messenger
55  */
56 PN_EXTERN pn_messenger_t *pn_messenger(const char *name);
57 
58 /** Retrieves the name of a Messenger.
59  *
60  * @param[in] messenger the messenger
61  *
62  * @return the name of the messenger
63  */
64 PN_EXTERN const char *pn_messenger_name(pn_messenger_t *messenger);
65 
66 /** Provides a certificate that will be used to identify the local
67  * Messenger to the peer.
68  *
69  * @param[in] messenger the messenger
70  * @param[in] certificate a path to a certificate file
71  *
72  * @return an error code of zero if there is no error
73  */
74 PN_EXTERN int pn_messenger_set_certificate(pn_messenger_t *messenger, const char *certificate);
75 
76 /** Gets the certificate file for a Messenger.
77  *
78  * @param[in] messenger the messenger
79  * @return the certificate file path
80  */
82 
83 /** Provides the private key that was used to sign the certificate.
84  * See ::pn_messenger_set_certificate
85  *
86  * @param[in] messenger the Messenger
87  * @param[in] private_key a path to a private key file
88  *
89  * @return an error code of zero if there is no error
90  */
91 PN_EXTERN int pn_messenger_set_private_key(pn_messenger_t *messenger, const char *private_key);
92 
93 /** Gets the private key file for a Messenger.
94  *
95  * @param[in] messenger the messenger
96  * @return the private key file path
97  */
99 
100 /** Sets the private key password for a Messenger.
101  *
102  * @param[in] messenger the messenger
103  * @param[in] password the password for the private key file
104  *
105  * @return an error code of zero if there is no error
106  */
107 PN_EXTERN int pn_messenger_set_password(pn_messenger_t *messenger, const char *password);
108 
109 /** Gets the private key file password for a Messenger.
110  *
111  * @param[in] messenger the messenger
112  * @return password for the private key file
113  */
114 PN_EXTERN const char *pn_messenger_get_password(pn_messenger_t *messenger);
115 
116 /** Sets the trusted certificates database for a Messenger. Messenger
117  * will use this database to validate the certificate provided by the
118  * peer.
119  *
120  * @param[in] messenger the messenger
121  * @param[in] cert_db a path to the certificates database
122  *
123  * @return an error code of zero if there is no error
124  */
125 PN_EXTERN int pn_messenger_set_trusted_certificates(pn_messenger_t *messenger, const char *cert_db);
126 
127 /** Gets the trusted certificates database for a Messenger.
128  *
129  * @param[in] messenger the messenger
130  * @return path to the trusted certificates database
131  */
133 
134 /** Sets the timeout for a Messenger. A negative timeout means
135  * infinite.
136  *
137  * @param[in] messenger the messenger
138  * @param[in] timeout the new timeout for the messenger, in milliseconds
139  *
140  * @return an error code or zero if there is no error
141  */
142 PN_EXTERN int pn_messenger_set_timeout(pn_messenger_t *messenger, int timeout);
143 
144 /** Retrieves the timeout for a Messenger.
145  *
146  * @param[in] messenger the messenger
147  *
148  * @return the timeout for the messenger, in milliseconds
149  */
151 
153 PN_EXTERN int pn_messenger_set_blocking(pn_messenger_t *messenger, bool blocking);
154 
155 /** Frees a Messenger.
156  *
157  * @param[in] messenger the messenger to free, no longer valid on
158  * return
159  */
161 
162 /** Returns the error code for the Messenger.
163  *
164  * @param[in] messenger the messenger to check for errors
165  *
166  * @return an error code or zero if there is no error
167  * @see error.h
168  */
170 
171 /** Returns the error info for a Messenger.
172  *
173  * @param[in] messenger the messenger to check for errors
174  *
175  * @return a pointer to the messenger's error descriptor
176  * @see error.h
177  */
179 
180 /** Gets the outgoing window for a Messenger. @see
181  * ::pn_messenger_set_outgoing_window
182  *
183  * @param[in] messenger the messenger
184  *
185  * @return the outgoing window
186  */
188 
189 /** Sets the outgoing window for a Messenger. If the outgoing window
190  * is set to a positive value, then after each call to
191  * pn_messenger_send, the Messenger will track the status of that
192  * many deliveries. @see ::pn_messenger_status
193  *
194  * @param[in] messenger the Messenger
195  * @param[in] window the number of deliveries to track
196  *
197  * @return an error or zero on success
198  * @see error.h
199  */
200 PN_EXTERN int pn_messenger_set_outgoing_window(pn_messenger_t *messenger, int window);
201 
202 /** Gets the incoming window for a Messenger. @see
203  * ::pn_messenger_set_incoming_window
204  *
205  * @param[in] messenger the Messenger
206  *
207  * @return the incoming window
208  */
210 
211 /** Sets the incoming window for a Messenger. If the incoming window
212  * is set to a positive value, then after each call to
213  * pn_messenger_accept or pn_messenger_reject, the Messenger will
214  * track the status of that many deliveries. @see
215  * ::pn_messenger_status
216  *
217  * @param[in] messenger the Messenger
218  * @param[in] window the number of deliveries to track
219  *
220  * @return an error or zero on success
221  * @see error.h
222  */
223 PN_EXTERN int pn_messenger_set_incoming_window(pn_messenger_t *messenger, int window);
224 
225 /** Starts a messenger. A messenger cannot send or recv messages until
226  * it is started.
227  *
228  * @param[in] messenger the messenger to start
229  *
230  * @return an error code or zero on success
231  * @see error.h
232  */
234 
235 /** Stops a messenger. A messenger cannot send or recv messages when
236  * it is stopped.
237  *
238  * @param[in] messenger the messenger to stop
239  *
240  * @return an error code or zero on success
241  * @see error.h
242  */
244 
246 
247 /** Subscribes a messenger to messages from the specified source.
248  *
249  * @param[in] messenger the messenger to subscribe
250  * @param[in] source
251  *
252  * @return a subscription
253  */
254 PN_EXTERN pn_subscription_t *pn_messenger_subscribe(pn_messenger_t *messenger, const char *source);
255 
257 
259 
260 /** Puts a message on the outgoing message queue for a messenger.
261  *
262  * @param[in] messenger the messenger
263  * @param[in] msg the message to put on the outgoing queue
264  *
265  * @return an error code or zero on success
266  * @see error.h
267  */
269 
270 /** Gets the last known remote state of the delivery associated with
271  * the given tracker.
272  *
273  * @param[in] messenger the messenger
274  * @param[in] tracker the tracker identify the delivery
275  *
276  * @return a status code for the delivery
277  */
278 PN_EXTERN pn_status_t pn_messenger_status(pn_messenger_t *messenger, pn_tracker_t tracker);
279 
280 /** Frees a Messenger from tracking the status associated with a given
281  * tracker. Use the PN_CUMULATIVE flag to indicate everything up to
282  * (and including) the given tracker.
283  *
284  * @param[in] messenger the Messenger
285  * @param[in] tracker identifies a delivery
286  * @param[in] flags 0 or PN_CUMULATIVE
287  *
288  * @return an error code or zero on success
289  * @see error.h
290  */
291 PN_EXTERN int pn_messenger_settle(pn_messenger_t *messenger, pn_tracker_t tracker, int flags);
292 
293 /** Gets the tracker for the message most recently provided to
294  * pn_messenger_put.
295  *
296  * @param[in] messenger the messenger
297  *
298  * @return a pn_tracker_t or an undefined value if pn_messenger_get
299  * has never been called for the given messenger
300  */
302 
303 /** Sends or receives any outstanding messages queued for a messenger.
304  * This will block for the indicated timeout.
305  *
306  * @param[in] messenger the Messenger
307  * @param[in] timeout the maximum time to block
308  */
309 PN_EXTERN int pn_messenger_work(pn_messenger_t *messenger, int timeout);
310 
311 /** Interrupts a messenger that is blocking. This method may be safely
312  * called from a different thread than the one that is blocking.
313  *
314  * @param[in] messenger the Messenger
315  */
317 
318 /** Sends messages in the outgoing message queue for a messenger. This
319  * call will block until the indicated number of messages have been
320  * sent. If n is -1 this call will block until all outgoing messages
321  * have been sent. If n is 0 then this call won't block.
322  *
323  * @param[in] messenger the messager
324  * @param[in] n the number of messages to send
325  *
326  * @return an error code or zero on success
327  * @see error.h
328  */
329 PN_EXTERN int pn_messenger_send(pn_messenger_t *messenger, int n);
330 
331 /** Instructs the messenger to receives up to limit messages into the
332  * incoming message queue of a messenger. If limit is -1, Messenger
333  * will receive as many messages as it can buffer internally. If the
334  * messenger is in blocking mode, this call will block until at least
335  * one message is available in the incoming queue.
336  *
337  * Each call to pn_messenger_recv replaces the previos receive
338  * operation, so pn_messenger_recv(messenger, 0) will cancel any
339  * outstanding receive.
340  *
341  * @param[in] messenger the messenger
342  * @param[in] limit the maximum number of messages to receive or -1 to
343  * to receive as many messages as it can buffer
344  * internally.
345  *
346  * @return an error code or zero on success
347  * @see error.h
348  */
349 PN_EXTERN int pn_messenger_recv(pn_messenger_t *messenger, int limit);
350 
351 /** Returns the number of messages currently being received by a
352  * messenger.
353  *
354  * @param[in] messenger the messenger
355  */
357 
358 /** Gets a message from the head of the incoming message queue of a
359  * messenger.
360  *
361  * @param[in] messenger the messenger
362  * @param[out] msg upon return contains the message from the head of the queue
363  *
364  * @return an error code or zero on success
365  * @see error.h
366  */
368 
369 /** Gets the tracker for the message most recently fetched by
370  * pn_messenger_get.
371  *
372  * @param[in] messenger the messenger
373  *
374  * @return a pn_tracker_t or an undefined value if pn_messenger_get
375  * has never been called for the given messenger
376  */
378 
380 
381 #define PN_CUMULATIVE (0x1)
382 
383 /** Accepts the incoming messages identified by the tracker. Use the
384  * PN_CUMULATIVE flag to accept everything prior to the supplied
385  * tracker.
386  *
387  * @param[in] messenger the messenger
388  * @param[in] tracker an incoming tracker
389  * @param[in] flags 0 or PN_CUMULATIVE
390  *
391  * @return an error code or zero on success
392  * @see error.h
393  */
394 PN_EXTERN int pn_messenger_accept(pn_messenger_t *messenger, pn_tracker_t tracker, int flags);
395 
396 /** Rejects the incoming messages identified by the tracker. Use the
397  * PN_CUMULATIVE flag to reject everything prior to the supplied
398  * tracker.
399  *
400  * @param[in] messenger the Messenger
401  * @param[in] tracker an incoming tracker
402  * @param[in] flags 0 or PN_CUMULATIVE
403  *
404  * @return an error code or zero on success
405  * @see error.h
406  */
407 PN_EXTERN int pn_messenger_reject(pn_messenger_t *messenger, pn_tracker_t tracker, int flags);
408 
409 /** Returns the number of messages in the outgoing message queue of a messenger.
410  *
411  * @param[in] messenger the Messenger
412  *
413  * @return the outgoing queue depth
414  */
416 
417 /** Returns the number of messages in the incoming message queue of a messenger.
418  *
419  * @param[in] messenger the Messenger
420  *
421  * @return the incoming queue depth
422  */
424 
425 /** Adds a routing rule to a Messenger's internal routing table.
426  *
427  * The route procedure may be used to influence how a messenger will
428  * internally treat a given address or class of addresses. Every call
429  * to the route procedure will result in messenger appending a routing
430  * rule to its internal routing table.
431  *
432  * Whenever a message is presented to a messenger for delivery, it
433  * will match the address of this message against the set of routing
434  * rules in order. The first rule to match will be triggered, and
435  * instead of routing based on the address presented in the message,
436  * the messenger will route based on the address supplied in the rule.
437  *
438  * The pattern matching syntax supports two types of matches, a '%'
439  * will match any character except a '/', and a '*' will match any
440  * character including a '/'.
441  *
442  * A routing address is specified as a normal AMQP address, however it
443  * may additionally use substitution variables from the pattern match
444  * that triggered the rule.
445  *
446  * Any message sent to "foo" will be routed to "amqp://foo.com":
447  *
448  * pn_messenger_route("foo", "amqp://foo.com");
449  *
450  * Any message sent to "foobar" will be routed to
451  * "amqp://foo.com/bar":
452  *
453  * pn_messenger_route("foobar", "amqp://foo.com/bar");
454  *
455  * Any message sent to bar/<path> will be routed to the corresponding
456  * path within the amqp://bar.com domain:
457  *
458  * pn_messenger_route("bar/*", "amqp://bar.com/$1");
459  *
460  * Route all messages over TLS:
461  *
462  * pn_messenger_route("amqp:*", "amqps:$1")
463  *
464  * Supply credentials for foo.com:
465  *
466  * pn_messenger_route("amqp://foo.com/*", "amqp://user:password@foo.com/$1");
467  *
468  * Supply credentials for all domains:
469  *
470  * pn_messenger_route("amqp://*", "amqp://user:password@$1");
471  *
472  * Route all addresses through a single proxy while preserving the
473  * original destination:
474  *
475  * pn_messenger_route("amqp://%/*", "amqp://user:password@proxy/$1/$2");
476  *
477  * Route any address through a single broker:
478  *
479  * pn_messenger_route("*", "amqp://user:password@broker/$1");
480  *
481  * @param[in] messenger the Messenger
482  * @param[in] pattern a glob pattern
483  * @param[in] address an address indicating alternative routing
484  *
485  * @return an error code or zero on success
486  * @see error.h
487  *
488  */
489 PN_EXTERN int pn_messenger_route(pn_messenger_t *messenger, const char *pattern,
490  const char *address);
491 
492 PN_EXTERN int pn_messenger_rewrite(pn_messenger_t *messenger, const char *pattern,
493  const char *address);
494 
495 #ifdef __cplusplus
496 }
497 #endif
498 
499 #endif /* messenger.h */