proton  0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
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  */
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 */
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. */
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 */
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 */
111 
112 /**
113  * Get the type of a terminus object.
114  *
115  * @param[in] terminus a terminus object
116  * @return the terminus type
117  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
300 
301 /** @}
302  */
303 
304 #ifdef __cplusplus
305 }
306 #endif
307 
308 #endif /* terminus.h */