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 */
The endpoint state flags for a link have changed.
Definition: event.h:116
A delivery has been created or updated.
Definition: event.h:129
PN_EXTERN pn_transport_t * pn_event_transport(pn_event_t *event)
Get the transport associated with an event.
struct pn_connection_t pn_connection_t
An AMQP Connection object.
Definition: types.h:111
The transport has new data to read and/or write.
Definition: event.h:135
Definition: event.h:103
struct pn_delivery_t pn_delivery_t
An AMQP Delivery object.
Definition: types.h:231
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
Definition: event.h:83
pn_event_type_t
An event type.
Definition: event.h:91
struct pn_collector_t pn_collector_t
An event collector.
Definition: types.h:243
Definition: event.h:84
Defined as a programming convenience.
Definition: event.h:96
The flow control state for a link has changed.
Definition: event.h:123
PN_EXTERN pn_collector_t * pn_collector(void)
Construct a collector.
PN_EXTERN void pn_collector_free(pn_collector_t *collector)
Free a collector.
PN_EXTERN pn_delivery_t * pn_event_delivery(pn_event_t *event)
Get the delivery associated with an event.
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:117
PN_EXTERN pn_link_t * pn_event_link(pn_event_t *event)
Get the link associated with an event.
struct pn_link_t pn_link_t
An AMQP Link object.
Definition: types.h:141
pn_event_category_t
Related events are grouped into categories.
Definition: event.h:82
The endpoint state flags for a connection have changed.
Definition: event.h:102
Definition: event.h:110
PN_EXTERN pn_session_t * pn_event_session(pn_event_t *event)
Get the session associated with an event.
#define PN_EXTERN
Definition: import_export.h:53
PN_EXTERN pn_event_type_t pn_event_type(pn_event_t *event)
Get the type of 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.
The endpoint state flags for a session have changed.
Definition: event.h:109
struct pn_transport_t pn_transport_t
An AMQP Transport object.
Definition: types.h:255
PN_EXTERN pn_event_category_t pn_event_category(pn_event_t *event)
Get the category an event belongs to.
Definition: event.h:85
struct pn_session_t pn_session_t
An AMQP Session object.
Definition: types.h:122
PN_EXTERN bool pn_collector_pop(pn_collector_t *collector)
Clear the head event on a collector.