00001 #ifndef PROTON_TERMINUS_H 00002 #define PROTON_TERMINUS_H 1 00003 00004 /* 00005 * 00006 * Licensed to the Apache Software Foundation (ASF) under one 00007 * or more contributor license agreements. See the NOTICE file 00008 * distributed with this work for additional information 00009 * regarding copyright ownership. The ASF licenses this file 00010 * to you under the Apache License, Version 2.0 (the 00011 * "License"); you may not use this file except in compliance 00012 * with the License. You may obtain a copy of the License at 00013 * 00014 * http://www.apache.org/licenses/LICENSE-2.0 00015 * 00016 * Unless required by applicable law or agreed to in writing, 00017 * software distributed under the License is distributed on an 00018 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 00019 * KIND, either express or implied. See the License for the 00020 * specific language governing permissions and limitations 00021 * under the License. 00022 * 00023 */ 00024 00025 #include <proton/import_export.h> 00026 #include <proton/type_compat.h> 00027 #include <proton/codec.h> 00028 #include <stddef.h> 00029 00030 #ifdef __cplusplus 00031 extern "C" { 00032 #endif 00033 00034 /** @file 00035 * 00036 * Terminus API for the proton Engine. 00037 * 00038 * @defgroup terminus Terminus 00039 * @ingroup link 00040 * @{ 00041 */ 00042 00043 /** 00044 * Encapsulates the endpoint state associated with an AMQP Terminus. 00045 * 00046 * An AMQP Terminus acts as either a source or target for messages, 00047 * but never both. Every AMQP link is associated with both a source 00048 * terminus and a target terminus that is negotiated during link 00049 * establishment. A terminus consists of an AMQP address, along with a 00050 * number of other properties defining the quality of service and 00051 * behaviour of the link. 00052 */ 00053 typedef struct pn_terminus_t pn_terminus_t; 00054 00055 /** 00056 * Type of an AMQP terminus. 00057 */ 00058 typedef enum { 00059 PN_UNSPECIFIED = 0, /**< indicates a nonexistent terminus, may used 00060 as a source or target */ 00061 PN_SOURCE = 1, /**< indicates a source of messages */ 00062 PN_TARGET = 2, /**< indicates a target for messages */ 00063 PN_COORDINATOR = 3 /**< a special target identifying a transaction 00064 coordinator */ 00065 } pn_terminus_type_t; 00066 00067 /** 00068 * Durability mode of an AMQP terminus. 00069 * 00070 * An AMQP terminus may provide durable storage for its state, thereby 00071 * permitting link recovery in the event of endpoint failures. This 00072 * durability may be applied to the configuration of the terminus 00073 * only, or to all delivery state as well. 00074 */ 00075 typedef enum { 00076 PN_NONDURABLE = 0, /**< indicates a non durable terminus */ 00077 PN_CONFIGURATION = 1, /**< indicates a terminus with durably held 00078 configuration, but not delivery state */ 00079 PN_DELIVERIES = 2 /**< indicates a terminus with both durably held 00080 configuration and durably held delivery 00081 state. */ 00082 } pn_durability_t; 00083 00084 /** 00085 * Expiry policy of an AMQP terminus. 00086 * 00087 * An orphaned terminus can only exist for the timeout configured by 00088 * ::pn_terminus_set_timeout. The expiry policy determins when a 00089 * terminus is considered orphaned, i.e. when the expiry timer starts 00090 * counting down. 00091 */ 00092 typedef enum { 00093 PN_EXPIRE_WITH_LINK, /**< the terminus is orphaned when the parent link is closed */ 00094 PN_EXPIRE_WITH_SESSION, /**< the terminus is orphaned when the parent session is closed */ 00095 PN_EXPIRE_WITH_CONNECTION, /**< the terminus is orphaned when the parent connection is closed */ 00096 PN_EXPIRE_NEVER /**< the terminus is never considered orphaned */ 00097 } pn_expiry_policy_t; 00098 00099 /** 00100 * Distribution mode of an AMQP terminus. 00101 * 00102 * The distribution mode of a source terminus defines the behaviour 00103 * when multiple receiving links provide addresses that resolve to the 00104 * same node. 00105 */ 00106 typedef enum { 00107 PN_DIST_MODE_UNSPECIFIED = 0, /**< the behaviour is defined by the node */ 00108 PN_DIST_MODE_COPY = 1, /**< the receiver gets all messages */ 00109 PN_DIST_MODE_MOVE = 2 /**< the receiver competes for messages */ 00110 } pn_distribution_mode_t; 00111 00112 /** 00113 * Get the type of a terminus object. 00114 * 00115 * @param[in] terminus a terminus object 00116 * @return the terminus type 00117 */ 00118 PN_EXTERN pn_terminus_type_t pn_terminus_get_type(pn_terminus_t *terminus); 00119 00120 /** 00121 * Set the type of a terminus object. 00122 * 00123 * @param[in] terminus a terminus object 00124 * @param[in] type the terminus type 00125 * @return 0 on success or an error code on failure 00126 */ 00127 PN_EXTERN int pn_terminus_set_type(pn_terminus_t *terminus, pn_terminus_type_t type); 00128 00129 /** 00130 * Get the address of a terminus object. 00131 * 00132 * The pointer returned by this operation is valid until 00133 * ::pn_terminus_set_address is called or until the terminus is freed 00134 * due to its parent link being freed. 00135 * 00136 * @param[in] terminus a terminus object 00137 * @return a pointer to the address 00138 */ 00139 PN_EXTERN const char *pn_terminus_get_address(pn_terminus_t *terminus); 00140 00141 /** 00142 * Set the address of a terminus object. 00143 * 00144 * @param[in] terminus a terminus object 00145 * @param[in] address an AMQP address string 00146 * @return 0 on success or an error code on failure 00147 */ 00148 PN_EXTERN int pn_terminus_set_address(pn_terminus_t *terminus, const char *address); 00149 00150 /** 00151 * Get the distribution mode of a terminus object. 00152 * 00153 * @param[in] terminus a terminus object 00154 * @return the distribution mode of the terminus 00155 */ 00156 PN_EXTERN pn_distribution_mode_t pn_terminus_get_distribution_mode(const pn_terminus_t *terminus); 00157 00158 /** 00159 * Set the distribution mode of a terminus object. 00160 * 00161 * @param[in] terminus a terminus object 00162 * @param[in] mode the distribution mode for the terminus 00163 * @return 0 on success or an error code on failure 00164 */ 00165 PN_EXTERN int pn_terminus_set_distribution_mode(pn_terminus_t *terminus, pn_distribution_mode_t mode); 00166 00167 /** 00168 * Get the durability mode of a terminus object. 00169 * 00170 * @param[in] terminus a terminus object 00171 * @return the terminus durability mode 00172 */ 00173 PN_EXTERN pn_durability_t pn_terminus_get_durability(pn_terminus_t *terminus); 00174 00175 /** 00176 * Set the durability mode of a terminus object. 00177 * 00178 * @param[in] terminus a terminus object 00179 * @param[in] durability the terminus durability mode 00180 * @return 0 on success or an error code on failure 00181 */ 00182 PN_EXTERN int pn_terminus_set_durability(pn_terminus_t *terminus, 00183 pn_durability_t durability); 00184 00185 /** 00186 * Get the expiry policy of a terminus object. 00187 * 00188 * @param[in] terminus a terminus object 00189 * @return the expiry policy of the terminus 00190 */ 00191 PN_EXTERN pn_expiry_policy_t pn_terminus_get_expiry_policy(pn_terminus_t *terminus); 00192 00193 /** 00194 * Set the expiry policy of a terminus object. 00195 * 00196 * @param[in] terminus a terminus object 00197 * @param[in] policy the expiry policy for the terminus 00198 * @return 0 on success or an error code on failure 00199 */ 00200 PN_EXTERN int pn_terminus_set_expiry_policy(pn_terminus_t *terminus, pn_expiry_policy_t policy); 00201 00202 /** 00203 * Get the timeout of a terminus object. 00204 * 00205 * @param[in] terminus a terminus object 00206 * @return the timeout of the terminus 00207 */ 00208 PN_EXTERN pn_seconds_t pn_terminus_get_timeout(pn_terminus_t *terminus); 00209 00210 /** 00211 * Set the timeout of a terminus object. 00212 * 00213 * @param[in] terminus a terminus object 00214 * @param[in] timeout the timeout for the terminus 00215 * @return 0 on success or an error code on failure 00216 */ 00217 PN_EXTERN int pn_terminus_set_timeout(pn_terminus_t *terminus, pn_seconds_t timeout); 00218 00219 /** 00220 * Get the dynamic flag for a terminus object. 00221 * 00222 * @param[in] terminus a terminus object 00223 * @return true if the dynamic flag is set for the terminus, false otherwise 00224 */ 00225 PN_EXTERN bool pn_terminus_is_dynamic(pn_terminus_t *terminus); 00226 00227 /** 00228 * Set the dynamic flag for a terminus object. 00229 * 00230 * @param[in] terminus a terminus object 00231 * @param[in] dynamic the dynamic flag for the terminus 00232 * @return 0 on success or an error code on failure 00233 */ 00234 PN_EXTERN int pn_terminus_set_dynamic(pn_terminus_t *terminus, bool dynamic); 00235 00236 /** 00237 * Access/modify the AMQP properties data for a terminus object. 00238 * 00239 * This operation will return a pointer to a ::pn_data_t object that 00240 * is valid until the terminus object is freed due to its parent link 00241 * being freed. Any data contained by the ::pn_data_t object will be 00242 * sent as the AMQP properties for the parent terminus object. Note 00243 * that this MUST take the form of a symbol keyed map to be valid. 00244 * 00245 * @param[in] terminus a terminus object 00246 * @return a pointer to a pn_data_t representing the terminus properties 00247 */ 00248 PN_EXTERN pn_data_t *pn_terminus_properties(pn_terminus_t *terminus); 00249 00250 /** 00251 * Access/modify the AMQP capabilities data for a terminus object. 00252 * 00253 * This operation will return a pointer to a ::pn_data_t object that 00254 * is valid until the terminus object is freed due to its parent link 00255 * being freed. Any data contained by the ::pn_data_t object will be 00256 * sent as the AMQP capabilities for the parent terminus object. Note 00257 * that this MUST take the form of an array of symbols to be valid. 00258 * 00259 * @param[in] terminus a terminus object 00260 * @return a pointer to a pn_data_t representing the terminus capabilities 00261 */ 00262 PN_EXTERN pn_data_t *pn_terminus_capabilities(pn_terminus_t *terminus); 00263 00264 /** 00265 * Access/modify the AMQP outcomes for a terminus object. 00266 * 00267 * This operation will return a pointer to a ::pn_data_t object that 00268 * is valid until the terminus object is freed due to its parent link 00269 * being freed. Any data contained by the ::pn_data_t object will be 00270 * sent as the AMQP outcomes for the parent terminus object. Note 00271 * that this MUST take the form of an array of symbols to be valid. 00272 * 00273 * @param[in] terminus a terminus object 00274 * @return a pointer to a pn_data_t representing the terminus outcomes 00275 */ 00276 PN_EXTERN pn_data_t *pn_terminus_outcomes(pn_terminus_t *terminus); 00277 00278 /** 00279 * Access/modify the AMQP filter set for a terminus object. 00280 * 00281 * This operation will return a pointer to a ::pn_data_t object that 00282 * is valid until the terminus object is freed due to its parent link 00283 * being freed. Any data contained by the ::pn_data_t object will be 00284 * sent as the AMQP filter set for the parent terminus object. Note 00285 * that this MUST take the form of a symbol keyed map to be valid. 00286 * 00287 * @param[in] terminus a source terminus object 00288 * @return a pointer to a pn_data_t representing the terminus filter set 00289 */ 00290 PN_EXTERN pn_data_t *pn_terminus_filter(pn_terminus_t *terminus); 00291 00292 /** 00293 * Copy a terminus object. 00294 * 00295 * @param[in] terminus the terminus object to be copied into 00296 * @param[in] src the terminus to be copied from 00297 * @return 0 on success or an error code on failure 00298 */ 00299 PN_EXTERN int pn_terminus_copy(pn_terminus_t *terminus, pn_terminus_t *src); 00300 00301 /** @} 00302 */ 00303 00304 #ifdef __cplusplus 00305 } 00306 #endif 00307 00308 #endif /* terminus.h */