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