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/message.h>
26 
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
30 
31 /** @file
32  * The messenger API provides a high level interface for sending and
33  * receiving AMQP messages.
34  */
35 
36 typedef struct pn_messenger_t pn_messenger_t; /**< Messenger*/
37 typedef struct pn_subscription_t pn_subscription_t; /**< Subscription*/
38 typedef int64_t pn_tracker_t;
39 
40 typedef enum {
44 
45 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_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 const char *pn_messenger_name(pn_messenger_t *messenger);
68 
69 /** Sets the certificate file for a Messenger.
70  *
71  * @param[in] messenger the messenger
72  * @param[in] certificate a path to a certificate file
73  *
74  * @return an error code of zero if there is no error
75  */
76 int pn_messenger_set_certificate(pn_messenger_t *messenger, const char *certificate);
77 
78 /** Gets the certificate file fora Messenger.
79  *
80  * @param[in] messenger the messenger
81  * @return the certificate file path
82  */
83 const char *pn_messenger_get_certificate(pn_messenger_t *messenger);
84 
85 /** Sets the private key file for a Messenger.
86  *
87  * @param[in] messenger the Messenger
88  * @param[in] private_key a path to a private key file
89  *
90  * @return an error code of zero if there is no error
91  */
92 int pn_messenger_set_private_key(pn_messenger_t *messenger, const char *private_key);
93 
94 /** Gets the private key file for a Messenger.
95  *
96  * @param[in] messenger the messenger
97  * @return the private key file path
98  */
99 const char *pn_messenger_get_private_key(pn_messenger_t *messenger);
100 
101 /** Sets the private key password for a Messenger.
102  *
103  * @param[in] messenger the messenger
104  * @param[in] password the password for the private key file
105  *
106  * @return an error code of zero if there is no error
107  */
108 int pn_messenger_set_password(pn_messenger_t *messenger, const char *password);
109 
110 /** Gets the private key file password for a Messenger.
111  *
112  * @param[in] messenger the messenger
113  * @return password for the private key file
114  */
115 const char *pn_messenger_get_password(pn_messenger_t *messenger);
116 
117 /** Sets the trusted certificates database for a Messenger.
118  *
119  * @param[in] messenger the messenger
120  * @param[in] cert_db a path to the certificates database
121  *
122  * @return an error code of zero if there is no error
123  */
124 int pn_messenger_set_trusted_certificates(pn_messenger_t *messenger, const char *cert_db);
125 
126 /** Gets the trusted certificates database for a Messenger.
127  *
128  * @param[in] messenger the messenger
129  * @return path to the trusted certificates database
130  */
132 
133 /** Sets the timeout for a Messenger. A negative timeout means
134  * infinite.
135  *
136  * @param[in] messenger the messenger
137  * @param[in] timeout the new timeout for the messenger, in milliseconds
138  *
139  * @return an error code or zero if there is no error
140  */
141 int pn_messenger_set_timeout(pn_messenger_t *messenger, int timeout);
142 
143 /** Retrieves the timeout for a Messenger.
144  *
145  * @param[in] messenger the messenger
146  *
147  * @return the timeout for the messenger, in milliseconds
148  */
150 
151 /** Frees a Messenger.
152  *
153  * @param[in] messenger the messenger to free, no longer valid on
154  * return
155  */
156 void pn_messenger_free(pn_messenger_t *messenger);
157 
158 /** Returns the error code for the Messenger.
159  *
160  * @param[in] messenger the messenger to check for errors
161  *
162  * @return an error code or zero if there is no error
163  * @see error.h
164  */
165 int pn_messenger_errno(pn_messenger_t *messenger);
166 
167 /** Returns the error info for a Messenger.
168  *
169  * @param[in] messenger the messenger to check for errors
170  *
171  * @return a descriptive error message or NULL if no error has
172  * occurred
173  */
174 const char *pn_messenger_error(pn_messenger_t *messenger);
175 
176 /** Gets the accept mode for a Messenger. @see
177  * ::pn_messenger_set_accept_mode
178  *
179  * @param[in] messenger the messenger
180  *
181  * @return one of PN_ACCEPT_MODE_AUTO or PN_ACCEPT_MODE_MANUAL
182  */
184 
185 /** Set the accept mode for a Messenger. If set to
186  * PN_ACCEPT_MODE_AUTO, the messenger will automatically accept every
187  * message as it is returned by pn_messenger_get(). If set to
188  * PN_ACCEPT_MODE_MANUAL, incoming messages must be manually accepted
189  * or rejected (either individually or cumulatively) via
190  * pn_messenger_accept() and/or pn_messenger_reject().
191  *
192  * @param[in] messenger the messenger to set the accept mode for
193  * @param[in] mode one of PN_ACCEPT_MODE_AUTO or PN_ACCEPT_MODE_MANUAL
194  *
195  * @return an error code or zero on success
196  * @see error.h
197  */
199 
200 /** Gets the outgoing window for a Messenger. @see
201  * ::pn_messenger_set_outgoing_window
202  *
203  * @param[in] messenger the messenger
204  *
205  * @return the outgoing window
206  */
208 
209 /** Sets the outgoing window for a Messenger. If the outgoing window
210  * is set to a positive value, then after each call to
211  * pn_messenger_send, the Messenger will track the status of that
212  * many deliveries. @see ::pn_messenger_status
213  *
214  * @param[in] messenger the Messenger
215  * @param[in] window the number of deliveries to track
216  *
217  * @return an error or zero on success
218  * @see error.h
219  */
220 int pn_messenger_set_outgoing_window(pn_messenger_t *messenger, int window);
221 
222 /** Gets the incoming window for a Messenger. @see
223  * ::pn_messenger_set_incoming_window
224  *
225  * @param[in] messenger the Messenger
226  *
227  * @return the incoming window
228  */
230 
231 /** Sets the incoming window for a Messenger. If the incoming window
232  * is set to a positive value, then after each call to
233  * pn_messenger_accept or pn_messenger_reject, the Messenger will
234  * track the status of that many deliveries. @see
235  * ::pn_messenger_status
236  *
237  * @param[in] messenger the Messenger
238  * @param[in] window the number of deliveries to track
239  *
240  * @return an error or zero on success
241  * @see error.h
242  */
243 int pn_messenger_set_incoming_window(pn_messenger_t *messenger, int window);
244 
245 /** Starts a messenger. A messenger cannot send or recv messages until
246  * it is started.
247  *
248  * @param[in] messenger the messenger to start
249  *
250  * @return an error code or zero on success
251  * @see error.h
252  */
253 int pn_messenger_start(pn_messenger_t *messenger);
254 
255 /** Stops a messenger. A messenger cannot send or recv messages when
256  * it is stopped.
257  *
258  * @param[in] messenger the messenger to stop
259  *
260  * @return an error code or zero on success
261  * @see error.h
262  */
263 int pn_messenger_stop(pn_messenger_t *messenger);
264 
265 /** Subscribes a messenger to messages from the specified source.
266  *
267  * @param[in] messenger the messenger to subscribe
268  * @param[in] source
269  *
270  * @return a subscription
271  */
272 pn_subscription_t *pn_messenger_subscribe(pn_messenger_t *messenger, const char *source);
273 
275 
276 void pn_subscription_set_context(pn_subscription_t *sub, void *context);
277 
278 /** Puts a message on the outgoing message queue for a messenger.
279  *
280  * @param[in] messenger the messenger
281  * @param[in] msg the message to put on the outgoing queue
282  *
283  * @return an error code or zero on success
284  * @see error.h
285  */
286 int pn_messenger_put(pn_messenger_t *messenger, pn_message_t *msg);
287 
288 /** Gets the last known remote state of the delivery associated with
289  * the given tracker.
290  *
291  * @param[in] messenger the messenger
292  * @param[in] tracker the tracker identify the delivery
293  *
294  * @return a status code for the delivery
295  */
296 pn_status_t pn_messenger_status(pn_messenger_t *messenger, pn_tracker_t tracker);
297 
298 /** Frees a Messenger from tracking the status associated with a given
299  * tracker. Use the PN_CUMULATIVE flag to indicate everything up to
300  * (and including) the given tracker.
301  *
302  * @param[in] messenger the Messenger
303  * @param[in] tracker identifies a delivery
304  * @param[in] flags 0 or PN_CUMULATIVE
305  *
306  * @return an error code or zero on success
307  * @see error.h
308  */
309 int pn_messenger_settle(pn_messenger_t *messenger, pn_tracker_t tracker, int flags);
310 
311 /** Gets the tracker for the message most recently provided to
312  * pn_messenger_put.
313  *
314  * @param[in] messenger the messenger
315  *
316  * @return a pn_tracker_t or an undefined value if pn_messenger_get
317  * has never been called for the given messenger
318  */
319 pn_tracker_t pn_messenger_outgoing_tracker(pn_messenger_t *messenger);
320 
321 /** Sends any messages in the outgoing message queue for a messenger.
322  * This will block until the messages have been sent.
323  *
324  * @param[in] messenger the messager
325  *
326  * @return an error code or zero on success
327  * @see error.h
328  */
329 int pn_messenger_send(pn_messenger_t *messenger);
330 
331 /** Receives up to n message into the incoming message queue of a
332  * messenger. Blocks until at least one message is available in the
333  * incoming queue.
334  *
335  * @param[in] messenger the messenger
336  * @param[in] n the maximum number of messages to receive
337  *
338  * @return an error code or zero on success
339  * @see error.h
340  */
341 int pn_messenger_recv(pn_messenger_t *messenger, int n);
342 
343 /** Gets a message from the head of the incoming message queue of a
344  * messenger.
345  *
346  * @param[in] messenger the messenger
347  * @param[out] msg upon return contains the message from the head of the queue
348  *
349  * @return an error code or zero on success
350  * @see error.h
351  */
352 int pn_messenger_get(pn_messenger_t *messenger, pn_message_t *msg);
353 
354 /** Gets the tracker for the message most recently fetched by
355  * pn_messenger_get.
356  *
357  * @param[in] messenger the messenger
358  *
359  * @return a pn_tracker_t or an undefined value if pn_messenger_get
360  * has never been called for the given messenger
361  */
362 pn_tracker_t pn_messenger_incoming_tracker(pn_messenger_t *messenger);
363 
365 
366 #define PN_CUMULATIVE (0x1)
367 
368 /** Accepts the incoming messages identified by the tracker. Use the
369  * PN_CUMULATIVE flag to accept everything prior to the supplied
370  * tracker.
371  *
372  * @param[in] messenger the messenger
373  * @param[in] tracker an incoming tracker
374  * @param[in] flags 0 or PN_CUMULATIVE
375  *
376  * @return an error code or zero on success
377  * @see error.h
378  */
379 int pn_messenger_accept(pn_messenger_t *messenger, pn_tracker_t tracker, int flags);
380 
381 /** Rejects the incoming messages identified by the tracker. Use the
382  * PN_CUMULATIVE flag to reject everything prior to the supplied
383  * tracker.
384  *
385  * @param[in] messenger the Messenger
386  * @param[in] tracker an incoming tracker
387  * @param[in] flags 0 or PN_CUMULATIVE
388  *
389  * @return an error code or zero on success
390  * @see error.h
391  */
392 int pn_messenger_reject(pn_messenger_t *messenger, pn_tracker_t tracker, int flags);
393 
394 /** Returns the number of messages in the outgoing message queue of a messenger.
395  *
396  * @param[in] messenger the Messenger
397  *
398  * @return the outgoing queue depth
399  */
400 int pn_messenger_outgoing(pn_messenger_t *messenger);
401 
402 /** Returns the number of messages in the incoming message queue of a messenger.
403  *
404  * @param[in] messenger the Messenger
405  *
406  * @return the incoming queue depth
407  */
408 int pn_messenger_incoming(pn_messenger_t *messenger);
409 
410 #ifdef __cplusplus
411 }
412 #endif
413 
414 #endif /* messenger.h */