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 <proton/object.h> 00028 #include <stddef.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 * An event type. 00081 */ 00082 typedef enum { 00083 /** 00084 * Defined as a programming convenience. No event of this type will 00085 * ever be generated. 00086 */ 00087 PN_EVENT_NONE = 0, 00088 00089 /** 00090 * A reactor has been started. Events of this type point to the reactor. 00091 */ 00092 PN_REACTOR_INIT, 00093 00094 /** 00095 * A reactor has no more events to process. Events of this type 00096 * point to the reactor. 00097 */ 00098 PN_REACTOR_QUIESCED, 00099 00100 /** 00101 * A reactor has been stopped. Events of this type point to the reactor. 00102 */ 00103 PN_REACTOR_FINAL, 00104 00105 /** 00106 * A timer event has occurred. 00107 */ 00108 PN_TIMER_TASK, 00109 00110 /** 00111 * The connection has been created. This is the first event that 00112 * will ever be issued for a connection. Events of this type point 00113 * to the relevant connection. 00114 */ 00115 PN_CONNECTION_INIT, 00116 00117 /** 00118 * The connection has been bound to a transport. This event is 00119 * issued when the ::pn_transport_bind() operation is invoked. 00120 */ 00121 PN_CONNECTION_BOUND, 00122 00123 /** 00124 * The connection has been unbound from its transport. This event is 00125 * issued when the ::pn_transport_unbind() operation is invoked. 00126 */ 00127 PN_CONNECTION_UNBOUND, 00128 00129 /** 00130 * The local connection endpoint has been closed. Events of this 00131 * type point to the relevant connection. 00132 */ 00133 PN_CONNECTION_LOCAL_OPEN, 00134 00135 /** 00136 * The remote endpoint has opened the connection. Events of this 00137 * type point to the relevant connection. 00138 */ 00139 PN_CONNECTION_REMOTE_OPEN, 00140 00141 /** 00142 * The local connection endpoint has been closed. Events of this 00143 * type point to the relevant connection. 00144 */ 00145 PN_CONNECTION_LOCAL_CLOSE, 00146 00147 /** 00148 * The remote endpoint has closed the connection. Events of this 00149 * type point to the relevant connection. 00150 */ 00151 PN_CONNECTION_REMOTE_CLOSE, 00152 00153 /** 00154 * The connection has been freed and any outstanding processing has 00155 * been completed. This is the final event that will ever be issued 00156 * for a connection. 00157 */ 00158 PN_CONNECTION_FINAL, 00159 00160 /** 00161 * The session has been created. This is the first event that will 00162 * ever be issued for a session. 00163 */ 00164 PN_SESSION_INIT, 00165 00166 /** 00167 * The local session endpoint has been opened. Events of this type 00168 * point ot the relevant session. 00169 */ 00170 PN_SESSION_LOCAL_OPEN, 00171 00172 /** 00173 * The remote endpoint has opened the session. Events of this type 00174 * point to the relevant session. 00175 */ 00176 PN_SESSION_REMOTE_OPEN, 00177 00178 /** 00179 * The local session endpoint has been closed. Events of this type 00180 * point ot the relevant session. 00181 */ 00182 PN_SESSION_LOCAL_CLOSE, 00183 00184 /** 00185 * The remote endpoint has closed the session. Events of this type 00186 * point to the relevant session. 00187 */ 00188 PN_SESSION_REMOTE_CLOSE, 00189 00190 /** 00191 * The session has been freed and any outstanding processing has 00192 * been completed. This is the final event that will ever be issued 00193 * for a session. 00194 */ 00195 PN_SESSION_FINAL, 00196 00197 /** 00198 * The link has been created. This is the first event that will ever 00199 * be issued for a link. 00200 */ 00201 PN_LINK_INIT, 00202 00203 /** 00204 * The local link endpoint has been opened. Events of this type 00205 * point ot the relevant link. 00206 */ 00207 PN_LINK_LOCAL_OPEN, 00208 00209 /** 00210 * The remote endpoint has opened the link. Events of this type 00211 * point to the relevant link. 00212 */ 00213 PN_LINK_REMOTE_OPEN, 00214 00215 /** 00216 * The local link endpoint has been closed. Events of this type 00217 * point ot the relevant link. 00218 */ 00219 PN_LINK_LOCAL_CLOSE, 00220 00221 /** 00222 * The remote endpoint has closed the link. Events of this type 00223 * point to the relevant link. 00224 */ 00225 PN_LINK_REMOTE_CLOSE, 00226 00227 /** 00228 * The local link endpoint has been detached. Events of this type 00229 * point to the relevant link. 00230 */ 00231 PN_LINK_LOCAL_DETACH, 00232 00233 /** 00234 * The remote endpoint has detached the link. Events of this type 00235 * point to the relevant link. 00236 */ 00237 PN_LINK_REMOTE_DETACH, 00238 00239 /** 00240 * The flow control state for a link has changed. Events of this 00241 * type point to the relevant link. 00242 */ 00243 PN_LINK_FLOW, 00244 00245 /** 00246 * The link has been freed and any outstanding processing has been 00247 * completed. This is the final event that will ever be issued for a 00248 * link. Events of this type point to the relevant link. 00249 */ 00250 PN_LINK_FINAL, 00251 00252 /** 00253 * A delivery has been created or updated. Events of this type point 00254 * to the relevant delivery. 00255 */ 00256 PN_DELIVERY, 00257 00258 /** 00259 * The transport has new data to read and/or write. Events of this 00260 * type point to the relevant transport. 00261 */ 00262 PN_TRANSPORT, 00263 00264 /** 00265 * The transport has authenticated, if this is received by a server 00266 * the associated transport has authenticated an incoming connection 00267 * and pn_transport_get_user() can be used to obtain the authenticated 00268 * user. 00269 */ 00270 PN_TRANSPORT_AUTHENTICATED, 00271 00272 /** 00273 * Indicates that a transport error has occurred. Use 00274 * ::pn_transport_condition() to access the details of the error 00275 * from the associated transport. 00276 */ 00277 PN_TRANSPORT_ERROR, 00278 00279 /** 00280 * Indicates that the head of the transport has been closed. This 00281 * means the transport will never produce more bytes for output to 00282 * the network. Events of this type point to the relevant transport. 00283 */ 00284 PN_TRANSPORT_HEAD_CLOSED, 00285 00286 /** 00287 * Indicates that the tail of the transport has been closed. This 00288 * means the transport will never be able to process more bytes from 00289 * the network. Events of this type point to the relevant transport. 00290 */ 00291 PN_TRANSPORT_TAIL_CLOSED, 00292 00293 /** 00294 * Indicates that the both the head and tail of the transport are 00295 * closed. Events of this type point to the relevant transport. 00296 */ 00297 PN_TRANSPORT_CLOSED, 00298 00299 PN_SELECTABLE_INIT, 00300 PN_SELECTABLE_UPDATED, 00301 PN_SELECTABLE_READABLE, 00302 PN_SELECTABLE_WRITABLE, 00303 PN_SELECTABLE_ERROR, 00304 PN_SELECTABLE_EXPIRED, 00305 PN_SELECTABLE_FINAL 00306 00307 } pn_event_type_t; 00308 00309 /** 00310 * Get a human readable name for an event type. 00311 * 00312 * @param[in] type an event type 00313 * @return a human readable name 00314 */ 00315 PN_EXTERN const char *pn_event_type_name(pn_event_type_t type); 00316 00317 /** 00318 * Construct a collector. 00319 * 00320 * A collector is used to register interest in events produced by one 00321 * or more ::pn_connection_t objects. Collectors are not currently 00322 * thread safe, so synchronization must be used if they are to be 00323 * shared between multiple connection objects. 00324 */ 00325 PN_EXTERN pn_collector_t *pn_collector(void); 00326 00327 /** 00328 * Free a collector. 00329 * 00330 * @param[in] collector a collector to free, or NULL 00331 */ 00332 PN_EXTERN void pn_collector_free(pn_collector_t *collector); 00333 00334 /** 00335 * Release a collector. Once in a released state a collector will 00336 * drain any internally queued events (thereby releasing any pointers 00337 * they may hold), shrink it's memory footprint to a minimum, and 00338 * discard any newly created events. 00339 * 00340 * @param[in] collector a collector object 00341 */ 00342 PN_EXTERN void pn_collector_release(pn_collector_t *collector); 00343 00344 /** 00345 * Place a new event on a collector. 00346 * 00347 * This operation will create a new event of the given type and 00348 * context and return a pointer to the newly created event. In some 00349 * cases an event of the given type and context can be elided. When 00350 * this happens, this operation will return a NULL pointer. 00351 * 00352 * @param[in] collector a collector object 00353 * @param[in] clazz class of the context 00354 * @param[in] context the event context 00355 * @param[in] type the event type 00356 * 00357 * @return a pointer to the newly created event or NULL if the event 00358 * was elided 00359 */ 00360 00361 PN_EXTERN pn_event_t *pn_collector_put(pn_collector_t *collector, 00362 const pn_class_t *clazz, void *context, 00363 pn_event_type_t type); 00364 00365 /** 00366 * Access the head event contained by a collector. 00367 * 00368 * This operation will continue to return the same event until it is 00369 * cleared by using ::pn_collector_pop. The pointer return by this 00370 * operation will be valid until ::pn_collector_pop is invoked or 00371 * ::pn_collector_free is called, whichever happens sooner. 00372 * 00373 * @param[in] collector a collector object 00374 * @return a pointer to the head event contained in the collector 00375 */ 00376 PN_EXTERN pn_event_t *pn_collector_peek(pn_collector_t *collector); 00377 00378 /** 00379 * Clear the head event on a collector. 00380 * 00381 * @param[in] collector a collector object 00382 * @return true if the event was popped, false if the collector is empty 00383 */ 00384 PN_EXTERN bool pn_collector_pop(pn_collector_t *collector); 00385 00386 /** 00387 * Check if there are more events after the current event. If this 00388 * returns true, then pn_collector_peek() will return an event even 00389 * after pn_collector_pop() is called. 00390 * 00391 * @param[in] collector a collector object 00392 * @return true if the collector has more than the current event 00393 */ 00394 PN_EXTERN bool pn_collector_more(pn_collector_t *collector); 00395 00396 /** 00397 * Get the type of an event. 00398 * 00399 * @param[in] event an event object 00400 * @return the type of the event 00401 */ 00402 PN_EXTERN pn_event_type_t pn_event_type(pn_event_t *event); 00403 00404 /** 00405 * Get the class associated with the event context. 00406 * 00407 * @param[in] event an event object 00408 * @return the class associated with the event context 00409 */ 00410 PN_EXTERN const pn_class_t *pn_event_class(pn_event_t *event); 00411 00412 /** 00413 * Get the context associated with an event. 00414 */ 00415 PN_EXTERN void *pn_event_context(pn_event_t *event); 00416 00417 /** 00418 * Get the root handler the current event was dispatched to. 00419 */ 00420 PN_EXTERN pn_handler_t *pn_event_root(pn_event_t *event); 00421 00422 /** 00423 * Get the connection associated with an event. 00424 * 00425 * @param[in] event an event object 00426 * @return the connection associated with the event (or NULL) 00427 */ 00428 PN_EXTERN pn_connection_t *pn_event_connection(pn_event_t *event); 00429 00430 /** 00431 * Get the session associated with an event. 00432 * 00433 * @param[in] event an event object 00434 * @return the session associated with the event (or NULL) 00435 */ 00436 PN_EXTERN pn_session_t *pn_event_session(pn_event_t *event); 00437 00438 /** 00439 * Get the link associated with an event. 00440 * 00441 * @param[in] event an event object 00442 * @return the link associated with the event (or NULL) 00443 */ 00444 PN_EXTERN pn_link_t *pn_event_link(pn_event_t *event); 00445 00446 /** 00447 * Get the delivery associated with an event. 00448 * 00449 * @param[in] event an event object 00450 * @return the delivery associated with the event (or NULL) 00451 */ 00452 PN_EXTERN pn_delivery_t *pn_event_delivery(pn_event_t *event); 00453 00454 /** 00455 * Get the transport associated with an event. 00456 * 00457 * @param[in] event an event object 00458 * @return the transport associated with the event (or NULL) 00459 */ 00460 PN_EXTERN pn_transport_t *pn_event_transport(pn_event_t *event); 00461 00462 /** 00463 * Get any attachments associated with an event. 00464 * 00465 * @param[in] event an event object 00466 * @return the record holding the attachments 00467 */ 00468 PN_EXTERN pn_record_t *pn_event_attachments(pn_event_t *event); 00469 00470 #ifdef __cplusplus 00471 } 00472 #endif 00473 00474 /** @} 00475 */ 00476 00477 #endif /* event.h */