proton  0
event.h
Go to the documentation of this file.
1 #ifndef PROTON_EVENT_H
2 #define PROTON_EVENT_H 1
3 
4 /*
5  *
6  * Licensed to the Apache Software Foundation (ASF) under one
7  * or more contributor license agreements. See the NOTICE file
8  * distributed with this work for additional information
9  * regarding copyright ownership. The ASF licenses this file
10  * to you under the Apache License, Version 2.0 (the
11  * "License"); you may not use this file except in compliance
12  * with the License. You may obtain a copy of the License at
13  *
14  * http://www.apache.org/licenses/LICENSE-2.0
15  *
16  * Unless required by applicable law or agreed to in writing,
17  * software distributed under the License is distributed on an
18  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
19  * KIND, either express or implied. See the License for the
20  * specific language governing permissions and limitations
21  * under the License.
22  *
23  */
24 
25 #include <proton/import_export.h>
26 #include <proton/type_compat.h>
27 #include <proton/object.h>
28 #include <stddef.h>
29 
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33 
34 /**
35  * @file
36  *
37  * Event API for the proton Engine.
38  *
39  * @defgroup event Event
40  * @ingroup engine
41  * @{
42  */
43 
44 /**
45  * An event provides notification of a state change within the
46  * protocol engine's object model.
47  *
48  * The AMQP endpoint state modeled by the protocol engine is captured
49  * by the following object types: @link pn_delivery_t Deliveries
50  * @endlink, @link pn_link_t Links @endlink, @link pn_session_t
51  * Sessions @endlink, @link pn_connection_t Connections @endlink, and
52  * @link pn_transport_t Transports @endlink. These objects are related
53  * as follows:
54  *
55  * - @link pn_delivery_t Deliveries @endlink always have a single
56  * parent Link
57  * - @link pn_link_t Links @endlink always have a single parent
58  * Session
59  * - @link pn_session_t Sessions @endlink always have a single parent
60  * Connection
61  * - @link pn_connection_t Connections @endlink optionally have at
62  * most one associated Transport
63  * - @link pn_transport_t Transports @endlink optionally have at most
64  * one associated Connection
65  *
66  * Every event has a type (see ::pn_event_type_t) that identifies what
67  * sort of state change has occurred along with a pointer to the
68  * object whose state has changed (as well as its associated objects).
69  *
70  * Events are accessed by creating a @link pn_collector_t Collector
71  * @endlink with ::pn_collector() and registering it with the @link
72  * pn_connection_t Connection @endlink of interest through use of
73  * ::pn_connection_collect(). Once a collector has been registered,
74  * ::pn_collector_peek() and ::pn_collector_pop() are used to access
75  * and process events.
76  */
77 typedef struct pn_event_t pn_event_t;
78 
79 /**
80  * An event type.
81  */
82 typedef enum {
83  /**
84  * Defined as a programming convenience. No event of this type will
85  * ever be generated.
86  */
88 
89  /**
90  * A reactor has been started. Events of this type point to the reactor.
91  */
93 
94  /**
95  * A reactor has no more events to process. Events of this type
96  * point to the reactor.
97  */
99 
100  /**
101  * A reactor has been stopped. Events of this type point to the reactor.
102  */
104 
105  /**
106  * A timer event has occurred.
107  */
109 
110  /**
111  * The connection has been created. This is the first event that
112  * will ever be issued for a connection. Events of this type point
113  * to the relevant connection.
114  */
116 
117  /**
118  * The connection has been bound to a transport. This event is
119  * issued when the ::pn_transport_bind() operation is invoked.
120  */
122 
123  /**
124  * The connection has been unbound from its transport. This event is
125  * issued when the ::pn_transport_unbind() operation is invoked.
126  */
128 
129  /**
130  * The local connection endpoint has been closed. Events of this
131  * type point to the relevant connection.
132  */
134 
135  /**
136  * The remote endpoint has opened the connection. Events of this
137  * type point to the relevant connection.
138  */
140 
141  /**
142  * The local connection endpoint has been closed. Events of this
143  * type point to the relevant connection.
144  */
146 
147  /**
148  * The remote endpoint has closed the connection. Events of this
149  * type point to the relevant connection.
150  */
152 
153  /**
154  * The connection has been freed and any outstanding processing has
155  * been completed. This is the final event that will ever be issued
156  * for a connection.
157  */
159 
160  /**
161  * The session has been created. This is the first event that will
162  * ever be issued for a session.
163  */
165 
166  /**
167  * The local session endpoint has been opened. Events of this type
168  * point ot the relevant session.
169  */
171 
172  /**
173  * The remote endpoint has opened the session. Events of this type
174  * point to the relevant session.
175  */
177 
178  /**
179  * The local session endpoint has been closed. Events of this type
180  * point ot the relevant session.
181  */
183 
184  /**
185  * The remote endpoint has closed the session. Events of this type
186  * point to the relevant session.
187  */
189 
190  /**
191  * The session has been freed and any outstanding processing has
192  * been completed. This is the final event that will ever be issued
193  * for a session.
194  */
196 
197  /**
198  * The link has been created. This is the first event that will ever
199  * be issued for a link.
200  */
202 
203  /**
204  * The local link endpoint has been opened. Events of this type
205  * point ot the relevant link.
206  */
208 
209  /**
210  * The remote endpoint has opened the link. Events of this type
211  * point to the relevant link.
212  */
214 
215  /**
216  * The local link endpoint has been closed. Events of this type
217  * point ot the relevant link.
218  */
220 
221  /**
222  * The remote endpoint has closed the link. Events of this type
223  * point to the relevant link.
224  */
226 
227  /**
228  * The local link endpoint has been detached. Events of this type
229  * point to the relevant link.
230  */
232 
233  /**
234  * The remote endpoint has detached the link. Events of this type
235  * point to the relevant link.
236  */
238 
239  /**
240  * The flow control state for a link has changed. Events of this
241  * type point to the relevant link.
242  */
244 
245  /**
246  * The link has been freed and any outstanding processing has been
247  * completed. This is the final event that will ever be issued for a
248  * link. Events of this type point to the relevant link.
249  */
251 
252  /**
253  * A delivery has been created or updated. Events of this type point
254  * to the relevant delivery.
255  */
257 
258  /**
259  * The transport has new data to read and/or write. Events of this
260  * type point to the relevant transport.
261  */
263 
264  /**
265  * The transport has authenticated, if this is received by a server
266  * the associated transport has authenticated an incoming connection
267  * and pn_transport_get_user() can be used to obtain the authenticated
268  * user.
269  */
271 
272  /**
273  * Indicates that a transport error has occurred. Use
274  * ::pn_transport_condition() to access the details of the error
275  * from the associated transport.
276  */
278 
279  /**
280  * Indicates that the head of the transport has been closed. This
281  * means the transport will never produce more bytes for output to
282  * the network. Events of this type point to the relevant transport.
283  */
285 
286  /**
287  * Indicates that the tail of the transport has been closed. This
288  * means the transport will never be able to process more bytes from
289  * the network. Events of this type point to the relevant transport.
290  */
292 
293  /**
294  * Indicates that the both the head and tail of the transport are
295  * closed. Events of this type point to the relevant transport.
296  */
298 
306 
308 
309 /**
310  * Get a human readable name for an event type.
311  *
312  * @param[in] type an event type
313  * @return a human readable name
314  */
315 PN_EXTERN const char *pn_event_type_name(pn_event_type_t type);
316 
317 /**
318  * Construct a collector.
319  *
320  * A collector is used to register interest in events produced by one
321  * or more ::pn_connection_t objects. Collectors are not currently
322  * thread safe, so synchronization must be used if they are to be
323  * shared between multiple connection objects.
324  */
326 
327 /**
328  * Free a collector.
329  *
330  * @param[in] collector a collector to free, or NULL
331  */
333 
334 /**
335  * Release a collector. Once in a released state a collector will
336  * drain any internally queued events (thereby releasing any pointers
337  * they may hold), shrink it's memory footprint to a minimum, and
338  * discard any newly created events.
339  *
340  * @param[in] collector a collector object
341  */
343 
344 /**
345  * Place a new event on a collector.
346  *
347  * This operation will create a new event of the given type and
348  * context and return a pointer to the newly created event. In some
349  * cases an event of the given type and context can be elided. When
350  * this happens, this operation will return a NULL pointer.
351  *
352  * @param[in] collector a collector object
353  * @param[in] clazz class of the context
354  * @param[in] context the event context
355  * @param[in] type the event type
356  *
357  * @return a pointer to the newly created event or NULL if the event
358  * was elided
359  */
360 
362  const pn_class_t *clazz, void *context,
363  pn_event_type_t type);
364 
365 /**
366  * Access the head event contained by a collector.
367  *
368  * This operation will continue to return the same event until it is
369  * cleared by using ::pn_collector_pop. The pointer return by this
370  * operation will be valid until ::pn_collector_pop is invoked or
371  * ::pn_collector_free is called, whichever happens sooner.
372  *
373  * @param[in] collector a collector object
374  * @return a pointer to the head event contained in the collector
375  */
377 
378 /**
379  * Clear the head event on a collector.
380  *
381  * @param[in] collector a collector object
382  * @return true if the event was popped, false if the collector is empty
383  */
384 PN_EXTERN bool pn_collector_pop(pn_collector_t *collector);
385 
386 /**
387  * Check if there are more events after the current event. If this
388  * returns true, then pn_collector_peek() will return an event even
389  * after pn_collector_pop() is called.
390  *
391  * @param[in] collector a collector object
392  * @return true if the collector has more than the current event
393  */
395 
396 /**
397  * Get the type of an event.
398  *
399  * @param[in] event an event object
400  * @return the type of the event
401  */
402 PN_EXTERN pn_event_type_t pn_event_type(pn_event_t *event);
403 
404 /**
405  * Get the class associated with the event context.
406  *
407  * @param[in] event an event object
408  * @return the class associated with the event context
409  */
411 
412 /**
413  * Get the context associated with an event.
414  */
416 
417 /**
418  * Get the root handler the current event was dispatched to.
419  */
421 
422 /**
423  * Get the connection associated with an event.
424  *
425  * @param[in] event an event object
426  * @return the connection associated with the event (or NULL)
427  */
429 
430 /**
431  * Get the session associated with an event.
432  *
433  * @param[in] event an event object
434  * @return the session associated with the event (or NULL)
435  */
437 
438 /**
439  * Get the link associated with an event.
440  *
441  * @param[in] event an event object
442  * @return the link associated with the event (or NULL)
443  */
445 
446 /**
447  * Get the delivery associated with an event.
448  *
449  * @param[in] event an event object
450  * @return the delivery associated with the event (or NULL)
451  */
453 
454 /**
455  * Get the transport associated with an event.
456  *
457  * @param[in] event an event object
458  * @return the transport associated with the event (or NULL)
459  */
461 
462 /**
463  * Get any attachments associated with an event.
464  *
465  * @param[in] event an event object
466  * @return the record holding the attachments
467  */
469 
470 #ifdef __cplusplus
471 }
472 #endif
473 
474 /** @}
475  */
476 
477 #endif /* event.h */
Indicates that the both the head and tail of the transport are closed.
Definition: event.h:297
PN_EXTERN pn_record_t * pn_event_attachments(pn_event_t *event)
Get any attachments associated with an event.
The local session endpoint has been opened.
Definition: event.h:170
pn_event_type_t
An event type.
Definition: event.h:82
The remote endpoint has closed the link.
Definition: event.h:225
PN_EXTERN pn_session_t * pn_event_session(pn_event_t *event)
Get the session associated with an event.
Definition: event.h:302
The flow control state for a link has changed.
Definition: event.h:243
PN_EXTERN bool pn_collector_pop(pn_collector_t *collector)
Clear the head event on a collector.
struct pn_record_t pn_record_t
Definition: object.h:46
The connection has been unbound from its transport.
Definition: event.h:127
The local link endpoint has been detached.
Definition: event.h:231
PN_EXTERN void pn_collector_free(pn_collector_t *collector)
Free a collector.
struct pn_transport_t pn_transport_t
An AMQP Transport object.
Definition: types.h:262
PN_EXTERN pn_handler_t * pn_event_root(pn_event_t *event)
Get the root handler the current event was dispatched to.
PN_EXTERN pn_event_t * pn_collector_put(pn_collector_t *collector, const pn_class_t *clazz, void *context, pn_event_type_t type)
Place a new event on a collector.
The link has been created.
Definition: event.h:201
The local connection endpoint has been closed.
Definition: event.h:145
PN_EXTERN pn_connection_t * pn_event_connection(pn_event_t *event)
Get the connection associated with an event.
A delivery has been created or updated.
Definition: event.h:256
PN_EXTERN void * pn_event_context(pn_event_t *event)
Get the context associated with an event.
The connection has been bound to a transport.
Definition: event.h:121
The remote endpoint has detached the link.
Definition: event.h:237
Indicates that the tail of the transport has been closed.
Definition: event.h:291
PN_EXTERN pn_event_type_t pn_event_type(pn_event_t *event)
Get the type of an event.
Defined as a programming convenience.
Definition: event.h:87
Definition: event.h:305
#define PN_EXTERN
Definition: import_export.h:53
PN_EXTERN bool pn_collector_more(pn_collector_t *collector)
Check if there are more events after the current event.
struct pn_collector_t pn_collector_t
An event collector.
Definition: types.h:250
struct pn_session_t pn_session_t
An AMQP Session object.
Definition: types.h:129
PN_EXTERN const pn_class_t * pn_event_class(pn_event_t *event)
Get the class associated with the event context.
Definition: event.h:299
The connection has been created.
Definition: event.h:115
The local session endpoint has been closed.
Definition: event.h:182
The local connection endpoint has been closed.
Definition: event.h:133
The session has been created.
Definition: event.h:164
PN_EXTERN const char * pn_event_type_name(pn_event_type_t type)
Get a human readable name for an event type.
Definition: event.h:300
struct pn_handler_t pn_handler_t
An event handler.
Definition: types.h:271
struct pn_delivery_t pn_delivery_t
An AMQP Delivery object.
Definition: types.h:238
A reactor has been started.
Definition: event.h:92
PN_EXTERN pn_link_t * pn_event_link(pn_event_t *event)
Get the link associated with an event.
The remote endpoint has opened the connection.
Definition: event.h:139
Definition: object.h:48
The link has been freed and any outstanding processing has been completed.
Definition: event.h:250
A timer event has occurred.
Definition: event.h:108
PN_EXTERN pn_transport_t * pn_event_transport(pn_event_t *event)
Get the transport associated with an event.
The session has been freed and any outstanding processing has been completed.
Definition: event.h:195
PN_EXTERN pn_collector_t * pn_collector(void)
Construct a collector.
The remote endpoint has opened the session.
Definition: event.h:176
Indicates that the head of the transport has been closed.
Definition: event.h:284
PN_EXTERN void pn_collector_release(pn_collector_t *collector)
Release a collector.
PN_EXTERN pn_delivery_t * pn_event_delivery(pn_event_t *event)
Get the delivery associated with an event.
PN_EXTERN pn_event_t * pn_collector_peek(pn_collector_t *collector)
Access the head event contained by a collector.
The remote endpoint has opened the link.
Definition: event.h:213
struct pn_connection_t pn_connection_t
An AMQP Connection object.
Definition: types.h:118
The local link endpoint has been opened.
Definition: event.h:207
Definition: event.h:304
A reactor has been stopped.
Definition: event.h:103
Definition: event.h:303
The transport has new data to read and/or write.
Definition: event.h:262
Indicates that a transport error has occurred.
Definition: event.h:277
The remote endpoint has closed the session.
Definition: event.h:188
The remote endpoint has closed the connection.
Definition: event.h:151
The connection has been freed and any outstanding processing has been completed.
Definition: event.h:158
The transport has authenticated, if this is received by a server the associated transport has authent...
Definition: event.h:270
struct pn_event_t pn_event_t
An event provides notification of a state change within the protocol engine&#39;s object model...
Definition: event.h:77
A reactor has no more events to process.
Definition: event.h:98
The local link endpoint has been closed.
Definition: event.h:219
Definition: event.h:301