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