proton  0
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 
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33 
34 /** @file
35  *
36  * The Condition API for the proton Engine.
37  *
38  * @defgroup condition Condition
39  * @ingroup connection
40  * @{
41  */
42 
43 /**
44  * An AMQP Condition object. Conditions hold exceptional information
45  * pertaining to the closing of an AMQP endpoint such as a Connection,
46  * Session, or Link. Conditions also hold similar information
47  * pertaining to deliveries that have reached terminal states.
48  * Connections, Sessions, Links, and Deliveries may all have local and
49  * remote conditions associated with them.
50  *
51  * The local condition may be modified by the local endpoint to signal
52  * a particular condition to the remote peer. The remote condition may
53  * be examined by the local endpoint to detect whatever condition the
54  * remote peer may be signaling. Although often conditions are used to
55  * indicate errors, not all conditions are errors per/se, e.g.
56  * conditions may be used to redirect a connection from one host to
57  * another.
58  *
59  * Every condition has a short symbolic name, a longer description,
60  * and an additional info map associated with it. The name identifies
61  * the formally defined condition, and the map contains additional
62  * information relevant to the identified condition.
63  */
65 
66 /**
67  * Returns true if the condition object is holding some information,
68  * i.e. if the name is set to some non NULL value. Returns false
69  * otherwise.
70  *
71  * @param[in] condition the condition object to test
72  * @return true iff some condition information is set
73  */
75 
76 /**
77  * Clears the condition object of any exceptional information. After
78  * calling ::pn_condition_clear(), ::pn_condition_is_set() is
79  * guaranteed to return false and ::pn_condition_get_name() as well as
80  * ::pn_condition_get_description() will return NULL. The ::pn_data_t
81  * returned by ::pn_condition_info() will still be valid, but will
82  * have been cleared as well (See ::pn_data_clear()).
83  *
84  * @param[in] condition the condition object to clear
85  */
87 
88 /**
89  * Returns the name associated with the exceptional condition, or NULL
90  * if there is no conditional information set.
91  *
92  * @param[in] condition the condition object
93  * @return a pointer to the name, or NULL
94  */
95 PN_EXTERN const char *pn_condition_get_name(pn_condition_t *condition);
96 
97 /**
98  * Sets the name associated with the exceptional condition.
99  *
100  * @param[in] condition the condition object
101  * @param[in] name the desired name
102  * @return an error code or 0 on success
103  */
104 PN_EXTERN int pn_condition_set_name(pn_condition_t *condition, const char *name);
105 
106 /**
107  * Gets the description associated with the exceptional condition.
108  *
109  * @param[in] condition the condition object
110  * @return a pointer to the description, or NULL
111  */
113 
114 /**
115  * Sets the description associated with the exceptional condition.
116  *
117  * @param[in] condition the condition object
118  * @param[in] description the desired description
119  * @return an error code or 0 on success
120  */
121 PN_EXTERN int pn_condition_set_description(pn_condition_t *condition, const char *description);
122 
123 /**
124  * Returns a data object that holds the additional information
125  * associated with the condition. The data object may be used both to
126  * access and to modify the additional information associated with the
127  * condition.
128  *
129  * @param[in] condition the condition object
130  * @return a data object holding the additional information for the condition
131  */
133 
134 /**
135  * Returns true if the condition is a redirect.
136  *
137  * @param[in] condition the condition object
138  * @return true if the condition is a redirect, false otherwise
139  */
141 
142 /**
143  * Retrieves the redirect host from the additional information
144  * associated with the condition. If the condition is not a redirect,
145  * this will return NULL.
146  *
147  * @param[in] condition the condition object
148  * @return the redirect host or NULL
149  */
150 PN_EXTERN const char *pn_condition_redirect_host(pn_condition_t *condition);
151 
152 /**
153  * Retrieves the redirect port from the additional information
154  * associated with the condition. If the condition is not a redirect,
155  * this will return an error code.
156  *
157  * @param[in] condition the condition object
158  * @return the redirect port or an error code
159  */
161 
162 /** @}
163  */
164 
165 #ifdef __cplusplus
166 }
167 #endif
168 
169 #endif /* condition.h */
PN_EXTERN int pn_condition_set_name(pn_condition_t *condition, const char *name)
Sets the name associated with the exceptional condition.
struct pn_data_t pn_data_t
An AMQP Data object.
Definition: codec.h:352
PN_EXTERN void pn_condition_clear(pn_condition_t *condition)
Clears the condition object of any exceptional information.
PN_EXTERN bool pn_condition_is_redirect(pn_condition_t *condition)
Returns true if the condition is a redirect.
Data API for proton.
PN_EXTERN bool pn_condition_is_set(pn_condition_t *condition)
Returns true if the condition object is holding some information, i.e.
PN_EXTERN pn_data_t * pn_condition_info(pn_condition_t *condition)
Returns a data object that holds the additional information associated with the condition.
#define PN_EXTERN
Definition: import_export.h:53
PN_EXTERN const char * pn_condition_redirect_host(pn_condition_t *condition)
Retrieves the redirect host from the additional information associated with the condition.
PN_EXTERN const char * pn_condition_get_description(pn_condition_t *condition)
Gets the description associated with the exceptional condition.
PN_EXTERN int pn_condition_set_description(pn_condition_t *condition, const char *description)
Sets the description associated with the exceptional condition.
struct pn_condition_t pn_condition_t
An AMQP Condition object.
Definition: condition.h:64
PN_EXTERN const char * pn_condition_get_name(pn_condition_t *condition)
Returns the name associated with the exceptional condition, or NULL if there is no conditional inform...
PN_EXTERN int pn_condition_redirect_port(pn_condition_t *condition)
Retrieves the redirect port from the additional information associated with the condition.