proton  0
disposition.h
Go to the documentation of this file.
1 #ifndef PROTON_DISPOSITION_H
2 #define PROTON_DISPOSITION_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/type_compat.h>
27 #include <proton/condition.h>
28 #include <stddef.h>
29 #include <sys/types.h>
30 
31 #ifdef __cplusplus
32 extern "C" {
33 #endif
34 
35 /**
36  * @file
37  *
38  * Disposition API for the proton Engine.
39  *
40  * @defgroup disposition Disposition
41  * @ingroup delivery
42  * @{
43  */
44 
45 /**
46  * Dispositions record the current state and/or final outcome of a
47  * transfer. Every delivery contains both a local and remote
48  * disposition. The local disposition holds the local state of the
49  * delivery, and the remote disposition holds the last known remote
50  * state of the delivery.
51  */
53 
54 /**
55  * The PN_RECEIVED delivery state is a non terminal state indicating
56  * how much (if any) message data has been received for a delivery.
57  */
58 #define PN_RECEIVED (0x0000000000000023)
59 
60 /**
61  * The PN_ACCEPTED delivery state is a terminal state indicating that
62  * the delivery was successfully processed. Once in this state there
63  * will be no further state changes prior to the delivery being
64  * settled.
65  */
66 #define PN_ACCEPTED (0x0000000000000024)
67 
68 /**
69  * The PN_REJECTED delivery state is a terminal state indicating that
70  * the delivery could not be processed due to some error condition.
71  * Once in this state there will be no further state changes prior to
72  * the delivery being settled.
73  */
74 #define PN_REJECTED (0x0000000000000025)
75 
76 /**
77  * The PN_RELEASED delivery state is a terminal state indicating that
78  * the delivery is being returned to the sender. Once in this state
79  * there will be no further state changes prior to the delivery being
80  * settled.
81  */
82 #define PN_RELEASED (0x0000000000000026)
83 
84 /**
85  * The PN_MODIFIED delivery state is a terminal state indicating that
86  * the delivery is being returned to the sender and should be
87  * annotated by the sender prior to further delivery attempts. Once in
88  * this state there will be no further state changes prior to the
89  * delivery being settled.
90  */
91 #define PN_MODIFIED (0x0000000000000027)
92 
93 /**
94  * Get the type of a disposition.
95  *
96  * Defined values are:
97  *
98  * - ::PN_RECEIVED
99  * - ::PN_ACCEPTED
100  * - ::PN_REJECTED
101  * - ::PN_RELEASED
102  * - ::PN_MODIFIED
103  *
104  * @param[in] disposition a disposition object
105  * @return the type of the disposition
106  */
107 PN_EXTERN uint64_t pn_disposition_type(pn_disposition_t *disposition);
108 
109 /**
110  * Access the condition object associated with a disposition.
111  *
112  * The ::pn_condition_t object retrieved by this operation may be
113  * modified prior to updating a delivery. When a delivery is updated,
114  * the condition described by the disposition is reported to the peer
115  * if applicable to the current delivery state, e.g. states such as
116  * ::PN_REJECTED.
117  *
118  * The pointer returned by this operation is valid until the parent
119  * delivery is settled.
120  *
121  * @param[in] disposition a disposition object
122  * @return a pointer to the disposition condition
123  */
125 
126 /**
127  * Access the disposition as a raw pn_data_t.
128  *
129  * Dispositions are an extension point in the AMQP protocol. The
130  * disposition interface provides setters/getters for those
131  * dispositions that are predefined by the specification, however
132  * access to the raw disposition data is provided so that other
133  * dispositions can be used.
134  *
135  * The ::pn_data_t pointer returned by this operation is valid until
136  * the parent delivery is settled.
137  *
138  * @param[in] disposition a disposition object
139  * @return a pointer to the raw disposition data
140  */
142 
143 /**
144  * Get the section number associated with a disposition.
145  *
146  * @param[in] disposition a disposition object
147  * @return a section number
148  */
150 
151 /**
152  * Set the section number associated with a disposition.
153  *
154  * @param[in] disposition a disposition object
155  * @param[in] section_number a section number
156  */
157 PN_EXTERN void pn_disposition_set_section_number(pn_disposition_t *disposition, uint32_t section_number);
158 
159 /**
160  * Get the section offset associated with a disposition.
161  *
162  * @param[in] disposition a disposition object
163  * @return a section offset
164  */
166 
167 /**
168  * Set the section offset associated with a disposition.
169  *
170  * @param[in] disposition a disposition object
171  * @param[in] section_offset a section offset
172  */
173 PN_EXTERN void pn_disposition_set_section_offset(pn_disposition_t *disposition, uint64_t section_offset);
174 
175 /**
176  * Check if a disposition has the failed flag set.
177  *
178  * @param[in] disposition a disposition object
179  * @return true if the disposition has the failed flag set, false otherwise
180  */
182 
183 /**
184  * Set the failed flag on a disposition.
185  *
186  * @param[in] disposition a disposition object
187  * @param[in] failed the value of the failed flag
188  */
189 PN_EXTERN void pn_disposition_set_failed(pn_disposition_t *disposition, bool failed);
190 
191 /**
192  * Check if a disposition has the undeliverable flag set.
193  *
194  * @param[in] disposition a disposition object
195  * @return true if the disposition has the undeliverable flag set, false otherwise
196  */
198 
199 /**
200  * Set the undeliverable flag on a disposition.
201  *
202  * @param[in] disposition a disposition object
203  * @param[in] undeliverable the value of the undeliverable flag
204  */
205 PN_EXTERN void pn_disposition_set_undeliverable(pn_disposition_t *disposition, bool undeliverable);
206 
207 /**
208  * Access the annotations associated with a disposition.
209  *
210  * The ::pn_data_t object retrieved by this operation may be modified
211  * prior to updating a delivery. When a delivery is updated, the
212  * annotations described by the ::pn_data_t are reported to the peer
213  * if applicable to the current delivery state, e.g. states such as
214  * ::PN_MODIFIED. The ::pn_data_t must be empty or contain a symbol
215  * keyed map.
216  *
217  * The pointer returned by this operation is valid until the parent
218  * delivery is settled.
219  *
220  * @param[in] disposition a disposition object
221  * @return the annotations associated with the disposition
222  */
224 
225 /** @}
226  */
227 
228 #ifdef __cplusplus
229 }
230 #endif
231 
232 #endif /* disposition.h */
PN_EXTERN void pn_disposition_set_section_number(pn_disposition_t *disposition, uint32_t section_number)
Set the section number associated with a disposition.
The Condition API for the proton Engine.
PN_EXTERN bool pn_disposition_is_undeliverable(pn_disposition_t *disposition)
Check if a disposition has the undeliverable flag set.
struct pn_disposition_t pn_disposition_t
Dispositions record the current state and/or final outcome of a transfer.
Definition: disposition.h:52
PN_EXTERN uint64_t pn_disposition_get_section_offset(pn_disposition_t *disposition)
Get the section offset associated with a disposition.
struct pn_data_t pn_data_t
An AMQP Data object.
Definition: codec.h:352
PN_EXTERN pn_data_t * pn_disposition_annotations(pn_disposition_t *disposition)
Access the annotations associated with a disposition.
PN_EXTERN uint64_t pn_disposition_type(pn_disposition_t *disposition)
Get the type of a disposition.
PN_EXTERN pn_data_t * pn_disposition_data(pn_disposition_t *disposition)
Access the disposition as a raw pn_data_t.
#define PN_EXTERN
Definition: import_export.h:53
PN_EXTERN void pn_disposition_set_undeliverable(pn_disposition_t *disposition, bool undeliverable)
Set the undeliverable flag on a disposition.
PN_EXTERN bool pn_disposition_is_failed(pn_disposition_t *disposition)
Check if a disposition has the failed flag set.
PN_EXTERN uint32_t pn_disposition_get_section_number(pn_disposition_t *disposition)
Get the section number associated with a disposition.
PN_EXTERN pn_condition_t * pn_disposition_condition(pn_disposition_t *disposition)
Access the condition object associated with a disposition.
PN_EXTERN void pn_disposition_set_failed(pn_disposition_t *disposition, bool failed)
Set the failed flag on a disposition.
struct pn_condition_t pn_condition_t
An AMQP Condition object.
Definition: condition.h:65
PN_EXTERN void pn_disposition_set_section_offset(pn_disposition_t *disposition, uint64_t section_offset)
Set the section offset associated with a disposition.