00001 #ifndef PROTON_TYPES_H 00002 #define PROTON_TYPES_H 1 00003 00004 /* 00005 * 00006 * Licensed to the Apache Software Foundation (ASF) under one 00007 * or more contributor license agreements. See the NOTICE file 00008 * distributed with this work for additional information 00009 * regarding copyright ownership. The ASF licenses this file 00010 * to you under the Apache License, Version 2.0 (the 00011 * "License"); you may not use this file except in compliance 00012 * with the License. You may obtain a copy of the License at 00013 * 00014 * http://www.apache.org/licenses/LICENSE-2.0 00015 * 00016 * Unless required by applicable law or agreed to in writing, 00017 * software distributed under the License is distributed on an 00018 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 00019 * KIND, either express or implied. See the License for the 00020 * specific language governing permissions and limitations 00021 * under the License. 00022 * 00023 */ 00024 00025 #include <proton/import_export.h> 00026 #include <stddef.h> 00027 #include <proton/type_compat.h> 00028 00029 /** 00030 * @file 00031 * 00032 * @defgroup types Types 00033 * @{ 00034 */ 00035 00036 #ifdef __cplusplus 00037 extern "C" { 00038 #endif 00039 00040 /** 00041 * @defgroup primitives Primitive Types 00042 * @{ 00043 */ 00044 00045 typedef int32_t pn_sequence_t; 00046 typedef uint32_t pn_millis_t; 00047 #define PN_MILLIS_MAX (~0U) 00048 typedef uint32_t pn_seconds_t; 00049 typedef int64_t pn_timestamp_t; 00050 typedef uint32_t pn_char_t; 00051 typedef uint32_t pn_decimal32_t; 00052 typedef uint64_t pn_decimal64_t; 00053 typedef struct { 00054 char bytes[16]; 00055 } pn_decimal128_t; 00056 typedef struct { 00057 char bytes[16]; 00058 } pn_uuid_t; 00059 00060 typedef struct { 00061 size_t size; 00062 const char *start; 00063 } pn_bytes_t; 00064 00065 PN_EXTERN pn_bytes_t pn_bytes(size_t size, const char *start); 00066 00067 /** @} 00068 */ 00069 00070 /** 00071 * @defgroup abstract Abstract Types 00072 * @{ 00073 */ 00074 00075 /** 00076 * Holds the state flags for an AMQP endpoint. 00077 * 00078 * A pn_state_t is an integral value with flags that encode both the 00079 * local and remote state of an AMQP Endpoint (@link pn_connection_t 00080 * Connection @endlink, @link pn_session_t Session @endlink, or @link 00081 * pn_link_t Link @endlink). The local portion of the state may be 00082 * accessed using ::PN_LOCAL_MASK, and the remote portion may be 00083 * accessed using ::PN_REMOTE_MASK. Individual bits may be accessed 00084 * using ::PN_LOCAL_UNINIT, ::PN_LOCAL_ACTIVE, ::PN_LOCAL_CLOSED, and 00085 * ::PN_REMOTE_UNINIT, ::PN_REMOTE_ACTIVE, ::PN_REMOTE_CLOSED. 00086 * 00087 * Every AMQP endpoint (@link pn_connection_t Connection @endlink, 00088 * @link pn_session_t Session @endlink, or @link pn_link_t Link 00089 * @endlink) starts out in an uninitialized state and then proceeds 00090 * linearly to an active and then closed state. This lifecycle occurs 00091 * at both endpoints involved, and so the state model for an endpoint 00092 * includes not only the known local state, but also the last known 00093 * state of the remote endpoint. 00094 * 00095 * @ingroup connection 00096 */ 00097 typedef int pn_state_t; 00098 00099 /** 00100 * An AMQP Connection object. 00101 * 00102 * A pn_connection_t object encapsulates all of the endpoint state 00103 * associated with an AMQP Connection. A pn_connection_t object 00104 * contains zero or more ::pn_session_t objects, which in turn contain 00105 * zero or more ::pn_link_t objects. Each ::pn_link_t object contains 00106 * an ordered sequence of ::pn_delivery_t objects. A link is either a 00107 * @link sender Sender @endlink, or a @link receiver Receiver 00108 * @endlink, but never both. 00109 * 00110 * @ingroup connection 00111 */ 00112 typedef struct pn_connection_t pn_connection_t; 00113 00114 /** 00115 * An AMQP Session object. 00116 * 00117 * A pn_session_t object encapsulates all of the endpoint state 00118 * associated with an AMQP Session. A pn_session_t object contains 00119 * zero or more ::pn_link_t objects. 00120 * 00121 * @ingroup session 00122 */ 00123 typedef struct pn_session_t pn_session_t; 00124 00125 /** 00126 * An AMQP Link object. 00127 * 00128 * A pn_link_t object encapsulates all of the endpoint state 00129 * associated with an AMQP Link. A pn_link_t object contains an 00130 * ordered sequence of ::pn_delivery_t objects representing in-flight 00131 * deliveries. A pn_link_t may be either a @link sender Sender 00132 * @endlink, or a @link receiver Receiver @endlink, but never both. 00133 * 00134 * A pn_link_t object maintains a pointer to the *current* delivery 00135 * within the ordered sequence of deliveries contained by the link 00136 * (See ::pn_link_current). The *current* delivery is the target of a 00137 * number of operations associated with the link, such as sending 00138 * (::pn_link_send) and receiving (::pn_link_recv) message data. 00139 * 00140 * @ingroup link 00141 */ 00142 typedef struct pn_link_t pn_link_t; 00143 00144 /** 00145 * An AMQP Delivery object. 00146 * 00147 * A pn_delivery_t object encapsulates all of the endpoint state 00148 * associated with an AMQP Delivery. Every delivery exists within the 00149 * context of a ::pn_link_t object. 00150 * 00151 * The AMQP model for settlement is based on the lifecycle of a 00152 * delivery at an endpoint. At each end of a link, a delivery is 00153 * created, it exists for some period of time, and finally it is 00154 * forgotten, aka settled. Note that because this lifecycle happens 00155 * independently at both the sender and the receiver, there are 00156 * actually four events of interest in the combined lifecycle of a 00157 * given delivery: 00158 * 00159 * - created at sender 00160 * - created at receiver 00161 * - settled at sender 00162 * - settled at receiver 00163 * 00164 * Because the sender and receiver are operating concurrently, these 00165 * events can occur in a variety of different orders, and the order of 00166 * these events impacts the types of failures that may occur when 00167 * transferring a delivery. Eliminating scenarios where the receiver 00168 * creates the delivery first, we have the following possible 00169 * sequences of interest: 00170 * 00171 * Sender presettles (aka at-most-once): 00172 * ------------------------------------- 00173 * 00174 * 1. created at sender 00175 * 2. settled at sender 00176 * 3. created at receiver 00177 * 4. settled at receiver 00178 * 00179 * In this configuration the sender settles (i.e. forgets about) the 00180 * delivery before it even reaches the receiver, and if anything 00181 * should happen to the delivery in-flight, there is no way to 00182 * recover, hence the "at most once" semantics. 00183 * 00184 * Receiver settles first (aka at-least-once): 00185 * ------------------------------------------- 00186 * 00187 * 1. created at sender 00188 * 2. created at receiver 00189 * 3. settled at receiver 00190 * 4. settled at sender 00191 * 00192 * In this configuration the receiver settles the delivery first, and 00193 * the sender settles once it sees the receiver has settled. Should 00194 * anything happen to the delivery in-flight, the sender can resend, 00195 * however the receiver may have already forgotten the delivery and so 00196 * it could interpret the resend as a new delivery, hence the "at 00197 * least once" semantics. 00198 * 00199 * Receiver settles second (aka exactly-once): 00200 * ------------------------------------------- 00201 * 00202 * 1. created at sender 00203 * 2. created at receiver 00204 * 3. settled at sender 00205 * 4. settled at receiver 00206 * 00207 * In this configuration the receiver settles only once it has seen 00208 * that the sender has settled. This provides the sender the option to 00209 * retransmit, and the receiver has the option to recognize (and 00210 * discard) duplicates, allowing for exactly once semantics. 00211 * 00212 * Note that in the last scenario the sender needs some way to know 00213 * when it is safe to settle. This is where delivery state comes in. 00214 * In addition to these lifecycle related events surrounding 00215 * deliveries there is also the notion of a delivery state that can 00216 * change over the lifetime of a delivery, e.g. it might start out as 00217 * nothing, transition to ::PN_RECEIVED and then transition to 00218 * ::PN_ACCEPTED. In the first two scenarios the delivery state isn't 00219 * required, however in final scenario the sender would typically 00220 * trigger settlement based on seeing the delivery state transition to 00221 * a terminal state like ::PN_ACCEPTED or ::PN_REJECTED. 00222 * 00223 * In practice settlement is controlled by application policy, so 00224 * there may well be more options here, e.g. a sender might not settle 00225 * strictly based on what has happened at the receiver, it might also 00226 * choose to impose some time limit and settle after that period has 00227 * expired, or it could simply have a sliding window of the last N 00228 * deliveries and settle the oldest whenever a new one comes along. 00229 * 00230 * @ingroup delivery 00231 */ 00232 typedef struct pn_delivery_t pn_delivery_t; 00233 00234 /** 00235 * An event collector. 00236 * 00237 * A pn_collector_t may be used to register interest in being notified 00238 * of high level events that can occur to the various objects 00239 * representing AMQP endpoint state. See ::pn_event_t for more 00240 * details. 00241 * 00242 * @ingroup event 00243 */ 00244 typedef struct pn_collector_t pn_collector_t; 00245 00246 /** 00247 * An AMQP Transport object. 00248 * 00249 * A pn_transport_t encapsulates the transport related state of all 00250 * AMQP endpoint objects associated with a physical network connection 00251 * at a given point in time. 00252 * 00253 * @ingroup transport 00254 */ 00255 00256 typedef struct pn_transport_t pn_transport_t; 00257 00258 /** @} 00259 */ 00260 #ifdef __cplusplus 00261 } 00262 #endif 00263 00264 /** @} 00265 */ 00266 00267 #endif /* types.h */