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