proton  0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
delivery.h
Go to the documentation of this file.
1 #ifndef PROTON_DELIVERY_H
2 #define PROTON_DELIVERY_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/disposition.h>
27 #include <proton/type_compat.h>
28 #include <stddef.h>
29 
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33 
34 /**
35  * @file
36  *
37  * Delivery API for the proton Engine.
38  *
39  * @defgroup delivery Delivery
40  * @ingroup engine
41  * @{
42  */
43 
44 /**
45  * An AMQP delivery tag.
46  */
48 
49 #ifndef SWIG // older versions of SWIG choke on this:
50 /**
51  * Construct a delivery tag.
52  *
53  * @param[in] bytes a pointer to the beginning of the tag
54  * @param[in] size the size of the tag
55  * @return the delivery tag
56  */
57 static inline pn_delivery_tag_t pn_dtag(const char *bytes, size_t size) {
58  pn_delivery_tag_t dtag = {size, bytes};
59  return dtag;
60 }
61 #endif
62 
63 /**
64  * Create a delivery on a link.
65  *
66  * Every delivery object within a link must be supplied with a unique
67  * tag. Links maintain a sequence of delivery object in the order that
68  * they are created.
69  *
70  * @param[in] link a link object
71  * @param[in] tag the delivery tag
72  * @return a newly created delivery, or NULL if there was an error
73  */
74 PN_EXTERN pn_delivery_t *pn_delivery(pn_link_t *link, pn_delivery_tag_t tag);
75 
76 /**
77  * @deprecated
78  * Get the application context that is associated with a delivery object.
79  *
80  * The application context for a delivery may be set using
81  * ::pn_delivery_set_context.
82  *
83  * @param[in] delivery the delivery whose context is to be returned.
84  * @return the application context for the delivery object
85  */
87 
88 /**
89  * @deprecated
90  * Set a new application context for a delivery object.
91  *
92  * The application context for a delivery object may be retrieved using
93  * ::pn_delivery_get_context.
94  *
95  * @param[in] delivery the delivery object
96  * @param[in] context the application context
97  */
98 PN_EXTERN void pn_delivery_set_context(pn_delivery_t *delivery, void *context);
99 
100 /**
101  * Get the attachments that are associated with a delivery object.
102  *
103  * @param[in] delivery the delivery whose attachments are to be returned.
104  * @return the attachments for the delivery object
105  */
107 
108 /**
109  * Get the tag for a delivery object.
110  *
111  * @param[in] delivery a delivery object
112  * @return the delivery tag
113  */
114 PN_EXTERN pn_delivery_tag_t pn_delivery_tag(pn_delivery_t *delivery);
115 
116 /**
117  * Get the parent link for a delivery object.
118  *
119  * @param[in] delivery a delivery object
120  * @return the parent link
121  */
123 
124 /**
125  * Get the local disposition for a delivery.
126  *
127  * The pointer returned by this object is valid until the delivery is
128  * settled.
129  *
130  * @param[in] delivery a delivery object
131  * @return a pointer to the local disposition
132  */
134 
135 /**
136  * Get the local disposition state for a delivery.
137  *
138  * @param[in] delivery a delivery object
139  * @return the local disposition state
140  */
142 
143 /**
144  * Get the remote disposition for a delivery.
145  *
146  * The pointer returned by this object is valid until the delivery is
147  * settled.
148  *
149  * @param[in] delivery a delivery object
150  * @return a pointer to the remote disposition
151  */
153 
154 /**
155  * Get the remote disposition state for a delivery.
156  *
157  * @param[in] delivery a delivery object
158  * @return the remote disposition state
159  */
161 
162 /**
163  * Check if a delivery is remotely settled.
164  *
165  * @param[in] delivery a delivery object
166  * @return true if the delivery is settled at the remote endpoint, false otherwise
167  */
169 
170 /**
171  * Get the amount of pending message data for a delivery.
172  *
173  * @param[in] delivery a delivery object
174  * @return the amount of pending message data in bytes
175  */
177 
178 /**
179  * Check if a delivery only has partial message data.
180  *
181  * @param[in] delivery a delivery object
182  * @return true if the delivery only contains part of a message, false otherwise
183  */
185 
186 /**
187  * Check if a delivery is writable.
188  *
189  * A delivery is considered writable if it is the current delivery on
190  * an outgoing link, and the link has positive credit.
191  *
192  * @param[in] delivery a delivery object
193  * @return true if the delivery is writable, false otherwise
194  */
196 
197 /**
198  * Check if a delivery is readable.
199  *
200  * A delivery is considered readable if it is the current delivery on
201  * an incoming link.
202  *
203  * @param[in] delivery a delivery object
204  * @return true if the delivery is readable, false otherwise
205  */
207 
208 /**
209  * Check if a delivery is updated.
210  *
211  * A delivery is considered updated whenever the peer communicates a
212  * new disposition for the delivery. Once a delivery becomes updated,
213  * it will remain so until ::pn_delivery_clear is called.
214  *
215  * @param[in] delivery a delivery object
216  * @return true if the delivery is updated, false otherwise
217  */
219 
220 /**
221  * Update the disposition of a delivery.
222  *
223  * When update is invoked the updated disposition of the delivery will
224  * be communicated to the peer.
225  *
226  * @param[in] delivery a delivery object
227  * @param[in] state the updated delivery state
228  */
229 PN_EXTERN void pn_delivery_update(pn_delivery_t *delivery, uint64_t state);
230 
231 /**
232  * Clear the updated flag for a delivery.
233  *
234  * See ::pn_delivery_updated.
235  *
236  * @param[in] delivery a delivery object
237  */
239 
240 /**
241  * Return true if delivery is the current delivery for its link.
242  *
243  * @param[in] delivery a delivery object
244  * @return true if delivery is the current delivery for its link.
245  */
247 
248 /**
249  * Settle a delivery.
250  *
251  * A settled delivery can never be used again.
252  *
253  * NOTE: if pn_delivery_current(delivery) is true before the call then
254  * pn_link_advance(pn_delivery_link(deliver)) is called automatically.
255  *
256  * @param[in] delivery a delivery object
257  */
259 
260 /**
261  * Utility function for printing details of a delivery.
262  *
263  * @param[in] delivery a delivery object
264  */
266 
267 /**
268  * Check if a delivery is buffered.
269  *
270  * A delivery that is buffered has not yet been written to the wire.
271  *
272  * Note that returning false does not imply that a delivery was
273  * definitely written to the wire. If false is returned, it is not
274  * known whether the delivery was actually written to the wire or not.
275  *
276  * @param[in] delivery a delivery object
277  * @return true if the delivery is buffered
278  */
280 
281 /**
282  * Extracts the first delivery on the connection that has pending
283  * operations.
284  *
285  * Retrieves the first delivery on the Connection that has pending
286  * operations. A readable delivery indicates message data is waiting
287  * to be read. A writable delivery indicates that message data may be
288  * sent. An updated delivery indicates that the delivery's disposition
289  * has changed. A delivery will never be both readable and writible,
290  * but it may be both readable and updated or both writiable and
291  * updated.
292  *
293  * @param[in] connection the connection
294  * @return the first delivery object that needs to be serviced, else
295  * NULL if none
296  */
298 
299 /**
300  * Get the next delivery on the connection that needs has pending
301  * operations.
302  *
303  * @param[in] delivery the previous delivery retrieved from
304  * either pn_work_head or pn_work_next
305  * @return the next delivery that has pending operations, else
306  * NULL if none
307  */
309 
310 /** @}
311  */
312 
313 #ifdef __cplusplus
314 }
315 #endif
316 
317 #endif /* delivery.h */
PN_EXTERN bool pn_delivery_current(pn_delivery_t *delivery)
Return true if delivery is the current delivery for its link.
PN_EXTERN pn_record_t * pn_delivery_attachments(pn_delivery_t *delivery)
Get the attachments that are associated with a delivery object.
struct pn_disposition_t pn_disposition_t
Dispositions record the current state and/or final outcome of a transfer.
Definition: disposition.h:51
PN_EXTERN uint64_t pn_delivery_local_state(pn_delivery_t *delivery)
Get the local disposition state for a delivery.
PN_EXTERN bool pn_delivery_buffered(pn_delivery_t *delivery)
Check if a delivery is buffered.
PN_EXTERN pn_delivery_t * pn_work_head(pn_connection_t *connection)
Extracts the first delivery on the connection that has pending operations.
struct pn_record_t pn_record_t
Definition: object.h:46
PN_EXTERN pn_delivery_t * pn_work_next(pn_delivery_t *delivery)
Get the next delivery on the connection that needs has pending operations.
PN_EXTERN void pn_delivery_update(pn_delivery_t *delivery, uint64_t state)
Update the disposition of a delivery.
PN_EXTERN pn_disposition_t * pn_delivery_remote(pn_delivery_t *delivery)
Get the remote disposition for a delivery.
PN_EXTERN void pn_delivery_settle(pn_delivery_t *delivery)
Settle a delivery.
PN_EXTERN bool pn_delivery_writable(pn_delivery_t *delivery)
Check if a delivery is writable.
PN_EXTERN bool pn_delivery_settled(pn_delivery_t *delivery)
Check if a delivery is remotely settled.
#define PN_EXTERN
Definition: import_export.h:53
Disposition API for the proton Engine.
pn_bytes_t pn_delivery_tag_t
An AMQP delivery tag.
Definition: delivery.h:47
struct pn_connection_t pn_connection_t
An AMQP Connection object.
Definition: types.h:111
PN_EXTERN pn_delivery_t * pn_delivery(pn_link_t *link, pn_delivery_tag_t tag)
Create a delivery on a link.
PN_EXTERN bool pn_delivery_updated(pn_delivery_t *delivery)
Check if a delivery is updated.
PN_EXTERN void * pn_delivery_get_context(pn_delivery_t *delivery)
PN_EXTERN bool pn_delivery_readable(pn_delivery_t *delivery)
Check if a delivery is readable.
PN_EXTERN pn_delivery_tag_t pn_delivery_tag(pn_delivery_t *delivery)
Get the tag for a delivery object.
struct pn_link_t pn_link_t
An AMQP Link object.
Definition: types.h:141
PN_EXTERN void pn_delivery_clear(pn_delivery_t *delivery)
Clear the updated flag for a delivery.
PN_EXTERN void pn_delivery_set_context(pn_delivery_t *delivery, void *context)
struct pn_delivery_t pn_delivery_t
An AMQP Delivery object.
Definition: types.h:231
PN_EXTERN uint64_t pn_delivery_remote_state(pn_delivery_t *delivery)
Get the remote disposition state for a delivery.
PN_EXTERN pn_link_t * pn_delivery_link(pn_delivery_t *delivery)
Get the parent link for a delivery object.
PN_EXTERN bool pn_delivery_partial(pn_delivery_t *delivery)
Check if a delivery only has partial message data.
PN_EXTERN size_t pn_delivery_pending(pn_delivery_t *delivery)
Get the amount of pending message data for a delivery.
PN_EXTERN pn_disposition_t * pn_delivery_local(pn_delivery_t *delivery)
Get the local disposition for a delivery.
Definition: types.h:60
PN_EXTERN void pn_delivery_dump(pn_delivery_t *delivery)
Utility function for printing details of a delivery.