00001 #ifndef PROTON_CONDITION_H 00002 #define PROTON_CONDITION_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/type_compat.h> 00028 #include <stddef.h> 00029 #include <sys/types.h> 00030 00031 #ifdef __cplusplus 00032 extern "C" { 00033 #endif 00034 00035 /** @file 00036 * 00037 * The Condition API for the proton Engine. 00038 * 00039 * @defgroup condition Condition 00040 * @ingroup connection 00041 * @{ 00042 */ 00043 00044 /** 00045 * An AMQP Condition object. Conditions hold exceptional information 00046 * pertaining to the closing of an AMQP endpoint such as a Connection, 00047 * Session, or Link. Conditions also hold similar information 00048 * pertaining to deliveries that have reached terminal states. 00049 * Connections, Sessions, Links, and Deliveries may all have local and 00050 * remote conditions associated with them. 00051 * 00052 * The local condition may be modified by the local endpoint to signal 00053 * a particular condition to the remote peer. The remote condition may 00054 * be examined by the local endpoint to detect whatever condition the 00055 * remote peer may be signaling. Although often conditions are used to 00056 * indicate errors, not all conditions are errors per/se, e.g. 00057 * conditions may be used to redirect a connection from one host to 00058 * another. 00059 * 00060 * Every condition has a short symbolic name, a longer description, 00061 * and an additional info map associated with it. The name identifies 00062 * the formally defined condition, and the map contains additional 00063 * information relevant to the identified condition. 00064 */ 00065 typedef struct pn_condition_t pn_condition_t; 00066 00067 /** 00068 * Returns true if the condition object is holding some information, 00069 * i.e. if the name is set to some non NULL value. Returns false 00070 * otherwise. 00071 * 00072 * @param[in] condition the condition object to test 00073 * @return true iff some condition information is set 00074 */ 00075 PN_EXTERN bool pn_condition_is_set(pn_condition_t *condition); 00076 00077 /** 00078 * Clears the condition object of any exceptional information. After 00079 * calling ::pn_condition_clear(), ::pn_condition_is_set() is 00080 * guaranteed to return false and ::pn_condition_get_name() as well as 00081 * ::pn_condition_get_description() will return NULL. The ::pn_data_t 00082 * returned by ::pn_condition_info() will still be valid, but will 00083 * have been cleared as well (See ::pn_data_clear()). 00084 * 00085 * @param[in] condition the condition object to clear 00086 */ 00087 PN_EXTERN void pn_condition_clear(pn_condition_t *condition); 00088 00089 /** 00090 * Returns the name associated with the exceptional condition, or NULL 00091 * if there is no conditional information set. 00092 * 00093 * @param[in] condition the condition object 00094 * @return a pointer to the name, or NULL 00095 */ 00096 PN_EXTERN const char *pn_condition_get_name(pn_condition_t *condition); 00097 00098 /** 00099 * Sets the name associated with the exceptional condition. 00100 * 00101 * @param[in] condition the condition object 00102 * @param[in] name the desired name 00103 * @return an error code or 0 on success 00104 */ 00105 PN_EXTERN int pn_condition_set_name(pn_condition_t *condition, const char *name); 00106 00107 /** 00108 * Gets the description associated with the exceptional condition. 00109 * 00110 * @param[in] condition the condition object 00111 * @return a pointer to the description, or NULL 00112 */ 00113 PN_EXTERN const char *pn_condition_get_description(pn_condition_t *condition); 00114 00115 /** 00116 * Sets the description associated with the exceptional condition. 00117 * 00118 * @param[in] condition the condition object 00119 * @param[in] description the desired description 00120 * @return an error code or 0 on success 00121 */ 00122 PN_EXTERN int pn_condition_set_description(pn_condition_t *condition, const char *description); 00123 00124 /** 00125 * Returns a data object that holds the additional information 00126 * associated with the condition. The data object may be used both to 00127 * access and to modify the additional information associated with the 00128 * condition. 00129 * 00130 * @param[in] condition the condition object 00131 * @return a data object holding the additional information for the condition 00132 */ 00133 PN_EXTERN pn_data_t *pn_condition_info(pn_condition_t *condition); 00134 00135 /** 00136 * Returns true if the condition is a redirect. 00137 * 00138 * @param[in] condition the condition object 00139 * @return true if the condition is a redirect, false otherwise 00140 */ 00141 PN_EXTERN bool pn_condition_is_redirect(pn_condition_t *condition); 00142 00143 /** 00144 * Retrieves the redirect host from the additional information 00145 * associated with the condition. If the condition is not a redirect, 00146 * this will return NULL. 00147 * 00148 * @param[in] condition the condition object 00149 * @return the redirect host or NULL 00150 */ 00151 PN_EXTERN const char *pn_condition_redirect_host(pn_condition_t *condition); 00152 00153 /** 00154 * Retrieves the redirect port from the additional information 00155 * associated with the condition. If the condition is not a redirect, 00156 * this will return an error code. 00157 * 00158 * @param[in] condition the condition object 00159 * @return the redirect port or an error code 00160 */ 00161 PN_EXTERN int pn_condition_redirect_port(pn_condition_t *condition); 00162 00163 /** @} 00164 */ 00165 00166 #ifdef __cplusplus 00167 } 00168 #endif 00169 00170 #endif /* condition.h */