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