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
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 Thu Jul 10 2014 02:10:59 for proton by
1.8.3.1