proton  0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups 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 #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  */
48 typedef struct pn_delivery_tag_t {
49  size_t size;
50  const char *bytes;
52 
53 #ifndef SWIG // older versions of SWIG choke on this:
54 /**
55  * Construct a delivery tag.
56  *
57  * @param[in] bytes a pointer to the beginning of the tag
58  * @param[in] size the size of the tag
59  * @return the delivery tag
60  */
61 static inline pn_delivery_tag_t pn_dtag(const char *bytes, size_t size) {
62  pn_delivery_tag_t dtag = {size, bytes};
63  return dtag;
64 }
65 #endif
66 
67 /**
68  * Create a delivery on a link.
69  *
70  * Every delivery object within a link must be supplied with a unique
71  * tag. Links maintain a sequence of delivery object in the order that
72  * they are created.
73  *
74  * @param[in] link a link object
75  * @param[in] tag the delivery tag
76  * @return a newly created delivery, or NULL if there was an error
77  */
79 
80 /**
81  * Get the application context that is associated with a delivery object.
82  *
83  * The application context for a delivery may be set using
84  * ::pn_delivery_set_context.
85  *
86  * @param[in] delivery the delivery whose context is to be returned.
87  * @return the application context for the delivery object
88  */
90 
91 /**
92  * Set a new application context for a delivery object.
93  *
94  * The application context for a delivery object may be retrieved using
95  * ::pn_delivery_get_context.
96  *
97  * @param[in] delivery the delivery object
98  * @param[in] context the application context
99  */
100 PN_EXTERN void pn_delivery_set_context(pn_delivery_t *delivery, void *context);
101 
102 /**
103  * Get the tag for a delivery object.
104  *
105  * @param[in] delivery a delivery object
106  * @return the delivery tag
107  */
109 
110 /**
111  * Get the parent link for a delivery object.
112  *
113  * @param[in] delivery a delivery object
114  * @return the parent link
115  */
117 
118 /**
119  * Get the local disposition for a delivery.
120  *
121  * The pointer returned by this object is valid until the delivery is
122  * settled.
123  *
124  * @param[in] delivery a delivery object
125  * @return a pointer to the local disposition
126  */
128 
129 /**
130  * Get the local disposition state for a delivery.
131  *
132  * @param[in] delivery a delivery object
133  * @return the local disposition state
134  */
136 
137 /**
138  * Get the remote disposition for a delivery.
139  *
140  * The pointer returned by this object is valid until the delivery is
141  * settled.
142  *
143  * @param[in] delivery a delivery object
144  * @return a pointer to the remote disposition
145  */
147 
148 /**
149  * Get the remote disposition state for a delivery.
150  *
151  * @param[in] delivery a delivery object
152  * @return the remote disposition state
153  */
155 
156 /**
157  * Check if a delivery is remotely settled.
158  *
159  * @param[in] delivery a delivery object
160  * @return true if the delivery is settled at the remote endpoint, false otherwise
161  */
163 
164 /**
165  * Get the amount of pending message data for a delivery.
166  *
167  * @param[in] delivery a delivery object
168  * @return the amount of pending message data in bytes
169  */
171 
172 /**
173  * Check if a delivery only has partial message data.
174  *
175  * @param[in] delivery a delivery object
176  * @return true if the delivery only contains part of a message, false otherwise
177  */
179 
180 /**
181  * Check if a delivery is writable.
182  *
183  * A delivery is considered writable if it is the current delivery on
184  * an outgoing link, and the link has positive credit.
185  *
186  * @param[in] delivery a delivery object
187  * @return true if the delivery is writable, false otherwise
188  */
190 
191 /**
192  * Check if a delivery is readable.
193  *
194  * A delivery is considered readable if it is the current delivery on
195  * an incoming link.
196  *
197  * @param[in] delivery a delivery object
198  * @return true if the delivery is readable, false otherwise
199  */
201 
202 /**
203  * Check if a delivery is updated.
204  *
205  * A delivery is considered updated whenever the peer communicates a
206  * new disposition for the delivery. Once a delivery becomes updated,
207  * it will remain so until ::pn_delivery_clear is called.
208  *
209  * @param[in] delivery a delivery object
210  * @return true if the delivery is updated, false otherwise
211  */
213 
214 /**
215  * Update the disposition of a delivery.
216  *
217  * When update is invoked the updated disposition of the delivery will
218  * be communicated to the peer.
219  *
220  * @param[in] delivery a delivery object
221  * @param[in] state the updated delivery state
222  */
223 PN_EXTERN void pn_delivery_update(pn_delivery_t *delivery, uint64_t state);
224 
225 /**
226  * Clear the updated flag for a delivery.
227  *
228  * See ::pn_delivery_updated.
229  *
230  * @param[in] delivery a delivery object
231  */
233 
234 //int pn_delivery_format(pn_delivery_t *delivery);
235 
236 /**
237  * Settle a delivery.
238  *
239  * A settled delivery can never be used again.
240  *
241  * @param[in] delivery a delivery object
242  */
244 
245 /**
246  * Utility function for printing details of a delivery.
247  *
248  * @param[in] delivery a delivery object
249  */
251 
252 /**
253  * Check if a delivery is buffered.
254  *
255  * A delivery that is buffered has not yet been written to the wire.
256  *
257  * Note that returning false does not imply that a delivery was
258  * definitely written to the wire. If false is returned, it is not
259  * known whether the delivery was actually written to the wire or not.
260  *
261  * @param[in] delivery a delivery object
262  * @return true if the delivery is buffered
263  */
265 
266 /**
267  * Extracts the first delivery on the connection that has pending
268  * operations.
269  *
270  * Retrieves the first delivery on the Connection that has pending
271  * operations. A readable delivery indicates message data is waiting
272  * to be read. A writable delivery indicates that message data may be
273  * sent. An updated delivery indicates that the delivery's disposition
274  * has changed. A delivery will never be both readable and writible,
275  * but it may be both readable and updated or both writiable and
276  * updated.
277  *
278  * @param[in] connection the connection
279  * @return the first delivery object that needs to be serviced, else
280  * NULL if none
281  */
283 
284 /**
285  * Get the next delivery on the connection that needs has pending
286  * operations.
287  *
288  * @param[in] delivery the previous delivery retrieved from
289  * either pn_work_head or pn_work_next
290  * @return the next delivery that has pending operations, else
291  * NULL if none
292  */
294 
295 /** @}
296  */
297 
298 #ifdef __cplusplus
299 }
300 #endif
301 
302 #endif /* delivery.h */