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