proton
0
Main Page
Related Pages
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Macros
Pages
include
proton
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
{
42
PN_ACCEPT_MODE_AUTO
,
43
PN_ACCEPT_MODE_MANUAL
44
}
pn_accept_mode_t
;
45
46
typedef
enum
{
47
PN_STATUS_UNKNOWN
= 0,
48
PN_STATUS_PENDING
= 1,
49
PN_STATUS_ACCEPTED
= 2,
50
PN_STATUS_REJECTED
= 3
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
*/
84
PN_EXTERN
const
char
*
pn_messenger_get_certificate
(
pn_messenger_t
*messenger);
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
*/
100
PN_EXTERN
const
char
*
pn_messenger_get_private_key
(
pn_messenger_t
*messenger);
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
*/
132
PN_EXTERN
const
char
*
pn_messenger_get_trusted_certificates
(
pn_messenger_t
*messenger);
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
*/
150
PN_EXTERN
int
pn_messenger_get_timeout
(
pn_messenger_t
*messenger);
151
152
/** Frees a Messenger.
153
*
154
* @param[in] messenger the messenger to free, no longer valid on
155
* return
156
*/
157
PN_EXTERN
void
pn_messenger_free
(
pn_messenger_t
*messenger);
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
*/
166
PN_EXTERN
int
pn_messenger_errno
(
pn_messenger_t
*messenger);
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
*/
184
PN_EXTERN
pn_accept_mode_t
pn_messenger_get_accept_mode
(
pn_messenger_t
*messenger);
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
*/
199
PN_EXTERN
int
pn_messenger_set_accept_mode
(
pn_messenger_t
*messenger,
pn_accept_mode_t
mode);
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
*/
208
PN_EXTERN
int
pn_messenger_get_outgoing_window
(
pn_messenger_t
*messenger);
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
*/
230
PN_EXTERN
int
pn_messenger_get_incoming_window
(
pn_messenger_t
*messenger);
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
*/
254
PN_EXTERN
int
pn_messenger_start
(
pn_messenger_t
*messenger);
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
*/
264
PN_EXTERN
int
pn_messenger_stop
(
pn_messenger_t
*messenger);
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
275
PN_EXTERN
void
*
pn_subscription_get_context
(
pn_subscription_t
*sub);
276
277
PN_EXTERN
void
pn_subscription_set_context
(
pn_subscription_t
*sub,
void
*context);
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
*/
287
PN_EXTERN
int
pn_messenger_put
(
pn_messenger_t
*messenger,
pn_message_t
*msg);
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
*/
320
PN_EXTERN
pn_tracker_t
pn_messenger_outgoing_tracker
(
pn_messenger_t
*messenger);
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
*/
330
PN_EXTERN
int
pn_messenger_send
(
pn_messenger_t
*messenger);
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
*/
355
PN_EXTERN
int
pn_messenger_get
(
pn_messenger_t
*messenger,
pn_message_t
*msg);
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
*/
365
PN_EXTERN
pn_tracker_t
pn_messenger_incoming_tracker
(
pn_messenger_t
*messenger);
366
367
PN_EXTERN
pn_subscription_t
*
pn_messenger_incoming_subscription
(
pn_messenger_t
*messenger);
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
*/
403
PN_EXTERN
int
pn_messenger_outgoing
(
pn_messenger_t
*messenger);
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
*/
411
PN_EXTERN
int
pn_messenger_incoming
(
pn_messenger_t
*messenger);
412
413
#ifdef __cplusplus
414
}
415
#endif
416
417
#endif
/* messenger.h */
Generated on Fri Apr 5 2013 13:06:17 for proton by
1.8.3.1