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