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