proton
0
Main Page
Related Pages
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Macros
Groups
Pages
include
proton
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
*/
65
typedef
struct
pn_condition_t
pn_condition_t
;
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
*/
75
PN_EXTERN
bool
pn_condition_is_set
(
pn_condition_t
*condition);
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
*/
87
PN_EXTERN
void
pn_condition_clear
(
pn_condition_t
*condition);
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
*/
113
PN_EXTERN
const
char
*
pn_condition_get_description
(
pn_condition_t
*condition);
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
*/
133
PN_EXTERN
pn_data_t
*
pn_condition_info
(
pn_condition_t
*condition);
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
*/
141
PN_EXTERN
bool
pn_condition_is_redirect
(
pn_condition_t
*condition);
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
*/
161
PN_EXTERN
int
pn_condition_redirect_port
(
pn_condition_t
*condition);
162
163
/** @}
164
*/
165
166
#ifdef __cplusplus
167
}
168
#endif
169
170
#endif
/* condition.h */
Generated on Thu Jul 10 2014 02:10:59 for proton by
1.8.3.1