00001 #ifndef PROTON_EVENT_H 00002 #define PROTON_EVENT_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 <proton/type_compat.h> 00027 #include <stddef.h> 00028 #include <sys/types.h> 00029 00030 #ifdef __cplusplus 00031 extern "C" { 00032 #endif 00033 00034 /** 00035 * @file 00036 * 00037 * Event API for the proton Engine. 00038 * 00039 * @defgroup event Event 00040 * @ingroup engine 00041 * @{ 00042 */ 00043 00044 /** 00045 * An event provides notification of a state change within the 00046 * protocol engine's object model. 00047 * 00048 * The AMQP endpoint state modeled by the protocol engine is captured 00049 * by the following object types: @link pn_delivery_t Deliveries 00050 * @endlink, @link pn_link_t Links @endlink, @link pn_session_t 00051 * Sessions @endlink, @link pn_connection_t Connections @endlink, and 00052 * @link pn_transport_t Transports @endlink. These objects are related 00053 * as follows: 00054 * 00055 * - @link pn_delivery_t Deliveries @endlink always have a single 00056 * parent Link 00057 * - @link pn_link_t Links @endlink always have a single parent 00058 * Session 00059 * - @link pn_session_t Sessions @endlink always have a single parent 00060 * Connection 00061 * - @link pn_connection_t Connections @endlink optionally have at 00062 * most one associated Transport 00063 * - @link pn_transport_t Transports @endlink optionally have at most 00064 * one associated Connection 00065 * 00066 * Every event has a type (see ::pn_event_type_t) that identifies what 00067 * sort of state change has occurred along with a pointer to the 00068 * object whose state has changed (as well as its associated objects). 00069 * 00070 * Events are accessed by creating a @link pn_collector_t Collector 00071 * @endlink with ::pn_collector() and registering it with the @link 00072 * pn_connection_t Connection @endlink of interest through use of 00073 * ::pn_connection_collect(). Once a collector has been registered, 00074 * ::pn_collector_peek() and ::pn_collector_pop() are used to access 00075 * and process events. 00076 */ 00077 typedef struct pn_event_t pn_event_t; 00078 00079 /** 00080 * Related events are grouped into categories 00081 */ 00082 typedef enum { 00083 PN_EVENT_CATEGORY_NONE = 0, 00084 PN_EVENT_CATEGORY_PROTOCOL = 0x00010000, 00085 PN_EVENT_CATEGORY_COUNT = 2 00086 } pn_event_category_t; 00087 00088 /** 00089 * An event type. 00090 */ 00091 typedef enum { 00092 /** 00093 * Defined as a programming convenience. No event of this type will 00094 * ever be generated. 00095 */ 00096 PN_EVENT_NONE = 0, 00097 /** 00098 * The endpoint state flags for a connection have changed. Events of 00099 * this type point to the relevant connection as well as its 00100 * associated transport. 00101 */ 00102 PN_CONNECTION_REMOTE_STATE = PN_EVENT_CATEGORY_PROTOCOL+1, 00103 PN_CONNECTION_LOCAL_STATE = PN_EVENT_CATEGORY_PROTOCOL+2, 00104 /** 00105 * The endpoint state flags for a session have changed. Events of 00106 * this type point to the relevant session as well as its associated 00107 * connection and transport. 00108 */ 00109 PN_SESSION_REMOTE_STATE = PN_EVENT_CATEGORY_PROTOCOL+3, 00110 PN_SESSION_LOCAL_STATE = PN_EVENT_CATEGORY_PROTOCOL+4, 00111 /** 00112 * The endpoint state flags for a link have changed. Events of this 00113 * type point to the relevant link as well as its associated 00114 * session, connection, and transport. 00115 */ 00116 PN_LINK_REMOTE_STATE = PN_EVENT_CATEGORY_PROTOCOL+5, 00117 PN_LINK_LOCAL_STATE = PN_EVENT_CATEGORY_PROTOCOL+6, 00118 /** 00119 * The flow control state for a link has changed. Events of this 00120 * type point to the relevant link along with its associated 00121 * session, connection, and transport. 00122 */ 00123 PN_LINK_FLOW = PN_EVENT_CATEGORY_PROTOCOL+7, 00124 /** 00125 * A delivery has been created or updated. Events of this type point 00126 * to the relevant delivery as well as its associated link, session, 00127 * connection, and transport. 00128 */ 00129 PN_DELIVERY = PN_EVENT_CATEGORY_PROTOCOL+8, 00130 /** 00131 * The transport has new data to read and/or write. Events of this 00132 * type point to the relevant transport as well as its associated 00133 * connection. 00134 */ 00135 PN_TRANSPORT = PN_EVENT_CATEGORY_PROTOCOL+9 00136 } pn_event_type_t; 00137 00138 /** 00139 * Get a human readable name for an event type. 00140 * 00141 * @param[in] type an event type 00142 * @return a human readable name 00143 */ 00144 PN_EXTERN const char *pn_event_type_name(pn_event_type_t type); 00145 00146 /** 00147 * Construct a collector. 00148 * 00149 * A collector is used to register interest in events produced by one 00150 * or more ::pn_connection_t objects. Collectors are not currently 00151 * thread safe, so synchronization must be used if they are to be 00152 * shared between multiple connection objects. 00153 */ 00154 PN_EXTERN pn_collector_t *pn_collector(void); 00155 00156 /** 00157 * Free a collector. 00158 * 00159 * @param[in] collector a collector to free, or NULL 00160 */ 00161 PN_EXTERN void pn_collector_free(pn_collector_t *collector); 00162 00163 /** 00164 * Access the head event contained by a collector. 00165 * 00166 * This operation will continue to return the same event until it is 00167 * cleared by using ::pn_collector_pop. The pointer return by this 00168 * operation will be valid until ::pn_collector_pop is invoked or 00169 * ::pn_collector_free is called, whichever happens sooner. 00170 * 00171 * @param[in] collector a collector object 00172 * @return a pointer to the head event contained in the collector 00173 */ 00174 PN_EXTERN pn_event_t *pn_collector_peek(pn_collector_t *collector); 00175 00176 /** 00177 * Clear the head event on a collector. 00178 * 00179 * @param[in] collector a collector object 00180 * @return true if the event was popped, false if the collector is empty 00181 */ 00182 PN_EXTERN bool pn_collector_pop(pn_collector_t *collector); 00183 00184 /** 00185 * Get the type of an event. 00186 * 00187 * @param[in] event an event object 00188 * @return the type of the event 00189 */ 00190 PN_EXTERN pn_event_type_t pn_event_type(pn_event_t *event); 00191 00192 /** 00193 * Get the category an event belongs to. 00194 * 00195 * @param[in] event an event object 00196 * @return the category the event belongs to 00197 */ 00198 PN_EXTERN pn_event_category_t pn_event_category(pn_event_t *event); 00199 00200 /** 00201 * Get the connection associated with an event. 00202 * 00203 * @param[in] event an event object 00204 * @return the connection associated with the event (or NULL) 00205 */ 00206 PN_EXTERN pn_connection_t *pn_event_connection(pn_event_t *event); 00207 00208 /** 00209 * Get the session associated with an event. 00210 * 00211 * @param[in] event an event object 00212 * @return the session associated with the event (or NULL) 00213 */ 00214 PN_EXTERN pn_session_t *pn_event_session(pn_event_t *event); 00215 00216 /** 00217 * Get the link associated with an event. 00218 * 00219 * @param[in] event an event object 00220 * @return the link associated with the event (or NULL) 00221 */ 00222 PN_EXTERN pn_link_t *pn_event_link(pn_event_t *event); 00223 00224 /** 00225 * Get the delivery associated with an event. 00226 * 00227 * @param[in] event an event object 00228 * @return the delivery associated with the event (or NULL) 00229 */ 00230 PN_EXTERN pn_delivery_t *pn_event_delivery(pn_event_t *event); 00231 00232 /** 00233 * Get the transport associated with an event. 00234 * 00235 * @param[in] event an event object 00236 * @return the transport associated with the event (or NULL) 00237 */ 00238 PN_EXTERN pn_transport_t *pn_event_transport(pn_event_t *event); 00239 00240 #ifdef __cplusplus 00241 } 00242 #endif 00243 00244 /** @} 00245 */ 00246 00247 #endif /* event.h */