00001 #ifndef PROTON_CONNECTION_H 00002 #define PROTON_CONNECTION_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 <stddef.h> 00028 #include <sys/types.h> 00029 00030 #ifdef __cplusplus 00031 extern "C" { 00032 #endif 00033 00034 /** 00035 * @file 00036 * 00037 * Connection API for the proton Engine. 00038 * 00039 * @defgroup connection Connection 00040 * @ingroup engine 00041 * @{ 00042 */ 00043 00044 /** 00045 * The local @link pn_state_t endpoint state @endlink is uninitialized. 00046 */ 00047 #define PN_LOCAL_UNINIT (1) 00048 /** 00049 * The local @link pn_state_t endpoint state @endlink is active. 00050 */ 00051 #define PN_LOCAL_ACTIVE (2) 00052 /** 00053 * The local @link pn_state_t endpoint state @endlink is closed. 00054 */ 00055 #define PN_LOCAL_CLOSED (4) 00056 /** 00057 * The remote @link pn_state_t endpoint state @endlink is uninitialized. 00058 */ 00059 #define PN_REMOTE_UNINIT (8) 00060 /** 00061 * The remote @link pn_state_t endpoint state @endlink is active. 00062 */ 00063 #define PN_REMOTE_ACTIVE (16) 00064 /** 00065 * The remote @link pn_state_t endpoint state @endlink is closed. 00066 */ 00067 #define PN_REMOTE_CLOSED (32) 00068 00069 /** 00070 * A mask for values of ::pn_state_t that preserves only the local 00071 * bits of an endpoint's state. 00072 */ 00073 #define PN_LOCAL_MASK (PN_LOCAL_UNINIT | PN_LOCAL_ACTIVE | PN_LOCAL_CLOSED) 00074 00075 /** 00076 * A mask for values of ::pn_state_t that preserves only the remote 00077 * bits of an endpoint's state. 00078 */ 00079 #define PN_REMOTE_MASK (PN_REMOTE_UNINIT | PN_REMOTE_ACTIVE | PN_REMOTE_CLOSED) 00080 00081 /** 00082 * Factory to construct a new Connection. 00083 * 00084 * @return pointer to a new connection object. 00085 */ 00086 PN_EXTERN pn_connection_t *pn_connection(void); 00087 00088 /** 00089 * Free a connection object. 00090 * 00091 * When a connection object is freed, all ::pn_session_t, ::pn_link_t, 00092 * and ::pn_delivery_t objects associated with the connection are also 00093 * freed. 00094 * 00095 * @param[in] connection the connection object to free (or NULL) 00096 */ 00097 PN_EXTERN void pn_connection_free(pn_connection_t *connection); 00098 00099 /** 00100 * Get additional error information associated with the connection. 00101 * 00102 * Whenever a connection operation fails (i.e. returns an error code), 00103 * additional error details can be obtained using this function. The 00104 * error object that is returned may also be used to clear the error 00105 * condition. 00106 * 00107 * The pointer returned by this operation is valid until the 00108 * connection object is freed. 00109 * 00110 * @param[in] connection the connection object 00111 * @return the connection's error object 00112 */ 00113 PN_EXTERN pn_error_t *pn_connection_error(pn_connection_t *connection); 00114 00115 /** 00116 * Associate a connection object with an event collector. 00117 * 00118 * By associating a connection object with an event collector, key 00119 * changes in endpoint state are reported to the collector via 00120 * ::pn_event_t objects that can be inspected and processed. See 00121 * ::pn_event_t for more details on the kinds of events. 00122 * 00123 * Note that by registering a collector, the user is requesting that 00124 * an indefinite number of events be queued up on his behalf. This 00125 * means that unless the application eventually processes these 00126 * events, the storage requirements for keeping them will grow without 00127 * bound. In other words, don't register a collector with a connection 00128 * if you never intend to process any of the events. 00129 * 00130 * @param[in] connection the connection object 00131 * @param[in] collector the event collector 00132 */ 00133 PN_EXTERN void pn_connection_collect(pn_connection_t *connection, pn_collector_t *collector); 00134 00135 /** 00136 * Get the application context that is associated with a connection 00137 * object. 00138 * 00139 * The application context for a connection may be set using 00140 * ::pn_connection_set_context. 00141 * 00142 * @param[in] connection the connection whose context is to be returned. 00143 * @return the application context for the connection object 00144 */ 00145 PN_EXTERN void *pn_connection_get_context(pn_connection_t *connection); 00146 00147 /** 00148 * Set a new application context for a connection object. 00149 * 00150 * The application context for a connection object may be retrieved 00151 * using ::pn_connection_get_context. 00152 * 00153 * @param[in] connection the connection object 00154 * @param[in] context the application context 00155 */ 00156 PN_EXTERN void pn_connection_set_context(pn_connection_t *connection, void *context); 00157 00158 /** 00159 * Get the endpoint state flags for a connection. 00160 * 00161 * @param[in] connection the connection 00162 * @return the connection's state flags 00163 */ 00164 PN_EXTERN pn_state_t pn_connection_state(pn_connection_t *connection); 00165 00166 /** 00167 * Open a connection. 00168 * 00169 * Once this operation has completed, the PN_LOCAL_ACTIVE state flag 00170 * will be set. 00171 * 00172 * @param[in] connection a connection object 00173 */ 00174 PN_EXTERN void pn_connection_open(pn_connection_t *connection); 00175 00176 /** 00177 * Close a connection. 00178 * 00179 * Once this operation has completed, the PN_LOCAL_CLOSED state flag 00180 * will be set. This may be called without calling 00181 * ::pn_connection_open, in this case it is equivalent to calling 00182 * ::pn_connection_open followed by ::pn_connection_close. 00183 * 00184 * @param[in] connection a connection object 00185 */ 00186 PN_EXTERN void pn_connection_close(pn_connection_t *connection); 00187 00188 /** 00189 * Reset a connection object back to the uninitialized state. 00190 * 00191 * Note that this does *not* remove any contained ::pn_session_t, 00192 * ::pn_link_t, and ::pn_delivery_t objects. 00193 * 00194 * @param[in] connection a connection object 00195 */ 00196 PN_EXTERN void pn_connection_reset(pn_connection_t *connection); 00197 00198 /** 00199 * Get the local condition associated with the connection endpoint. 00200 * 00201 * The ::pn_condition_t object retrieved may be modified prior to 00202 * closing the connection in order to indicate a particular condition 00203 * exists when the connection closes. This is normally used to 00204 * communicate error conditions to the remote peer, however it may 00205 * also be used in non error cases such as redirects. See 00206 * ::pn_condition_t for more details. 00207 * 00208 * The pointer returned by this operation is valid until the 00209 * connection object is freed. 00210 * 00211 * @param[in] connection the connection object 00212 * @return the connection's local condition object 00213 */ 00214 PN_EXTERN pn_condition_t *pn_connection_condition(pn_connection_t *connection); 00215 00216 /** 00217 * Get the remote condition associated with the connection endpoint. 00218 * 00219 * The ::pn_condition_t object retrieved may be examined in order to 00220 * determine whether the remote peer was indicating some sort of 00221 * exceptional condition when the remote connection endpoint was 00222 * closed. The ::pn_condition_t object returned may not be modified. 00223 * 00224 * The pointer returned by this operation is valid until the 00225 * connection object is freed. 00226 * 00227 * @param[in] connection the connection object 00228 * @return the connection's remote condition object 00229 */ 00230 PN_EXTERN pn_condition_t *pn_connection_remote_condition(pn_connection_t *connection); 00231 00232 /** 00233 * Get the AMQP Container name advertised by a connection object. 00234 * 00235 * The pointer returned by this operation is valid until 00236 * ::pn_connection_set_container is called, or until the connection 00237 * object is freed, whichever happens sooner. 00238 * 00239 * @param[in] connection the connection object 00240 * @return a pointer to the container name 00241 */ 00242 PN_EXTERN const char *pn_connection_get_container(pn_connection_t *connection); 00243 00244 /** 00245 * Set the AMQP Container name advertised by a connection object. 00246 * 00247 * @param[in] connection the connection object 00248 * @param[in] container the container name 00249 */ 00250 PN_EXTERN void pn_connection_set_container(pn_connection_t *connection, const char *container); 00251 00252 /** 00253 * Get the value of the AMQP Hostname used by a connection object. 00254 * 00255 * The pointer returned by this operation is valid until 00256 * ::pn_connection_set_hostname is called, or until the connection 00257 * object is freed, whichever happens sooner. 00258 * 00259 * @param[in] connection the connection object 00260 * @return a pointer to the hostname 00261 */ 00262 PN_EXTERN const char *pn_connection_get_hostname(pn_connection_t *connection); 00263 00264 /** 00265 * Set the value of the AMQP Hostname used by a connection object. 00266 * 00267 * @param[in] connection the connection object 00268 * @param[in] hostname the hostname 00269 */ 00270 PN_EXTERN void pn_connection_set_hostname(pn_connection_t *connection, const char *hostname); 00271 00272 /** 00273 * Get the AMQP Container name advertised by the remote connection 00274 * endpoint. 00275 * 00276 * This will return NULL until the ::PN_REMOTE_ACTIVE state is 00277 * reached. See ::pn_state_t for more details on endpoint state. 00278 * 00279 * Any non null pointer returned by this operation will be valid until 00280 * the connection object is unbound from a transport or freed, 00281 * whichever happens sooner. 00282 * 00283 * @param[in] connection the connection object 00284 * @return a pointer to the remote container name 00285 */ 00286 PN_EXTERN const char *pn_connection_remote_container(pn_connection_t *connection); 00287 00288 /** 00289 * Get the AMQP Hostname set by the remote connection endpoint. 00290 * 00291 * This will return NULL until the ::PN_REMOTE_ACTIVE state is 00292 * reached. See ::pn_state_t for more details on endpoint state. 00293 * 00294 * Any non null pointer returned by this operation will be valid until 00295 * the connection object is unbound from a transport or freed, 00296 * whichever happens sooner. 00297 * 00298 * @param[in] connection the connection object 00299 * @return a pointer to the remote hostname 00300 */ 00301 PN_EXTERN const char *pn_connection_remote_hostname(pn_connection_t *connection); 00302 00303 /** 00304 * Access/modify the AMQP offered capabilities data for a connection 00305 * object. 00306 * 00307 * This operation will return a pointer to a ::pn_data_t object that 00308 * is valid until the connection object is freed. Any data contained 00309 * by the ::pn_data_t object will be sent as the offered capabilites 00310 * for the parent connection object. Note that this MUST take the form 00311 * of an array of symbols to be valid. 00312 * 00313 * The ::pn_data_t pointer returned is valid until the connection 00314 * object is freed. 00315 * 00316 * @param[in] connection the connection object 00317 * @return a pointer to a pn_data_t representing the offered capabilities 00318 */ 00319 PN_EXTERN pn_data_t *pn_connection_offered_capabilities(pn_connection_t *connection); 00320 00321 /** 00322 * Access/modify the AMQP desired capabilities data for a connection 00323 * object. 00324 * 00325 * This operation will return a pointer to a ::pn_data_t object that 00326 * is valid until the connection object is freed. Any data contained 00327 * by the ::pn_data_t object will be sent as the desired capabilites 00328 * for the parent connection object. Note that this MUST take the form 00329 * of an array of symbols to be valid. 00330 * 00331 * The ::pn_data_t pointer returned is valid until the connection 00332 * object is freed. 00333 * 00334 * @param[in] connection the connection object 00335 * @return a pointer to a pn_data_t representing the desired capabilities 00336 */ 00337 PN_EXTERN pn_data_t *pn_connection_desired_capabilities(pn_connection_t *connection); 00338 00339 /** 00340 * Access/modify the AMQP properties data for a connection object. 00341 * 00342 * This operation will return a pointer to a ::pn_data_t object that 00343 * is valid until the connection object is freed. Any data contained 00344 * by the ::pn_data_t object will be sent as the AMQP properties for 00345 * the parent connection object. Note that this MUST take the form of 00346 * a symbol keyed map to be valid. 00347 * 00348 * The ::pn_data_t pointer returned is valid until the connection 00349 * object is freed. 00350 * 00351 * @param[in] connection the connection object 00352 * @return a pointer to a pn_data_t representing the connection properties 00353 */ 00354 PN_EXTERN pn_data_t *pn_connection_properties(pn_connection_t *connection); 00355 00356 /** 00357 * Access the AMQP offered capabilites supplied by the remote 00358 * connection endpoint. 00359 * 00360 * This operation will return a pointer to a ::pn_data_t object that 00361 * is valid until the connection object is freed. This data object 00362 * will be empty until the remote connection is opened as indicated by 00363 * the ::PN_REMOTE_ACTIVE flag. 00364 * 00365 * @param[in] connection the connection object 00366 * @return the remote offered capabilities 00367 */ 00368 PN_EXTERN pn_data_t *pn_connection_remote_offered_capabilities(pn_connection_t *connection); 00369 00370 /** 00371 * Access the AMQP desired capabilites supplied by the remote 00372 * connection endpoint. 00373 * 00374 * This operation will return a pointer to a ::pn_data_t object that 00375 * is valid until the connection object is freed. This data object 00376 * will be empty until the remote connection is opened as indicated by 00377 * the ::PN_REMOTE_ACTIVE flag. 00378 * 00379 * @param[in] connection the connection object 00380 * @return the remote desired capabilities 00381 */ 00382 PN_EXTERN pn_data_t *pn_connection_remote_desired_capabilities(pn_connection_t *connection); 00383 00384 /** 00385 * Access the AMQP connection properties supplied by the remote 00386 * connection endpoint. 00387 * 00388 * This operation will return a pointer to a ::pn_data_t object that 00389 * is valid until the connection object is freed. This data object 00390 * will be empty until the remote connection is opened as indicated by 00391 * the ::PN_REMOTE_ACTIVE flag. 00392 * 00393 * @param[in] connection the connection object 00394 * @return the remote connection properties 00395 */ 00396 PN_EXTERN pn_data_t *pn_connection_remote_properties(pn_connection_t *connection); 00397 00398 /** 00399 * Get the transport bound to a connection object. 00400 * 00401 * If the connection is unbound, then this operation will return NULL. 00402 * 00403 * @param[in] connection the connection object 00404 * @return the transport bound to a connection, or NULL if the 00405 * connection is unbound 00406 */ 00407 PN_EXTERN pn_transport_t *pn_connection_transport(pn_connection_t *connection); 00408 00409 /** @} 00410 */ 00411 00412 #ifdef __cplusplus 00413 } 00414 #endif 00415 00416 #endif /* connection.h */