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