proton  0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
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 <stddef.h>
28 #include <sys/types.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  * Related events are grouped into categories
81  */
82 typedef enum {
87 
88 /**
89  * An event type.
90  */
91 typedef enum {
92  /**
93  * Defined as a programming convenience. No event of this type will
94  * ever be generated.
95  */
97  /**
98  * The endpoint state flags for a connection have changed. Events of
99  * this type point to the relevant connection as well as its
100  * associated transport.
101  */
104  /**
105  * The endpoint state flags for a session have changed. Events of
106  * this type point to the relevant session as well as its associated
107  * connection and transport.
108  */
111  /**
112  * The endpoint state flags for a link have changed. Events of this
113  * type point to the relevant link as well as its associated
114  * session, connection, and transport.
115  */
118  /**
119  * The flow control state for a link has changed. Events of this
120  * type point to the relevant link along with its associated
121  * session, connection, and transport.
122  */
124  /**
125  * A delivery has been created or updated. Events of this type point
126  * to the relevant delivery as well as its associated link, session,
127  * connection, and transport.
128  */
130  /**
131  * The transport has new data to read and/or write. Events of this
132  * type point to the relevant transport as well as its associated
133  * connection.
134  */
137 
138 /**
139  * Get a human readable name for an event type.
140  *
141  * @param[in] type an event type
142  * @return a human readable name
143  */
145 
146 /**
147  * Construct a collector.
148  *
149  * A collector is used to register interest in events produced by one
150  * or more ::pn_connection_t objects. Collectors are not currently
151  * thread safe, so synchronization must be used if they are to be
152  * shared between multiple connection objects.
153  */
155 
156 /**
157  * Free a collector.
158  *
159  * @param[in] collector a collector to free, or NULL
160  */
162 
163 /**
164  * Access the head event contained by a collector.
165  *
166  * This operation will continue to return the same event until it is
167  * cleared by using ::pn_collector_pop. The pointer return by this
168  * operation will be valid until ::pn_collector_pop is invoked or
169  * ::pn_collector_free is called, whichever happens sooner.
170  *
171  * @param[in] collector a collector object
172  * @return a pointer to the head event contained in the collector
173  */
175 
176 /**
177  * Clear the head event on a collector.
178  *
179  * @param[in] collector a collector object
180  * @return true if the event was popped, false if the collector is empty
181  */
182 PN_EXTERN bool pn_collector_pop(pn_collector_t *collector);
183 
184 /**
185  * Get the type of an event.
186  *
187  * @param[in] event an event object
188  * @return the type of the event
189  */
191 
192 /**
193  * Get the category an event belongs to.
194  *
195  * @param[in] event an event object
196  * @return the category the event belongs to
197  */
199 
200 /**
201  * Get the connection associated with an event.
202  *
203  * @param[in] event an event object
204  * @return the connection associated with the event (or NULL)
205  */
207 
208 /**
209  * Get the session associated with an event.
210  *
211  * @param[in] event an event object
212  * @return the session associated with the event (or NULL)
213  */
215 
216 /**
217  * Get the link associated with an event.
218  *
219  * @param[in] event an event object
220  * @return the link associated with the event (or NULL)
221  */
223 
224 /**
225  * Get the delivery associated with an event.
226  *
227  * @param[in] event an event object
228  * @return the delivery associated with the event (or NULL)
229  */
231 
232 /**
233  * Get the transport associated with an event.
234  *
235  * @param[in] event an event object
236  * @return the transport associated with the event (or NULL)
237  */
239 
240 #ifdef __cplusplus
241 }
242 #endif
243 
244 /** @}
245  */
246 
247 #endif /* event.h */