proton
0
Main Page
Related Pages
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Macros
Groups
Pages
include
proton
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
;
51
}
pn_delivery_tag_t
;
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
*/
78
PN_EXTERN
pn_delivery_t
*
pn_delivery
(
pn_link_t
*link,
pn_delivery_tag_t
tag);
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
*/
89
PN_EXTERN
void
*
pn_delivery_get_context
(
pn_delivery_t
*delivery);
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
*/
108
PN_EXTERN
pn_delivery_tag_t
pn_delivery_tag
(
pn_delivery_t
*delivery);
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
*/
116
PN_EXTERN
pn_link_t
*
pn_delivery_link
(
pn_delivery_t
*delivery);
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
*/
127
PN_EXTERN
pn_disposition_t
*
pn_delivery_local
(
pn_delivery_t
*delivery);
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
*/
135
PN_EXTERN
uint64_t
pn_delivery_local_state
(
pn_delivery_t
*delivery);
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
*/
146
PN_EXTERN
pn_disposition_t
*
pn_delivery_remote
(
pn_delivery_t
*delivery);
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
*/
154
PN_EXTERN
uint64_t
pn_delivery_remote_state
(
pn_delivery_t
*delivery);
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
*/
162
PN_EXTERN
bool
pn_delivery_settled
(
pn_delivery_t
*delivery);
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
*/
170
PN_EXTERN
size_t
pn_delivery_pending
(
pn_delivery_t
*delivery);
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
*/
178
PN_EXTERN
bool
pn_delivery_partial
(
pn_delivery_t
*delivery);
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
*/
189
PN_EXTERN
bool
pn_delivery_writable
(
pn_delivery_t
*delivery);
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
*/
200
PN_EXTERN
bool
pn_delivery_readable
(
pn_delivery_t
*delivery);
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
*/
212
PN_EXTERN
bool
pn_delivery_updated
(
pn_delivery_t
*delivery);
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
*/
232
PN_EXTERN
void
pn_delivery_clear
(
pn_delivery_t
*delivery);
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
*/
243
PN_EXTERN
void
pn_delivery_settle
(
pn_delivery_t
*delivery);
244
245
/**
246
* Utility function for printing details of a delivery.
247
*
248
* @param[in] delivery a delivery object
249
*/
250
PN_EXTERN
void
pn_delivery_dump
(
pn_delivery_t
*delivery);
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
*/
264
PN_EXTERN
bool
pn_delivery_buffered
(
pn_delivery_t
*delivery);
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
*/
282
PN_EXTERN
pn_delivery_t
*
pn_work_head
(
pn_connection_t
*connection);
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
*/
293
PN_EXTERN
pn_delivery_t
*
pn_work_next
(
pn_delivery_t
*delivery);
294
295
/** @}
296
*/
297
298
#ifdef __cplusplus
299
}
300
#endif
301
302
#endif
/* delivery.h */
Generated on Thu Jul 10 2014 02:10:59 for proton by
1.8.3.1