proton  0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
condition.h
Go to the documentation of this file.
1 #ifndef PROTON_CONDITION_H
2 #define PROTON_CONDITION_H 1
3 
4 /*
5  *
6  * Licensed to the Apache Software Foundation (ASF) under one
7  * or more contributor license agreements. See the NOTICE file
8  * distributed with this work for additional information
9  * regarding copyright ownership. The ASF licenses this file
10  * to you under the Apache License, Version 2.0 (the
11  * "License"); you may not use this file except in compliance
12  * with the License. You may obtain a copy of the License at
13  *
14  * http://www.apache.org/licenses/LICENSE-2.0
15  *
16  * Unless required by applicable law or agreed to in writing,
17  * software distributed under the License is distributed on an
18  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
19  * KIND, either express or implied. See the License for the
20  * specific language governing permissions and limitations
21  * under the License.
22  *
23  */
24 
25 #include <proton/import_export.h>
26 #include <proton/codec.h>
27 #include <proton/type_compat.h>
28 #include <stddef.h>
29 #include <sys/types.h>
30 
31 #ifdef __cplusplus
32 extern "C" {
33 #endif
34 
35 /** @file
36  *
37  * The Condition API for the proton Engine.
38  *
39  * @defgroup condition Condition
40  * @ingroup connection
41  * @{
42  */
43 
44 /**
45  * An AMQP Condition object. Conditions hold exceptional information
46  * pertaining to the closing of an AMQP endpoint such as a Connection,
47  * Session, or Link. Conditions also hold similar information
48  * pertaining to deliveries that have reached terminal states.
49  * Connections, Sessions, Links, and Deliveries may all have local and
50  * remote conditions associated with them.
51  *
52  * The local condition may be modified by the local endpoint to signal
53  * a particular condition to the remote peer. The remote condition may
54  * be examined by the local endpoint to detect whatever condition the
55  * remote peer may be signaling. Although often conditions are used to
56  * indicate errors, not all conditions are errors per/se, e.g.
57  * conditions may be used to redirect a connection from one host to
58  * another.
59  *
60  * Every condition has a short symbolic name, a longer description,
61  * and an additional info map associated with it. The name identifies
62  * the formally defined condition, and the map contains additional
63  * information relevant to the identified condition.
64  */
66 
67 /**
68  * Returns true if the condition object is holding some information,
69  * i.e. if the name is set to some non NULL value. Returns false
70  * otherwise.
71  *
72  * @param[in] condition the condition object to test
73  * @return true iff some condition information is set
74  */
76 
77 /**
78  * Clears the condition object of any exceptional information. After
79  * calling ::pn_condition_clear(), ::pn_condition_is_set() is
80  * guaranteed to return false and ::pn_condition_get_name() as well as
81  * ::pn_condition_get_description() will return NULL. The ::pn_data_t
82  * returned by ::pn_condition_info() will still be valid, but will
83  * have been cleared as well (See ::pn_data_clear()).
84  *
85  * @param[in] condition the condition object to clear
86  */
88 
89 /**
90  * Returns the name associated with the exceptional condition, or NULL
91  * if there is no conditional information set.
92  *
93  * @param[in] condition the condition object
94  * @return a pointer to the name, or NULL
95  */
96 PN_EXTERN const char *pn_condition_get_name(pn_condition_t *condition);
97 
98 /**
99  * Sets the name associated with the exceptional condition.
100  *
101  * @param[in] condition the condition object
102  * @param[in] name the desired name
103  * @return an error code or 0 on success
104  */
105 PN_EXTERN int pn_condition_set_name(pn_condition_t *condition, const char *name);
106 
107 /**
108  * Gets the description associated with the exceptional condition.
109  *
110  * @param[in] condition the condition object
111  * @return a pointer to the description, or NULL
112  */
114 
115 /**
116  * Sets the description associated with the exceptional condition.
117  *
118  * @param[in] condition the condition object
119  * @param[in] description the desired description
120  * @return an error code or 0 on success
121  */
122 PN_EXTERN int pn_condition_set_description(pn_condition_t *condition, const char *description);
123 
124 /**
125  * Returns a data object that holds the additional information
126  * associated with the condition. The data object may be used both to
127  * access and to modify the additional information associated with the
128  * condition.
129  *
130  * @param[in] condition the condition object
131  * @return a data object holding the additional information for the condition
132  */
134 
135 /**
136  * Returns true if the condition is a redirect.
137  *
138  * @param[in] condition the condition object
139  * @return true if the condition is a redirect, false otherwise
140  */
142 
143 /**
144  * Retrieves the redirect host from the additional information
145  * associated with the condition. If the condition is not a redirect,
146  * this will return NULL.
147  *
148  * @param[in] condition the condition object
149  * @return the redirect host or NULL
150  */
151 PN_EXTERN const char *pn_condition_redirect_host(pn_condition_t *condition);
152 
153 /**
154  * Retrieves the redirect port from the additional information
155  * associated with the condition. If the condition is not a redirect,
156  * this will return an error code.
157  *
158  * @param[in] condition the condition object
159  * @return the redirect port or an error code
160  */
162 
163 /** @}
164  */
165 
166 #ifdef __cplusplus
167 }
168 #endif
169 
170 #endif /* condition.h */