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
proton-c
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 Mon Jun 2 2014 22:59:05 for proton by
1.8.1.2