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