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
proton-c
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 Mon Jun 2 2014 22:59:05 for proton by
1.8.1.2