00001 #ifndef PROTON_DELIVERY_H 00002 #define PROTON_DELIVERY_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/disposition.h> 00027 #include <proton/type_compat.h> 00028 #include <stddef.h> 00029 00030 #ifdef __cplusplus 00031 extern "C" { 00032 #endif 00033 00034 /** 00035 * @file 00036 * 00037 * Delivery API for the proton Engine. 00038 * 00039 * @defgroup delivery Delivery 00040 * @ingroup engine 00041 * @{ 00042 */ 00043 00044 /** 00045 * An AMQP delivery tag. 00046 */ 00047 typedef pn_bytes_t pn_delivery_tag_t; 00048 00049 /** 00050 * Construct a delivery tag. 00051 * 00052 * @param[in] bytes a pointer to the beginning of the tag 00053 * @param[in] size the size of the tag 00054 * @return the delivery tag 00055 */ 00056 PN_EXTERN pn_delivery_tag_t pn_dtag(const char *bytes, size_t size); 00057 00058 /** 00059 * Create a delivery on a link. 00060 * 00061 * Every delivery object within a link must be supplied with a unique 00062 * tag. Links maintain a sequence of delivery object in the order that 00063 * they are created. 00064 * 00065 * @param[in] link a link object 00066 * @param[in] tag the delivery tag 00067 * @return a newly created delivery, or NULL if there was an error 00068 */ 00069 PN_EXTERN pn_delivery_t *pn_delivery(pn_link_t *link, pn_delivery_tag_t tag); 00070 00071 /** 00072 * @deprecated 00073 * Get the application context that is associated with a delivery object. 00074 * 00075 * The application context for a delivery may be set using 00076 * ::pn_delivery_set_context. 00077 * 00078 * @param[in] delivery the delivery whose context is to be returned. 00079 * @return the application context for the delivery object 00080 */ 00081 PN_EXTERN void *pn_delivery_get_context(pn_delivery_t *delivery); 00082 00083 /** 00084 * @deprecated 00085 * Set a new application context for a delivery object. 00086 * 00087 * The application context for a delivery object may be retrieved using 00088 * ::pn_delivery_get_context. 00089 * 00090 * @param[in] delivery the delivery object 00091 * @param[in] context the application context 00092 */ 00093 PN_EXTERN void pn_delivery_set_context(pn_delivery_t *delivery, void *context); 00094 00095 /** 00096 * Get the attachments that are associated with a delivery object. 00097 * 00098 * @param[in] delivery the delivery whose attachments are to be returned. 00099 * @return the attachments for the delivery object 00100 */ 00101 PN_EXTERN pn_record_t *pn_delivery_attachments(pn_delivery_t *delivery); 00102 00103 /** 00104 * Get the tag for a delivery object. 00105 * 00106 * @param[in] delivery a delivery object 00107 * @return the delivery tag 00108 */ 00109 PN_EXTERN pn_delivery_tag_t pn_delivery_tag(pn_delivery_t *delivery); 00110 00111 /** 00112 * Get the parent link for a delivery object. 00113 * 00114 * @param[in] delivery a delivery object 00115 * @return the parent link 00116 */ 00117 PN_EXTERN pn_link_t *pn_delivery_link(pn_delivery_t *delivery); 00118 00119 /** 00120 * Get the local disposition for a delivery. 00121 * 00122 * The pointer returned by this object is valid until the delivery is 00123 * settled. 00124 * 00125 * @param[in] delivery a delivery object 00126 * @return a pointer to the local disposition 00127 */ 00128 PN_EXTERN pn_disposition_t *pn_delivery_local(pn_delivery_t *delivery); 00129 00130 /** 00131 * Get the local disposition state for a delivery. 00132 * 00133 * @param[in] delivery a delivery object 00134 * @return the local disposition state 00135 */ 00136 PN_EXTERN uint64_t pn_delivery_local_state(pn_delivery_t *delivery); 00137 00138 /** 00139 * Get the remote disposition for a delivery. 00140 * 00141 * The pointer returned by this object is valid until the delivery is 00142 * settled. 00143 * 00144 * @param[in] delivery a delivery object 00145 * @return a pointer to the remote disposition 00146 */ 00147 PN_EXTERN pn_disposition_t *pn_delivery_remote(pn_delivery_t *delivery); 00148 00149 /** 00150 * Get the remote disposition state for a delivery. 00151 * 00152 * @param[in] delivery a delivery object 00153 * @return the remote disposition state 00154 */ 00155 PN_EXTERN uint64_t pn_delivery_remote_state(pn_delivery_t *delivery); 00156 00157 /** 00158 * Check if a delivery is remotely settled. 00159 * 00160 * @param[in] delivery a delivery object 00161 * @return true if the delivery is settled at the remote endpoint, false otherwise 00162 */ 00163 PN_EXTERN bool pn_delivery_settled(pn_delivery_t *delivery); 00164 00165 /** 00166 * Get the amount of pending message data for a delivery. 00167 * 00168 * @param[in] delivery a delivery object 00169 * @return the amount of pending message data in bytes 00170 */ 00171 PN_EXTERN size_t pn_delivery_pending(pn_delivery_t *delivery); 00172 00173 /** 00174 * Check if a delivery only has partial message data. 00175 * 00176 * @param[in] delivery a delivery object 00177 * @return true if the delivery only contains part of a message, false otherwise 00178 */ 00179 PN_EXTERN bool pn_delivery_partial(pn_delivery_t *delivery); 00180 00181 /** 00182 * Check if a delivery is writable. 00183 * 00184 * A delivery is considered writable if it is the current delivery on 00185 * an outgoing link, and the link has positive credit. 00186 * 00187 * @param[in] delivery a delivery object 00188 * @return true if the delivery is writable, false otherwise 00189 */ 00190 PN_EXTERN bool pn_delivery_writable(pn_delivery_t *delivery); 00191 00192 /** 00193 * Check if a delivery is readable. 00194 * 00195 * A delivery is considered readable if it is the current delivery on 00196 * an incoming link. 00197 * 00198 * @param[in] delivery a delivery object 00199 * @return true if the delivery is readable, false otherwise 00200 */ 00201 PN_EXTERN bool pn_delivery_readable(pn_delivery_t *delivery); 00202 00203 /** 00204 * Check if a delivery is updated. 00205 * 00206 * A delivery is considered updated whenever the peer communicates a 00207 * new disposition for the delivery. Once a delivery becomes updated, 00208 * it will remain so until ::pn_delivery_clear is called. 00209 * 00210 * @param[in] delivery a delivery object 00211 * @return true if the delivery is updated, false otherwise 00212 */ 00213 PN_EXTERN bool pn_delivery_updated(pn_delivery_t *delivery); 00214 00215 /** 00216 * Update the disposition of a delivery. 00217 * 00218 * When update is invoked the updated disposition of the delivery will 00219 * be communicated to the peer. 00220 * 00221 * @param[in] delivery a delivery object 00222 * @param[in] state the updated delivery state 00223 */ 00224 PN_EXTERN void pn_delivery_update(pn_delivery_t *delivery, uint64_t state); 00225 00226 /** 00227 * Clear the updated flag for a delivery. 00228 * 00229 * See ::pn_delivery_updated. 00230 * 00231 * @param[in] delivery a delivery object 00232 */ 00233 PN_EXTERN void pn_delivery_clear(pn_delivery_t *delivery); 00234 00235 /** 00236 * Return true if delivery is the current delivery for its link. 00237 * 00238 * @param[in] delivery a delivery object 00239 * @return true if delivery is the current delivery for its link. 00240 */ 00241 PN_EXTERN bool pn_delivery_current(pn_delivery_t *delivery); 00242 00243 /** 00244 * Settle a delivery. 00245 * 00246 * A settled delivery can never be used again. 00247 * 00248 * NOTE: if pn_delivery_current(delivery) is true before the call then 00249 * pn_link_advance(pn_delivery_link(deliver)) is called automatically. 00250 * 00251 * @param[in] delivery a delivery object 00252 */ 00253 PN_EXTERN void pn_delivery_settle(pn_delivery_t *delivery); 00254 00255 /** 00256 * Utility function for printing details of a delivery. 00257 * 00258 * @param[in] delivery a delivery object 00259 */ 00260 PN_EXTERN void pn_delivery_dump(pn_delivery_t *delivery); 00261 00262 /** 00263 * Check if a delivery is buffered. 00264 * 00265 * A delivery that is buffered has not yet been written to the wire. 00266 * 00267 * Note that returning false does not imply that a delivery was 00268 * definitely written to the wire. If false is returned, it is not 00269 * known whether the delivery was actually written to the wire or not. 00270 * 00271 * @param[in] delivery a delivery object 00272 * @return true if the delivery is buffered 00273 */ 00274 PN_EXTERN bool pn_delivery_buffered(pn_delivery_t *delivery); 00275 00276 /** 00277 * Extracts the first delivery on the connection that has pending 00278 * operations. 00279 * 00280 * Retrieves the first delivery on the Connection that has pending 00281 * operations. A readable delivery indicates message data is waiting 00282 * to be read. A writable delivery indicates that message data may be 00283 * sent. An updated delivery indicates that the delivery's disposition 00284 * has changed. A delivery will never be both readable and writible, 00285 * but it may be both readable and updated or both writiable and 00286 * updated. 00287 * 00288 * @param[in] connection the connection 00289 * @return the first delivery object that needs to be serviced, else 00290 * NULL if none 00291 */ 00292 PN_EXTERN pn_delivery_t *pn_work_head(pn_connection_t *connection); 00293 00294 /** 00295 * Get the next delivery on the connection that needs has pending 00296 * operations. 00297 * 00298 * @param[in] delivery the previous delivery retrieved from 00299 * either pn_work_head or pn_work_next 00300 * @return the next delivery that has pending operations, else 00301 * NULL if none 00302 */ 00303 PN_EXTERN pn_delivery_t *pn_work_next(pn_delivery_t *delivery); 00304 00305 /** @} 00306 */ 00307 00308 #ifdef __cplusplus 00309 } 00310 #endif 00311 00312 #endif /* delivery.h */