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] type the event type 00354 * @param[in] context the event context 00355 * 00356 * @return a pointer to the newly created event or NULL if the event 00357 * was elided 00358 */ 00359 00360 PN_EXTERN pn_event_t *pn_collector_put(pn_collector_t *collector, 00361 const pn_class_t *clazz, void *context, 00362 pn_event_type_t type); 00363 00364 /** 00365 * Access the head event contained by a collector. 00366 * 00367 * This operation will continue to return the same event until it is 00368 * cleared by using ::pn_collector_pop. The pointer return by this 00369 * operation will be valid until ::pn_collector_pop is invoked or 00370 * ::pn_collector_free is called, whichever happens sooner. 00371 * 00372 * @param[in] collector a collector object 00373 * @return a pointer to the head event contained in the collector 00374 */ 00375 PN_EXTERN pn_event_t *pn_collector_peek(pn_collector_t *collector); 00376 00377 /** 00378 * Clear the head event on a collector. 00379 * 00380 * @param[in] collector a collector object 00381 * @return true if the event was popped, false if the collector is empty 00382 */ 00383 PN_EXTERN bool pn_collector_pop(pn_collector_t *collector); 00384 00385 /** 00386 * Check if there are more events after the current event. If this 00387 * returns true, then pn_collector_peek() will return an event even 00388 * after pn_collector_pop() is called. 00389 * 00390 * @param[in] collector a collector object 00391 * @return true if the collector has more than the current event 00392 */ 00393 PN_EXTERN bool pn_collector_more(pn_collector_t *collector); 00394 00395 /** 00396 * Get the type of an event. 00397 * 00398 * @param[in] event an event object 00399 * @return the type of the event 00400 */ 00401 PN_EXTERN pn_event_type_t pn_event_type(pn_event_t *event); 00402 00403 /** 00404 * Get the class associated with the event context. 00405 * 00406 * @param[in] event an event object 00407 * @return the class associated with the event context 00408 */ 00409 PN_EXTERN const pn_class_t *pn_event_class(pn_event_t *event); 00410 00411 /** 00412 * Get the context associated with an event. 00413 */ 00414 PN_EXTERN void *pn_event_context(pn_event_t *event); 00415 00416 /** 00417 * Get the connection associated with an event. 00418 * 00419 * @param[in] event an event object 00420 * @return the connection associated with the event (or NULL) 00421 */ 00422 PN_EXTERN pn_connection_t *pn_event_connection(pn_event_t *event); 00423 00424 /** 00425 * Get the session associated with an event. 00426 * 00427 * @param[in] event an event object 00428 * @return the session associated with the event (or NULL) 00429 */ 00430 PN_EXTERN pn_session_t *pn_event_session(pn_event_t *event); 00431 00432 /** 00433 * Get the link associated with an event. 00434 * 00435 * @param[in] event an event object 00436 * @return the link associated with the event (or NULL) 00437 */ 00438 PN_EXTERN pn_link_t *pn_event_link(pn_event_t *event); 00439 00440 /** 00441 * Get the delivery associated with an event. 00442 * 00443 * @param[in] event an event object 00444 * @return the delivery associated with the event (or NULL) 00445 */ 00446 PN_EXTERN pn_delivery_t *pn_event_delivery(pn_event_t *event); 00447 00448 /** 00449 * Get the transport associated with an event. 00450 * 00451 * @param[in] event an event object 00452 * @return the transport associated with the event (or NULL) 00453 */ 00454 PN_EXTERN pn_transport_t *pn_event_transport(pn_event_t *event); 00455 00456 /** 00457 * Get any attachments associated with an event. 00458 * 00459 * @param[in] event an event object 00460 * @return the record holding the attachments 00461 */ 00462 PN_EXTERN pn_record_t *pn_event_attachments(pn_event_t *event); 00463 00464 #ifdef __cplusplus 00465 } 00466 #endif 00467 00468 /** @} 00469 */ 00470 00471 #endif /* event.h */