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
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 Thu Jul 10 2014 02:10:59 for proton by
1.8.3.1