00001 #ifndef PROTON_DISPOSITION_H 00002 #define PROTON_DISPOSITION_H 1 00003 00004 /* 00005 * 00006 * Licensed to the Apache Software Foundation (ASF) under one 00007 * or more contributor license agreements. See the NOTICE file 00008 * distributed with this work for additional information 00009 * regarding copyright ownership. The ASF licenses this file 00010 * to you under the Apache License, Version 2.0 (the 00011 * "License"); you may not use this file except in compliance 00012 * with the License. You may obtain a copy of the License at 00013 * 00014 * http://www.apache.org/licenses/LICENSE-2.0 00015 * 00016 * Unless required by applicable law or agreed to in writing, 00017 * software distributed under the License is distributed on an 00018 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 00019 * KIND, either express or implied. See the License for the 00020 * specific language governing permissions and limitations 00021 * under the License. 00022 * 00023 */ 00024 00025 #include <proton/import_export.h> 00026 #include <proton/type_compat.h> 00027 #include <proton/condition.h> 00028 #include <stddef.h> 00029 00030 #ifdef __cplusplus 00031 extern "C" { 00032 #endif 00033 00034 /** 00035 * @file 00036 * 00037 * Disposition API for the proton Engine. 00038 * 00039 * @defgroup disposition Disposition 00040 * @ingroup delivery 00041 * @{ 00042 */ 00043 00044 /** 00045 * Dispositions record the current state and/or final outcome of a 00046 * transfer. Every delivery contains both a local and remote 00047 * disposition. The local disposition holds the local state of the 00048 * delivery, and the remote disposition holds the last known remote 00049 * state of the delivery. 00050 */ 00051 typedef struct pn_disposition_t pn_disposition_t; 00052 00053 /** 00054 * The PN_RECEIVED delivery state is a non terminal state indicating 00055 * how much (if any) message data has been received for a delivery. 00056 */ 00057 #define PN_RECEIVED (0x0000000000000023) 00058 00059 /** 00060 * The PN_ACCEPTED delivery state is a terminal state indicating that 00061 * the delivery was successfully processed. Once in this state there 00062 * will be no further state changes prior to the delivery being 00063 * settled. 00064 */ 00065 #define PN_ACCEPTED (0x0000000000000024) 00066 00067 /** 00068 * The PN_REJECTED delivery state is a terminal state indicating that 00069 * the delivery could not be processed due to some error condition. 00070 * Once in this state there will be no further state changes prior to 00071 * the delivery being settled. 00072 */ 00073 #define PN_REJECTED (0x0000000000000025) 00074 00075 /** 00076 * The PN_RELEASED delivery state is a terminal state indicating that 00077 * the delivery is being returned to the sender. Once in this state 00078 * there will be no further state changes prior to the delivery being 00079 * settled. 00080 */ 00081 #define PN_RELEASED (0x0000000000000026) 00082 00083 /** 00084 * The PN_MODIFIED delivery state is a terminal state indicating that 00085 * the delivery is being returned to the sender and should be 00086 * annotated by the sender prior to further delivery attempts. Once in 00087 * this state there will be no further state changes prior to the 00088 * delivery being settled. 00089 */ 00090 #define PN_MODIFIED (0x0000000000000027) 00091 00092 /** 00093 * Get the type of a disposition. 00094 * 00095 * Defined values are: 00096 * 00097 * - ::PN_RECEIVED 00098 * - ::PN_ACCEPTED 00099 * - ::PN_REJECTED 00100 * - ::PN_RELEASED 00101 * - ::PN_MODIFIED 00102 * 00103 * @param[in] disposition a disposition object 00104 * @return the type of the disposition 00105 */ 00106 PN_EXTERN uint64_t pn_disposition_type(pn_disposition_t *disposition); 00107 00108 /** 00109 * Access the condition object associated with a disposition. 00110 * 00111 * The ::pn_condition_t object retrieved by this operation may be 00112 * modified prior to updating a delivery. When a delivery is updated, 00113 * the condition described by the disposition is reported to the peer 00114 * if applicable to the current delivery state, e.g. states such as 00115 * ::PN_REJECTED. 00116 * 00117 * The pointer returned by this operation is valid until the parent 00118 * delivery is settled. 00119 * 00120 * @param[in] disposition a disposition object 00121 * @return a pointer to the disposition condition 00122 */ 00123 PN_EXTERN pn_condition_t *pn_disposition_condition(pn_disposition_t *disposition); 00124 00125 /** 00126 * Access the disposition as a raw pn_data_t. 00127 * 00128 * Dispositions are an extension point in the AMQP protocol. The 00129 * disposition interface provides setters/getters for those 00130 * dispositions that are predefined by the specification, however 00131 * access to the raw disposition data is provided so that other 00132 * dispositions can be used. 00133 * 00134 * The ::pn_data_t pointer returned by this operation is valid until 00135 * the parent delivery is settled. 00136 * 00137 * @param[in] disposition a disposition object 00138 * @return a pointer to the raw disposition data 00139 */ 00140 PN_EXTERN pn_data_t *pn_disposition_data(pn_disposition_t *disposition); 00141 00142 /** 00143 * Get the section number associated with a disposition. 00144 * 00145 * @param[in] disposition a disposition object 00146 * @return a section number 00147 */ 00148 PN_EXTERN uint32_t pn_disposition_get_section_number(pn_disposition_t *disposition); 00149 00150 /** 00151 * Set the section number associated with a disposition. 00152 * 00153 * @param[in] disposition a disposition object 00154 * @param[in] section_number a section number 00155 */ 00156 PN_EXTERN void pn_disposition_set_section_number(pn_disposition_t *disposition, uint32_t section_number); 00157 00158 /** 00159 * Get the section offset associated with a disposition. 00160 * 00161 * @param[in] disposition a disposition object 00162 * @return a section offset 00163 */ 00164 PN_EXTERN uint64_t pn_disposition_get_section_offset(pn_disposition_t *disposition); 00165 00166 /** 00167 * Set the section offset associated with a disposition. 00168 * 00169 * @param[in] disposition a disposition object 00170 * @param[in] section_offset a section offset 00171 */ 00172 PN_EXTERN void pn_disposition_set_section_offset(pn_disposition_t *disposition, uint64_t section_offset); 00173 00174 /** 00175 * Check if a disposition has the failed flag set. 00176 * 00177 * @param[in] disposition a disposition object 00178 * @return true if the disposition has the failed flag set, false otherwise 00179 */ 00180 PN_EXTERN bool pn_disposition_is_failed(pn_disposition_t *disposition); 00181 00182 /** 00183 * Set the failed flag on a disposition. 00184 * 00185 * @param[in] disposition a disposition object 00186 * @param[in] failed the value of the failed flag 00187 */ 00188 PN_EXTERN void pn_disposition_set_failed(pn_disposition_t *disposition, bool failed); 00189 00190 /** 00191 * Check if a disposition has the undeliverable flag set. 00192 * 00193 * @param[in] disposition a disposition object 00194 * @return true if the disposition has the undeliverable flag set, false otherwise 00195 */ 00196 PN_EXTERN bool pn_disposition_is_undeliverable(pn_disposition_t *disposition); 00197 00198 /** 00199 * Set the undeliverable flag on a disposition. 00200 * 00201 * @param[in] disposition a disposition object 00202 * @param[in] undeliverable the value of the undeliverable flag 00203 */ 00204 PN_EXTERN void pn_disposition_set_undeliverable(pn_disposition_t *disposition, bool undeliverable); 00205 00206 /** 00207 * Access the annotations associated with a disposition. 00208 * 00209 * The ::pn_data_t object retrieved by this operation may be modified 00210 * prior to updating a delivery. When a delivery is updated, the 00211 * annotations described by the ::pn_data_t are reported to the peer 00212 * if applicable to the current delivery state, e.g. states such as 00213 * ::PN_MODIFIED. The ::pn_data_t must be empty or contain a symbol 00214 * keyed map. 00215 * 00216 * The pointer returned by this operation is valid until the parent 00217 * delivery is settled. 00218 * 00219 * @param[in] disposition a disposition object 00220 * @return the annotations associated with the disposition 00221 */ 00222 PN_EXTERN pn_data_t *pn_disposition_annotations(pn_disposition_t *disposition); 00223 00224 /** @} 00225 */ 00226 00227 #ifdef __cplusplus 00228 } 00229 #endif 00230 00231 #endif /* disposition.h */