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 {
45 
46 typedef enum {
51 } pn_status_t;
52 
53 /** Construct a new Messenger with the given name. The name is global.
54  * If a NULL name is supplied, a UUID based name will be chosen.
55  *
56  * @param[in] name the name of the messenger or NULL
57  *
58  * @return pointer to a new Messenger
59  */
60 PN_EXTERN pn_messenger_t *pn_messenger(const char *name);
61 
62 /** Retrieves the name of a Messenger.
63  *
64  * @param[in] messenger the messenger
65  *
66  * @return the name of the messenger
67  */
68 PN_EXTERN const char *pn_messenger_name(pn_messenger_t *messenger);
69 
70 /** Sets the certificate file for a Messenger.
71  *
72  * @param[in] messenger the messenger
73  * @param[in] certificate a path to a certificate file
74  *
75  * @return an error code of zero if there is no error
76  */
77 PN_EXTERN int pn_messenger_set_certificate(pn_messenger_t *messenger, const char *certificate);
78 
79 /** Gets the certificate file fora Messenger.
80  *
81  * @param[in] messenger the messenger
82  * @return the certificate file path
83  */
85 
86 /** Sets the private key file for a Messenger.
87  *
88  * @param[in] messenger the Messenger
89  * @param[in] private_key a path to a private key file
90  *
91  * @return an error code of zero if there is no error
92  */
93 PN_EXTERN int pn_messenger_set_private_key(pn_messenger_t *messenger, const char *private_key);
94 
95 /** Gets the private key file for a Messenger.
96  *
97  * @param[in] messenger the messenger
98  * @return the private key file path
99  */
101 
102 /** Sets the private key password for a Messenger.
103  *
104  * @param[in] messenger the messenger
105  * @param[in] password the password for the private key file
106  *
107  * @return an error code of zero if there is no error
108  */
109 PN_EXTERN int pn_messenger_set_password(pn_messenger_t *messenger, const char *password);
110 
111 /** Gets the private key file password for a Messenger.
112  *
113  * @param[in] messenger the messenger
114  * @return password for the private key file
115  */
116 PN_EXTERN const char *pn_messenger_get_password(pn_messenger_t *messenger);
117 
118 /** Sets the trusted certificates database for a Messenger.
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 
152 /** Frees a Messenger.
153  *
154  * @param[in] messenger the messenger to free, no longer valid on
155  * return
156  */
158 
159 /** Returns the error code for the Messenger.
160  *
161  * @param[in] messenger the messenger to check for errors
162  *
163  * @return an error code or zero if there is no error
164  * @see error.h
165  */
167 
168 /** Returns the error info for a Messenger.
169  *
170  * @param[in] messenger the messenger to check for errors
171  *
172  * @return a descriptive error message or NULL if no error has
173  * occurred
174  */
175 PN_EXTERN const char *pn_messenger_error(pn_messenger_t *messenger);
176 
177 /** Gets the accept mode for a Messenger. @see
178  * ::pn_messenger_set_accept_mode
179  *
180  * @param[in] messenger the messenger
181  *
182  * @return one of PN_ACCEPT_MODE_AUTO or PN_ACCEPT_MODE_MANUAL
183  */
185 
186 /** Set the accept mode for a Messenger. If set to
187  * PN_ACCEPT_MODE_AUTO, the messenger will automatically accept every
188  * message as it is returned by pn_messenger_get(). If set to
189  * PN_ACCEPT_MODE_MANUAL, incoming messages must be manually accepted
190  * or rejected (either individually or cumulatively) via
191  * pn_messenger_accept() and/or pn_messenger_reject().
192  *
193  * @param[in] messenger the messenger to set the accept mode for
194  * @param[in] mode one of PN_ACCEPT_MODE_AUTO or PN_ACCEPT_MODE_MANUAL
195  *
196  * @return an error code or zero on success
197  * @see error.h
198  */
200 
201 /** Gets the outgoing window for a Messenger. @see
202  * ::pn_messenger_set_outgoing_window
203  *
204  * @param[in] messenger the messenger
205  *
206  * @return the outgoing window
207  */
209 
210 /** Sets the outgoing window for a Messenger. If the outgoing window
211  * is set to a positive value, then after each call to
212  * pn_messenger_send, the Messenger will track the status of that
213  * many deliveries. @see ::pn_messenger_status
214  *
215  * @param[in] messenger the Messenger
216  * @param[in] window the number of deliveries to track
217  *
218  * @return an error or zero on success
219  * @see error.h
220  */
221 PN_EXTERN int pn_messenger_set_outgoing_window(pn_messenger_t *messenger, int window);
222 
223 /** Gets the incoming window for a Messenger. @see
224  * ::pn_messenger_set_incoming_window
225  *
226  * @param[in] messenger the Messenger
227  *
228  * @return the incoming window
229  */
231 
232 /** Sets the incoming window for a Messenger. If the incoming window
233  * is set to a positive value, then after each call to
234  * pn_messenger_accept or pn_messenger_reject, the Messenger will
235  * track the status of that many deliveries. @see
236  * ::pn_messenger_status
237  *
238  * @param[in] messenger the Messenger
239  * @param[in] window the number of deliveries to track
240  *
241  * @return an error or zero on success
242  * @see error.h
243  */
244 PN_EXTERN int pn_messenger_set_incoming_window(pn_messenger_t *messenger, int window);
245 
246 /** Starts a messenger. A messenger cannot send or recv messages until
247  * it is started.
248  *
249  * @param[in] messenger the messenger to start
250  *
251  * @return an error code or zero on success
252  * @see error.h
253  */
255 
256 /** Stops a messenger. A messenger cannot send or recv messages when
257  * it is stopped.
258  *
259  * @param[in] messenger the messenger to stop
260  *
261  * @return an error code or zero on success
262  * @see error.h
263  */
265 
266 /** Subscribes a messenger to messages from the specified source.
267  *
268  * @param[in] messenger the messenger to subscribe
269  * @param[in] source
270  *
271  * @return a subscription
272  */
273 PN_EXTERN pn_subscription_t *pn_messenger_subscribe(pn_messenger_t *messenger, const char *source);
274 
276 
278 
279 /** Puts a message on the outgoing message queue for a messenger.
280  *
281  * @param[in] messenger the messenger
282  * @param[in] msg the message to put on the outgoing queue
283  *
284  * @return an error code or zero on success
285  * @see error.h
286  */
288 
289 /** Gets the last known remote state of the delivery associated with
290  * the given tracker.
291  *
292  * @param[in] messenger the messenger
293  * @param[in] tracker the tracker identify the delivery
294  *
295  * @return a status code for the delivery
296  */
297 PN_EXTERN pn_status_t pn_messenger_status(pn_messenger_t *messenger, pn_tracker_t tracker);
298 
299 /** Frees a Messenger from tracking the status associated with a given
300  * tracker. Use the PN_CUMULATIVE flag to indicate everything up to
301  * (and including) the given tracker.
302  *
303  * @param[in] messenger the Messenger
304  * @param[in] tracker identifies a delivery
305  * @param[in] flags 0 or PN_CUMULATIVE
306  *
307  * @return an error code or zero on success
308  * @see error.h
309  */
310 PN_EXTERN int pn_messenger_settle(pn_messenger_t *messenger, pn_tracker_t tracker, int flags);
311 
312 /** Gets the tracker for the message most recently provided to
313  * pn_messenger_put.
314  *
315  * @param[in] messenger the messenger
316  *
317  * @return a pn_tracker_t or an undefined value if pn_messenger_get
318  * has never been called for the given messenger
319  */
321 
322 /** Sends any messages in the outgoing message queue for a messenger.
323  * This will block until the messages have been sent.
324  *
325  * @param[in] messenger the messager
326  *
327  * @return an error code or zero on success
328  * @see error.h
329  */
331 
332 /** Receives up to n messages into the incoming message queue of a
333  * messenger. If n is -1, Messenger will be able to receive as many
334  * messages as it can buffer internally. Blocks until at least one
335  * message is available in the incoming queue.
336  *
337  * @param[in] messenger the messenger
338  * @param[in] n the maximum number of messages to receive or -1 to to
339  * receive as many messages as it can buffer internally.
340  *
341  * @return an error code or zero on success
342  * @see error.h
343  */
344 PN_EXTERN int pn_messenger_recv(pn_messenger_t *messenger, int n);
345 
346 /** Gets a message from the head of the incoming message queue of a
347  * messenger.
348  *
349  * @param[in] messenger the messenger
350  * @param[out] msg upon return contains the message from the head of the queue
351  *
352  * @return an error code or zero on success
353  * @see error.h
354  */
356 
357 /** Gets the tracker for the message most recently fetched by
358  * pn_messenger_get.
359  *
360  * @param[in] messenger the messenger
361  *
362  * @return a pn_tracker_t or an undefined value if pn_messenger_get
363  * has never been called for the given messenger
364  */
366 
368 
369 #define PN_CUMULATIVE (0x1)
370 
371 /** Accepts the incoming messages identified by the tracker. Use the
372  * PN_CUMULATIVE flag to accept everything prior to the supplied
373  * tracker.
374  *
375  * @param[in] messenger the messenger
376  * @param[in] tracker an incoming tracker
377  * @param[in] flags 0 or PN_CUMULATIVE
378  *
379  * @return an error code or zero on success
380  * @see error.h
381  */
382 PN_EXTERN int pn_messenger_accept(pn_messenger_t *messenger, pn_tracker_t tracker, int flags);
383 
384 /** Rejects the incoming messages identified by the tracker. Use the
385  * PN_CUMULATIVE flag to reject everything prior to the supplied
386  * tracker.
387  *
388  * @param[in] messenger the Messenger
389  * @param[in] tracker an incoming tracker
390  * @param[in] flags 0 or PN_CUMULATIVE
391  *
392  * @return an error code or zero on success
393  * @see error.h
394  */
395 PN_EXTERN int pn_messenger_reject(pn_messenger_t *messenger, pn_tracker_t tracker, int flags);
396 
397 /** Returns the number of messages in the outgoing message queue of a messenger.
398  *
399  * @param[in] messenger the Messenger
400  *
401  * @return the outgoing queue depth
402  */
404 
405 /** Returns the number of messages in the incoming message queue of a messenger.
406  *
407  * @param[in] messenger the Messenger
408  *
409  * @return the incoming queue depth
410  */
412 
413 #ifdef __cplusplus
414 }
415 #endif
416 
417 #endif /* messenger.h */