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 <sys/types.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 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 char *start; 00063 } pn_bytes_t; 00064 00065 PN_EXTERN pn_bytes_t pn_bytes(size_t size, char *start); 00066 PN_EXTERN pn_bytes_t pn_bytes_dup(size_t size, const char *start); 00067 00068 /** @} 00069 */ 00070 00071 /** 00072 * @defgroup abstract Abstract Types 00073 * @{ 00074 */ 00075 00076 /** 00077 * Holds the state flags for an AMQP endpoint. 00078 * 00079 * A pn_state_t is an integral value with flags that encode both the 00080 * local and remote state of an AMQP Endpoint (@link pn_connection_t 00081 * Connection @endlink, @link pn_session_t Session @endlink, or @link 00082 * pn_link_t Link @endlink). The local portion of the state may be 00083 * accessed using ::PN_LOCAL_MASK, and the remote portion may be 00084 * accessed using ::PN_REMOTE_MASK. Individual bits may be accessed 00085 * using ::PN_LOCAL_UNINIT, ::PN_LOCAL_ACTIVE, ::PN_LOCAL_CLOSED, and 00086 * ::PN_REMOTE_UNINIT, ::PN_REMOTE_ACTIVE, ::PN_REMOTE_CLOSED. 00087 * 00088 * Every AMQP endpoint (@link pn_connection_t Connection @endlink, 00089 * @link pn_session_t Session @endlink, or @link pn_link_t Link 00090 * @endlink) starts out in an uninitialized state and then proceeds 00091 * linearly to an active and then closed state. This lifecycle occurs 00092 * at both endpoints involved, and so the state model for an endpoint 00093 * includes not only the known local state, but also the last known 00094 * state of the remote endpoint. 00095 * 00096 * @ingroup connection 00097 */ 00098 typedef int pn_state_t; 00099 00100 /** 00101 * An AMQP Connection object. 00102 * 00103 * A pn_connection_t object encapsulates all of the endpoint state 00104 * associated with an AMQP Connection. A pn_connection_t object 00105 * contains zero or more ::pn_session_t objects, which in turn contain 00106 * zero or more ::pn_link_t objects. Each ::pn_link_t object contains 00107 * an ordered sequence of ::pn_delivery_t objects. A link is either a 00108 * @link sender Sender @endlink, or a @link receiver Receiver 00109 * @endlink, but never both. 00110 * 00111 * @ingroup connection 00112 */ 00113 typedef struct pn_connection_t pn_connection_t; 00114 00115 /** 00116 * An AMQP Session object. 00117 * 00118 * A pn_session_t object encapsulates all of the endpoint state 00119 * associated with an AMQP Session. A pn_session_t object contains 00120 * zero or more ::pn_link_t objects. 00121 * 00122 * @ingroup session 00123 */ 00124 typedef struct pn_session_t pn_session_t; 00125 00126 /** 00127 * An AMQP Link object. 00128 * 00129 * A pn_link_t object encapsulates all of the endpoint state 00130 * associated with an AMQP Link. A pn_link_t object contains an 00131 * ordered sequence of ::pn_delivery_t objects representing in-flight 00132 * deliveries. A pn_link_t may be either a @link sender Sender 00133 * @endlink, or a @link receiver Receiver @endlink, but never both. 00134 * 00135 * A pn_link_t object maintains a pointer to the *current* delivery 00136 * within the ordered sequence of deliveries contained by the link 00137 * (See ::pn_link_current). The *current* delivery is the target of a 00138 * number of operations associated with the link, such as sending 00139 * (::pn_link_send) and receiving (::pn_link_recv) message data. 00140 * 00141 * @ingroup link 00142 */ 00143 typedef struct pn_link_t pn_link_t; 00144 00145 /** 00146 * An AMQP Delivery object. 00147 * 00148 * A pn_delivery_t object encapsulates all of the endpoint state 00149 * associated with an AMQP Delivery. Every delivery exists within the 00150 * context of a ::pn_link_t object. 00151 * 00152 * The AMQP model for settlement is based on the lifecycle of a 00153 * delivery at an endpoint. At each end of a link, a delivery is 00154 * created, it exists for some period of time, and finally it is 00155 * forgotten, aka settled. Note that because this lifecycle happens 00156 * independently at both the sender and the receiver, there are 00157 * actually four events of interest in the combined lifecycle of a 00158 * given delivery: 00159 * 00160 * - created at sender 00161 * - created at receiver 00162 * - settled at sender 00163 * - settled at receiver 00164 * 00165 * Because the sender and receiver are operating concurrently, these 00166 * events can occur in a variety of different orders, and the order of 00167 * these events impacts the types of failures that may occur when 00168 * transferring a delivery. Eliminating scenarios where the receiver 00169 * creates the delivery first, we have the following possible 00170 * sequences of interest: 00171 * 00172 * Sender presettles (aka at-most-once): 00173 * ------------------------------------- 00174 * 00175 * 1. created at sender 00176 * 2. settled at sender 00177 * 3. created at receiver 00178 * 4. settled at receiver 00179 * 00180 * In this configuration the sender settles (i.e. forgets about) the 00181 * delivery before it even reaches the receiver, and if anything 00182 * should happen to the delivery in-flight, there is no way to 00183 * recover, hence the "at most once" semantics. 00184 * 00185 * Receiver settles first (aka at-least-once): 00186 * ------------------------------------------- 00187 * 00188 * 1. created at sender 00189 * 2. created at receiver 00190 * 3. settled at receiver 00191 * 4. settled at sender 00192 * 00193 * In this configuration the receiver settles the delivery first, and 00194 * the sender settles once it sees the receiver has settled. Should 00195 * anything happen to the delivery in-flight, the sender can resend, 00196 * however the receiver may have already forgotten the delivery and so 00197 * it could interpret the resend as a new delivery, hence the "at 00198 * least once" semantics. 00199 * 00200 * Receiver settles second (aka exactly-once): 00201 * ------------------------------------------- 00202 * 00203 * 1. created at sender 00204 * 2. created at receiver 00205 * 3. settled at sender 00206 * 4. settled at receiver 00207 * 00208 * In this configuration the receiver settles only once it has seen 00209 * that the sender has settled. This provides the sender the option to 00210 * retransmit, and the receiver has the option to recognize (and 00211 * discard) duplicates, allowing for exactly once semantics. 00212 * 00213 * Note that in the last scenario the sender needs some way to know 00214 * when it is safe to settle. This is where delivery state comes in. 00215 * In addition to these lifecycle related events surrounding 00216 * deliveries there is also the notion of a delivery state that can 00217 * change over the lifetime of a delivery, e.g. it might start out as 00218 * nothing, transition to ::PN_RECEIVED and then transition to 00219 * ::PN_ACCEPTED. In the first two scenarios the delivery state isn't 00220 * required, however in final scenario the sender would typically 00221 * trigger settlement based on seeing the delivery state transition to 00222 * a terminal state like ::PN_ACCEPTED or ::PN_REJECTED. 00223 * 00224 * In practice settlement is controlled by application policy, so 00225 * there may well be more options here, e.g. a sender might not settle 00226 * strictly based on what has happened at the receiver, it might also 00227 * choose to impose some time limit and settle after that period has 00228 * expired, or it could simply have a sliding window of the last N 00229 * deliveries and settle the oldest whenever a new one comes along. 00230 * 00231 * @ingroup delivery 00232 */ 00233 typedef struct pn_delivery_t pn_delivery_t; 00234 00235 /** 00236 * An event collector. 00237 * 00238 * A pn_collector_t may be used to register interest in being notified 00239 * of high level events that can occur to the various objects 00240 * representing AMQP endpoint state. See ::pn_event_t for more 00241 * details. 00242 * 00243 * @ingroup event 00244 */ 00245 typedef struct pn_collector_t pn_collector_t; 00246 00247 /** 00248 * An AMQP Transport object. 00249 * 00250 * A pn_transport_t encapsulates the transport related state of all 00251 * AMQP endpoint objects associated with a physical network connection 00252 * at a given point in time. 00253 * 00254 * @ingroup transport 00255 */ 00256 00257 typedef struct pn_transport_t pn_transport_t; 00258 00259 /** @} 00260 */ 00261 #ifdef __cplusplus 00262 } 00263 #endif 00264 00265 /** @} 00266 */ 00267 00268 #endif /* types.h */