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
types.h
Go to the documentation of this file.
1
#ifndef PROTON_TYPES_H
2
#define PROTON_TYPES_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 <sys/types.h>
27
#include <
proton/type_compat.h
>
28
29
/**
30
* @file
31
*
32
* @defgroup types Types
33
* @{
34
*/
35
36
#ifdef __cplusplus
37
extern
"C"
{
38
#endif
39
40
/**
41
* @defgroup primitives Primitive Types
42
* @{
43
*/
44
45
typedef
int32_t
pn_sequence_t
;
46
typedef
uint32_t
pn_millis_t
;
47
typedef
uint32_t
pn_seconds_t
;
48
typedef
int64_t
pn_timestamp_t
;
49
typedef
uint32_t
pn_char_t
;
50
typedef
uint32_t
pn_decimal32_t
;
51
typedef
uint64_t
pn_decimal64_t
;
52
typedef
struct
{
53
char
bytes[16];
54
}
pn_decimal128_t
;
55
typedef
struct
{
56
char
bytes[16];
57
}
pn_uuid_t
;
58
59
typedef
struct
{
60
size_t
size
;
61
char
*
start
;
62
}
pn_bytes_t
;
63
64
PN_EXTERN
pn_bytes_t
pn_bytes
(
size_t
size,
char
*start);
65
PN_EXTERN
pn_bytes_t
pn_bytes_dup
(
size_t
size,
const
char
*start);
66
67
/** @}
68
*/
69
70
/**
71
* @defgroup abstract Abstract Types
72
* @{
73
*/
74
75
/**
76
* Holds the state flags for an AMQP endpoint.
77
*
78
* A pn_state_t is an integral value with flags that encode both the
79
* local and remote state of an AMQP Endpoint (@link pn_connection_t
80
* Connection @endlink, @link pn_session_t Session @endlink, or @link
81
* pn_link_t Link @endlink). The local portion of the state may be
82
* accessed using ::PN_LOCAL_MASK, and the remote portion may be
83
* accessed using ::PN_REMOTE_MASK. Individual bits may be accessed
84
* using ::PN_LOCAL_UNINIT, ::PN_LOCAL_ACTIVE, ::PN_LOCAL_CLOSED, and
85
* ::PN_REMOTE_UNINIT, ::PN_REMOTE_ACTIVE, ::PN_REMOTE_CLOSED.
86
*
87
* Every AMQP endpoint (@link pn_connection_t Connection @endlink,
88
* @link pn_session_t Session @endlink, or @link pn_link_t Link
89
* @endlink) starts out in an uninitialized state and then proceeds
90
* linearly to an active and then closed state. This lifecycle occurs
91
* at both endpoints involved, and so the state model for an endpoint
92
* includes not only the known local state, but also the last known
93
* state of the remote endpoint.
94
*
95
* @ingroup connection
96
*/
97
typedef
int
pn_state_t
;
98
99
/**
100
* An AMQP Connection object.
101
*
102
* A pn_connection_t object encapsulates all of the endpoint state
103
* associated with an AMQP Connection. A pn_connection_t object
104
* contains zero or more ::pn_session_t objects, which in turn contain
105
* zero or more ::pn_link_t objects. Each ::pn_link_t object contains
106
* an ordered sequence of ::pn_delivery_t objects. A link is either a
107
* @link sender Sender @endlink, or a @link receiver Receiver
108
* @endlink, but never both.
109
*
110
* @ingroup connection
111
*/
112
typedef
struct
pn_connection_t
pn_connection_t
;
113
114
/**
115
* An AMQP Session object.
116
*
117
* A pn_session_t object encapsulates all of the endpoint state
118
* associated with an AMQP Session. A pn_session_t object contains
119
* zero or more ::pn_link_t objects.
120
*
121
* @ingroup session
122
*/
123
typedef
struct
pn_session_t
pn_session_t
;
124
125
/**
126
* An AMQP Link object.
127
*
128
* A pn_link_t object encapsulates all of the endpoint state
129
* associated with an AMQP Link. A pn_link_t object contains an
130
* ordered sequence of ::pn_delivery_t objects representing in-flight
131
* deliveries. A pn_link_t may be either a @link sender Sender
132
* @endlink, or a @link receiver Receiver @endlink, but never both.
133
*
134
* A pn_link_t object maintains a pointer to the *current* delivery
135
* within the ordered sequence of deliveries contained by the link
136
* (See ::pn_link_current). The *current* delivery is the target of a
137
* number of operations associated with the link, such as sending
138
* (::pn_link_send) and receiving (::pn_link_recv) message data.
139
*
140
* @ingroup link
141
*/
142
typedef
struct
pn_link_t
pn_link_t
;
143
144
/**
145
* An AMQP Delivery object.
146
*
147
* A pn_delivery_t object encapsulates all of the endpoint state
148
* associated with an AMQP Delivery. Every delivery exists within the
149
* context of a ::pn_link_t object.
150
*
151
* The AMQP model for settlement is based on the lifecycle of a
152
* delivery at an endpoint. At each end of a link, a delivery is
153
* created, it exists for some period of time, and finally it is
154
* forgotten, aka settled. Note that because this lifecycle happens
155
* independently at both the sender and the receiver, there are
156
* actually four events of interest in the combined lifecycle of a
157
* given delivery:
158
*
159
* - created at sender
160
* - created at receiver
161
* - settled at sender
162
* - settled at receiver
163
*
164
* Because the sender and receiver are operating concurrently, these
165
* events can occur in a variety of different orders, and the order of
166
* these events impacts the types of failures that may occur when
167
* transferring a delivery. Eliminating scenarios where the receiver
168
* creates the delivery first, we have the following possible
169
* sequences of interest:
170
*
171
* Sender presettles (aka at-most-once):
172
* -------------------------------------
173
*
174
* 1. created at sender
175
* 2. settled at sender
176
* 3. created at receiver
177
* 4. settled at receiver
178
*
179
* In this configuration the sender settles (i.e. forgets about) the
180
* delivery before it even reaches the receiver, and if anything
181
* should happen to the delivery in-flight, there is no way to
182
* recover, hence the "at most once" semantics.
183
*
184
* Receiver settles first (aka at-least-once):
185
* -------------------------------------------
186
*
187
* 1. created at sender
188
* 2. created at receiver
189
* 3. settled at receiver
190
* 4. settled at sender
191
*
192
* In this configuration the receiver settles the delivery first, and
193
* the sender settles once it sees the receiver has settled. Should
194
* anything happen to the delivery in-flight, the sender can resend,
195
* however the receiver may have already forgotten the delivery and so
196
* it could interpret the resend as a new delivery, hence the "at
197
* least once" semantics.
198
*
199
* Receiver settles second (aka exactly-once):
200
* -------------------------------------------
201
*
202
* 1. created at sender
203
* 2. created at receiver
204
* 3. settled at sender
205
* 4. settled at receiver
206
*
207
* In this configuration the receiver settles only once it has seen
208
* that the sender has settled. This provides the sender the option to
209
* retransmit, and the receiver has the option to recognize (and
210
* discard) duplicates, allowing for exactly once semantics.
211
*
212
* Note that in the last scenario the sender needs some way to know
213
* when it is safe to settle. This is where delivery state comes in.
214
* In addition to these lifecycle related events surrounding
215
* deliveries there is also the notion of a delivery state that can
216
* change over the lifetime of a delivery, e.g. it might start out as
217
* nothing, transition to ::PN_RECEIVED and then transition to
218
* ::PN_ACCEPTED. In the first two scenarios the delivery state isn't
219
* required, however in final scenario the sender would typically
220
* trigger settlement based on seeing the delivery state transition to
221
* a terminal state like ::PN_ACCEPTED or ::PN_REJECTED.
222
*
223
* In practice settlement is controlled by application policy, so
224
* there may well be more options here, e.g. a sender might not settle
225
* strictly based on what has happened at the receiver, it might also
226
* choose to impose some time limit and settle after that period has
227
* expired, or it could simply have a sliding window of the last N
228
* deliveries and settle the oldest whenever a new one comes along.
229
*
230
* @ingroup delivery
231
*/
232
typedef
struct
pn_delivery_t
pn_delivery_t
;
233
234
/**
235
* An event collector.
236
*
237
* A pn_collector_t may be used to register interest in being notified
238
* of high level events that can occur to the various objects
239
* representing AMQP endpoint state. See ::pn_event_t for more
240
* details.
241
*
242
* @ingroup event
243
*/
244
typedef
struct
pn_collector_t
pn_collector_t
;
245
246
/**
247
* An AMQP Transport object.
248
*
249
* A pn_transport_t encapsulates the transport related state of all
250
* AMQP endpoint objects associated with a physical network connection
251
* at a given point in time.
252
*
253
* @ingroup transport
254
*/
255
256
typedef
struct
pn_transport_t
pn_transport_t
;
257
258
/** @}
259
*/
260
#ifdef __cplusplus
261
}
262
#endif
263
264
/** @}
265
*/
266
267
#endif
/* types.h */
Generated on Mon Jun 2 2014 22:59:05 for proton by
1.8.1.2