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  * 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];
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  */
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 */