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