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