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/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
{
41
PN_ACCEPT_MODE_AUTO
,
42
PN_ACCEPT_MODE_MANUAL
43
}
pn_accept_mode_t
;
44
45
typedef
enum
{
46
PN_STATUS_UNKNOWN
= 0,
47
PN_STATUS_PENDING
= 1,
48
PN_STATUS_ACCEPTED
= 2,
49
PN_STATUS_REJECTED
= 3
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
*/
131
const
char
*
pn_messenger_get_trusted_certificates
(
pn_messenger_t
*messenger);
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
*/
149
int
pn_messenger_get_timeout
(
pn_messenger_t
*messenger);
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
*/
183
pn_accept_mode_t
pn_messenger_get_accept_mode
(
pn_messenger_t
*messenger);
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
*/
198
int
pn_messenger_set_accept_mode
(
pn_messenger_t
*messenger,
pn_accept_mode_t
mode);
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
*/
207
int
pn_messenger_get_outgoing_window
(
pn_messenger_t
*messenger);
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
*/
229
int
pn_messenger_get_incoming_window
(
pn_messenger_t
*messenger);
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
274
void
*
pn_subscription_get_context
(
pn_subscription_t
*sub);
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
364
pn_subscription_t
*
pn_messenger_incoming_subscription
(
pn_messenger_t
*messenger);
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 */
Generated on Mon Feb 11 2013 20:34:32 for proton by
1.8.1.1