proton
0
Main Page
Related Pages
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Macros
Groups
Pages
proton-c
include
proton
terminus.h
Go to the documentation of this file.
1
#ifndef PROTON_TERMINUS_H
2
#define PROTON_TERMINUS_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/type_compat.h
>
27
#include <stddef.h>
28
#include <sys/types.h>
29
30
#ifdef __cplusplus
31
extern
"C"
{
32
#endif
33
34
/** @file
35
*
36
* Terminus API for the proton Engine.
37
*
38
* @defgroup terminus Terminus
39
* @ingroup link
40
* @{
41
*/
42
43
/**
44
* Encapsulates the endpoint state associated with an AMQP Terminus.
45
*
46
* An AMQP Terminus acts as either a source or target for messages,
47
* but never both. Every AMQP link is associated with both a source
48
* terminus and a target terminus that is negotiated during link
49
* establishment. A terminus consists of an AMQP address, along with a
50
* number of other properties defining the quality of service and
51
* behaviour of the link.
52
*/
53
typedef
struct
pn_terminus_t
pn_terminus_t
;
54
55
/**
56
* Type of an AMQP terminus.
57
*/
58
typedef
enum
{
59
PN_UNSPECIFIED
= 0,
/**< indicates a nonexistent terminus, may used
60
as a source or target */
61
PN_SOURCE
= 1,
/**< indicates a source of messages */
62
PN_TARGET
= 2,
/**< indicates a target for messages */
63
PN_COORDINATOR
= 3
/**< a special target identifying a transaction
64
coordinator */
65
}
pn_terminus_type_t
;
66
67
/**
68
* Durability mode of an AMQP terminus.
69
*
70
* An AMQP terminus may provide durable storage for its state, thereby
71
* permitting link recovery in the event of endpoint failures. This
72
* durability may be applied to the configuration of the terminus
73
* only, or to all delivery state as well.
74
*/
75
typedef
enum
{
76
PN_NONDURABLE
= 0,
/**< indicates a non durable terminus */
77
PN_CONFIGURATION
= 1,
/**< indicates a terminus with durably held
78
configuration, but not delivery state */
79
PN_DELIVERIES
= 2
/**< indicates a terminus with both durably held
80
configuration and durably held delivery
81
state. */
82
}
pn_durability_t
;
83
84
/**
85
* Expiry policy of an AMQP terminus.
86
*
87
* An orphaned terminus can only exist for the timeout configured by
88
* ::pn_terminus_set_timeout. The expiry policy determins when a
89
* terminus is considered orphaned, i.e. when the expiry timer starts
90
* counting down.
91
*/
92
typedef
enum
{
93
PN_LINK_CLOSE
,
/**< the terminus is orphaned when the parent link is closed */
94
PN_SESSION_CLOSE
,
/**< the terminus is orphaned when the parent session is closed */
95
PN_CONNECTION_CLOSE
,
/**< the terminus is orphaned when the parent connection is closed */
96
PN_NEVER
/**< the terminus is never considered orphaned */
97
}
pn_expiry_policy_t
;
98
99
/**
100
* Distribution mode of an AMQP terminus.
101
*
102
* The distribution mode of a source terminus defines the behaviour
103
* when multiple receiving links provide addresses that resolve to the
104
* same node.
105
*/
106
typedef
enum
{
107
PN_DIST_MODE_UNSPECIFIED
= 0,
/**< the behaviour is defined by the node */
108
PN_DIST_MODE_COPY
= 1,
/**< the receiver gets all messages */
109
PN_DIST_MODE_MOVE
= 2
/**< the receiver competes for messages */
110
}
pn_distribution_mode_t
;
111
112
/**
113
* Get the type of a terminus object.
114
*
115
* @param[in] terminus a terminus object
116
* @return the terminus type
117
*/
118
PN_EXTERN
pn_terminus_type_t
pn_terminus_get_type
(
pn_terminus_t
*terminus);
119
120
/**
121
* Set the type of a terminus object.
122
*
123
* @param[in] terminus a terminus object
124
* @param[in] type the terminus type
125
* @return 0 on success or an error code on failure
126
*/
127
PN_EXTERN
int
pn_terminus_set_type
(
pn_terminus_t
*terminus,
pn_terminus_type_t
type);
128
129
/**
130
* Get the address of a terminus object.
131
*
132
* The pointer returned by this operation is valid until
133
* ::pn_terminus_set_address is called or until the terminus is freed
134
* due to its parent link being freed.
135
*
136
* @param[in] terminus a terminus object
137
* @return a pointer to the address
138
*/
139
PN_EXTERN
const
char
*
pn_terminus_get_address
(
pn_terminus_t
*terminus);
140
141
/**
142
* Set the address of a terminus object.
143
*
144
* @param[in] terminus a terminus object
145
* @param[in] address an AMQP address string
146
* @return 0 on success or an error code on failure
147
*/
148
PN_EXTERN
int
pn_terminus_set_address
(
pn_terminus_t
*terminus,
const
char
*address);
149
150
/**
151
* Get the distribution mode of a terminus object.
152
*
153
* @param[in] terminus a terminus object
154
* @return the distribution mode of the terminus
155
*/
156
PN_EXTERN
pn_distribution_mode_t
pn_terminus_get_distribution_mode
(
const
pn_terminus_t
*terminus);
157
158
/**
159
* Set the distribution mode of a terminus object.
160
*
161
* @param[in] terminus a terminus object
162
* @param[in] mode the distribution mode for the terminus
163
* @return 0 on success or an error code on failure
164
*/
165
PN_EXTERN
int
pn_terminus_set_distribution_mode
(
pn_terminus_t
*terminus,
pn_distribution_mode_t
mode);
166
167
/**
168
* Get the durability mode of a terminus object.
169
*
170
* @param[in] terminus a terminus object
171
* @return the terminus durability mode
172
*/
173
PN_EXTERN
pn_durability_t
pn_terminus_get_durability
(
pn_terminus_t
*terminus);
174
175
/**
176
* Set the durability mode of a terminus object.
177
*
178
* @param[in] terminus a terminus object
179
* @param[in] durability the terminus durability mode
180
* @return 0 on success or an error code on failure
181
*/
182
PN_EXTERN
int
pn_terminus_set_durability
(
pn_terminus_t
*terminus,
183
pn_durability_t
durability);
184
185
/**
186
* Get the expiry policy of a terminus object.
187
*
188
* @param[in] terminus a terminus object
189
* @return the expiry policy of the terminus
190
*/
191
PN_EXTERN
pn_expiry_policy_t
pn_terminus_get_expiry_policy
(
pn_terminus_t
*terminus);
192
193
/**
194
* Set the expiry policy of a terminus object.
195
*
196
* @param[in] terminus a terminus object
197
* @param[in] policy the expiry policy for the terminus
198
* @return 0 on success or an error code on failure
199
*/
200
PN_EXTERN
int
pn_terminus_set_expiry_policy
(
pn_terminus_t
*terminus,
pn_expiry_policy_t
policy);
201
202
/**
203
* Get the timeout of a terminus object.
204
*
205
* @param[in] terminus a terminus object
206
* @return the timeout of the terminus
207
*/
208
PN_EXTERN
pn_seconds_t
pn_terminus_get_timeout
(
pn_terminus_t
*terminus);
209
210
/**
211
* Set the timeout of a terminus object.
212
*
213
* @param[in] terminus a terminus object
214
* @param[in] timeout the timeout for the terminus
215
* @return 0 on success or an error code on failure
216
*/
217
PN_EXTERN
int
pn_terminus_set_timeout
(
pn_terminus_t
*terminus,
pn_seconds_t
timeout);
218
219
/**
220
* Get the dynamic flag for a terminus object.
221
*
222
* @param[in] terminus a terminus object
223
* @return true if the dynamic flag is set for the terminus, false otherwise
224
*/
225
PN_EXTERN
bool
pn_terminus_is_dynamic
(
pn_terminus_t
*terminus);
226
227
/**
228
* Set the dynamic flag for a terminus object.
229
*
230
* @param[in] terminus a terminus object
231
* @param[in] dynamic the dynamic flag for the terminus
232
* @return 0 on success or an error code on failure
233
*/
234
PN_EXTERN
int
pn_terminus_set_dynamic
(
pn_terminus_t
*terminus,
bool
dynamic);
235
236
/**
237
* Access/modify the AMQP properties data for a terminus object.
238
*
239
* This operation will return a pointer to a ::pn_data_t object that
240
* is valid until the terminus object is freed due to its parent link
241
* being freed. Any data contained by the ::pn_data_t object will be
242
* sent as the AMQP properties for the parent terminus object. Note
243
* that this MUST take the form of a symbol keyed map to be valid.
244
*
245
* @param[in] terminus a terminus object
246
* @return a pointer to a pn_data_t representing the terminus properties
247
*/
248
PN_EXTERN
pn_data_t
*
pn_terminus_properties
(
pn_terminus_t
*terminus);
249
250
/**
251
* Access/modify the AMQP capabilities data for a terminus object.
252
*
253
* This operation will return a pointer to a ::pn_data_t object that
254
* is valid until the terminus object is freed due to its parent link
255
* being freed. Any data contained by the ::pn_data_t object will be
256
* sent as the AMQP capabilities for the parent terminus object. Note
257
* that this MUST take the form of an array of symbols to be valid.
258
*
259
* @param[in] terminus a terminus object
260
* @return a pointer to a pn_data_t representing the terminus capabilities
261
*/
262
PN_EXTERN
pn_data_t
*
pn_terminus_capabilities
(
pn_terminus_t
*terminus);
263
264
/**
265
* Access/modify the AMQP outcomes for a terminus object.
266
*
267
* This operation will return a pointer to a ::pn_data_t object that
268
* is valid until the terminus object is freed due to its parent link
269
* being freed. Any data contained by the ::pn_data_t object will be
270
* sent as the AMQP outcomes for the parent terminus object. Note
271
* that this MUST take the form of an array of symbols to be valid.
272
*
273
* @param[in] terminus a terminus object
274
* @return a pointer to a pn_data_t representing the terminus outcomes
275
*/
276
PN_EXTERN
pn_data_t
*
pn_terminus_outcomes
(
pn_terminus_t
*terminus);
277
278
/**
279
* Access/modify the AMQP filter set for a terminus object.
280
*
281
* This operation will return a pointer to a ::pn_data_t object that
282
* is valid until the terminus object is freed due to its parent link
283
* being freed. Any data contained by the ::pn_data_t object will be
284
* sent as the AMQP filter set for the parent terminus object. Note
285
* that this MUST take the form of a symbol keyed map to be valid.
286
*
287
* @param[in] terminus a source terminus object
288
* @return a pointer to a pn_data_t representing the terminus filter set
289
*/
290
PN_EXTERN
pn_data_t
*
pn_terminus_filter
(
pn_terminus_t
*terminus);
291
292
/**
293
* Copy a terminus object.
294
*
295
* @param[in] terminus the terminus object to be copied into
296
* @param[in] src the terminus to be copied from
297
* @return 0 on success or an error code on failure
298
*/
299
PN_EXTERN
int
pn_terminus_copy
(
pn_terminus_t
*terminus,
pn_terminus_t
*src);
300
301
/** @}
302
*/
303
304
#ifdef __cplusplus
305
}
306
#endif
307
308
#endif
/* terminus.h */
Generated on Mon Jun 2 2014 22:59:05 for proton by
1.8.1.2