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  * 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  * The connection has been created. This is the first event that
91  * will ever be issued for a connection. Events of this type point
92  * to the relevant connection.
93  */
95 
96  /**
97  * The connection has been bound to a transport. This event is
98  * issued when the ::pn_transport_bind() operation is invoked.
99  */
101 
102  /**
103  * The connection has been unbound from its transport. This event is
104  * issued when the ::pn_transport_unbind() operation is invoked.
105  */
107 
108  /**
109  * The local connection endpoint has been closed. Events of this
110  * type point to the relevant connection.
111  */
113 
114  /**
115  * The remote endpoint has opened the connection. Events of this
116  * type point to the relevant connection.
117  */
119 
120  /**
121  * The local connection endpoint has been closed. Events of this
122  * type point to the relevant connection.
123  */
125 
126  /**
127  * The remote endpoint has closed the connection. Events of this
128  * type point to the relevant connection.
129  */
131 
132  /**
133  * The connection has been freed and any outstanding processing has
134  * been completed. This is the final event that will ever be issued
135  * for a connection.
136  */
138 
139  /**
140  * The session has been created. This is the first event that will
141  * ever be issued for a session.
142  */
144 
145  /**
146  * The local session endpoint has been opened. Events of this type
147  * point ot the relevant session.
148  */
150 
151  /**
152  * The remote endpoint has opened the session. Events of this type
153  * point to the relevant session.
154  */
156 
157  /**
158  * The local session endpoint has been closed. Events of this type
159  * point ot the relevant session.
160  */
162 
163  /**
164  * The remote endpoint has closed the session. Events of this type
165  * point to the relevant session.
166  */
168 
169  /**
170  * The session has been freed and any outstanding processing has
171  * been completed. This is the final event that will ever be issued
172  * for a session.
173  */
175 
176  /**
177  * The link has been created. This is the first event that will ever
178  * be issued for a link.
179  */
181 
182  /**
183  * The local link endpoint has been opened. Events of this type
184  * point ot the relevant link.
185  */
187 
188  /**
189  * The remote endpoint has opened the link. Events of this type
190  * point to the relevant link.
191  */
193 
194  /**
195  * The local link endpoint has been closed. Events of this type
196  * point ot the relevant link.
197  */
199 
200  /**
201  * The remote endpoint has closed the link. Events of this type
202  * point to the relevant link.
203  */
205 
206  /**
207  * The local link endpoint has been detached. Events of this type
208  * point to the relevant link.
209  */
211 
212  /**
213  * The remote endpoint has detached the link. Events of this type
214  * point to the relevant link.
215  */
217 
218  /**
219  * The flow control state for a link has changed. Events of this
220  * type point to the relevant link.
221  */
223 
224  /**
225  * The link has been freed and any outstanding processing has been
226  * completed. This is the final event that will ever be issued for a
227  * link. Events of this type point to the relevant link.
228  */
230 
231  /**
232  * A delivery has been created or updated. Events of this type point
233  * to the relevant delivery.
234  */
236 
237  /**
238  * The transport has new data to read and/or write. Events of this
239  * type point to the relevant transport.
240  */
242 
243  /**
244  * Indicates that a transport error has occurred. Use
245  * ::pn_transport_condition() to access the details of the error
246  * from the associated transport.
247  */
249 
250  /**
251  * Indicates that the head of the transport has been closed. This
252  * means the transport will never produce more bytes for output to
253  * the network. Events of this type point to the relevant transport.
254  */
256 
257  /**
258  * Indicates that the tail of the transport has been closed. This
259  * means the transport will never be able to process more bytes from
260  * the network. Events of this type point to the relevant transport.
261  */
263 
264  /**
265  * Indicates that the both the head and tail of the transport are
266  * closed. Events of this type point to the relevant transport.
267  */
269 
271 
272 /**
273  * Get a human readable name for an event type.
274  *
275  * @param[in] type an event type
276  * @return a human readable name
277  */
279 
280 /**
281  * Construct a collector.
282  *
283  * A collector is used to register interest in events produced by one
284  * or more ::pn_connection_t objects. Collectors are not currently
285  * thread safe, so synchronization must be used if they are to be
286  * shared between multiple connection objects.
287  */
289 
290 /**
291  * Free a collector.
292  *
293  * @param[in] collector a collector to free, or NULL
294  */
296 
297 /**
298  * Place a new event on a collector.
299  *
300  * This operation will create a new event of the given type and
301  * context and return a pointer to the newly created event. In some
302  * cases an event of the given type and context can be elided. When
303  * this happens, this operation will return a NULL pointer.
304  *
305  * @param[in] collector a collector object
306  * @param[in] type the event type
307  * @param[in] context the event context
308  *
309  * @return a pointer to the newly created event or NULL if the event
310  * was elided
311  */
312 
314  const pn_class_t *clazz, void *context,
315  pn_event_type_t type);
316 
317 /**
318  * Access the head event contained by a collector.
319  *
320  * This operation will continue to return the same event until it is
321  * cleared by using ::pn_collector_pop. The pointer return by this
322  * operation will be valid until ::pn_collector_pop is invoked or
323  * ::pn_collector_free is called, whichever happens sooner.
324  *
325  * @param[in] collector a collector object
326  * @return a pointer to the head event contained in the collector
327  */
329 
330 /**
331  * Clear the head event on a collector.
332  *
333  * @param[in] collector a collector object
334  * @return true if the event was popped, false if the collector is empty
335  */
336 PN_EXTERN bool pn_collector_pop(pn_collector_t *collector);
337 
338 /**
339  * Get the type of an event.
340  *
341  * @param[in] event an event object
342  * @return the type of the event
343  */
345 
346 /**
347  * Get the class associated with the event context.
348  *
349  * @param[in] event an event object
350  * @return the class associated with the event context
351  */
353 
354 /**
355  * Get the context associated with an event.
356  */
358 
359 /**
360  * Get the connection associated with an event.
361  *
362  * @param[in] event an event object
363  * @return the connection associated with the event (or NULL)
364  */
366 
367 /**
368  * Get the session associated with an event.
369  *
370  * @param[in] event an event object
371  * @return the session associated with the event (or NULL)
372  */
374 
375 /**
376  * Get the link associated with an event.
377  *
378  * @param[in] event an event object
379  * @return the link associated with the event (or NULL)
380  */
382 
383 /**
384  * Get the delivery associated with an event.
385  *
386  * @param[in] event an event object
387  * @return the delivery associated with the event (or NULL)
388  */
390 
391 /**
392  * Get the transport associated with an event.
393  *
394  * @param[in] event an event object
395  * @return the transport associated with the event (or NULL)
396  */
398 
399 #ifdef __cplusplus
400 }
401 #endif
402 
403 /** @}
404  */
405 
406 #endif /* event.h */
PN_EXTERN void pn_collector_free(pn_collector_t *collector)
Free a collector.
The connection has been bound to a transport.
Definition: event.h:100
PN_EXTERN const char * pn_event_type_name(pn_event_type_t type)
Get a human readable name for an event type.
Indicates that the both the head and tail of the transport are closed.
Definition: event.h:268
PN_EXTERN pn_collector_t * pn_collector(void)
Construct a collector.
Indicates that the tail of the transport has been closed.
Definition: event.h:262
The link has been freed and any outstanding processing has been completed.
Definition: event.h:229
PN_EXTERN pn_transport_t * pn_event_transport(pn_event_t *event)
Get the transport associated with an event.
PN_EXTERN const pn_class_t * pn_event_class(pn_event_t *event)
Get the class associated with the event context.
The remote endpoint has closed the link.
Definition: event.h:204
The local link endpoint has been closed.
Definition: event.h:198
struct pn_collector_t pn_collector_t
An event collector.
Definition: types.h:243
Defined as a programming convenience.
Definition: event.h:87
#define PN_EXTERN
Definition: import_export.h:53
The remote endpoint has closed the connection.
Definition: event.h:130
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
The local connection endpoint has been closed.
Definition: event.h:124
PN_EXTERN pn_session_t * pn_event_session(pn_event_t *event)
Get the session associated with an event.
The remote endpoint has closed the session.
Definition: event.h:167
struct pn_delivery_t pn_delivery_t
An AMQP Delivery object.
Definition: types.h:231
PN_EXTERN pn_event_t * pn_collector_peek(pn_collector_t *collector)
Access the head event contained by a collector.
PN_EXTERN pn_link_t * pn_event_link(pn_event_t *event)
Get the link associated with an event.
PN_EXTERN pn_event_type_t pn_event_type(pn_event_t *event)
Get the type of an event.
pn_event_type_t
An event type.
Definition: event.h:82
The local link endpoint has been detached.
Definition: event.h:210
The local link endpoint has been opened.
Definition: event.h:186
The local session endpoint has been closed.
Definition: event.h:161
Indicates that a transport error has occurred.
Definition: event.h:248
The local connection endpoint has been closed.
Definition: event.h:112
The connection has been freed and any outstanding processing has been completed.
Definition: event.h:137
PN_EXTERN bool pn_collector_pop(pn_collector_t *collector)
Clear the head event on a collector.
The session has been created.
Definition: event.h:143
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 detached the link.
Definition: event.h:216
PN_EXTERN void * pn_event_context(pn_event_t *event)
Get the context associated with an event.
Definition: object.h:47
The transport has new data to read and/or write.
Definition: event.h:241
The remote endpoint has opened the link.
Definition: event.h:192
The remote endpoint has opened the session.
Definition: event.h:155
PN_EXTERN pn_connection_t * pn_event_connection(pn_event_t *event)
Get the connection associated with an event.
The connection has been created.
Definition: event.h:94
The session has been freed and any outstanding processing has been completed.
Definition: event.h:174
struct pn_connection_t pn_connection_t
An AMQP Connection object.
Definition: types.h:111
struct pn_session_t pn_session_t
An AMQP Session object.
Definition: types.h:122
A delivery has been created or updated.
Definition: event.h:235
The remote endpoint has opened the connection.
Definition: event.h:118
The local session endpoint has been opened.
Definition: event.h:149
The link has been created.
Definition: event.h:180
The flow control state for a link has changed.
Definition: event.h:222
Indicates that the head of the transport has been closed.
Definition: event.h:255
struct pn_link_t pn_link_t
An AMQP Link object.
Definition: types.h:141
struct pn_transport_t pn_transport_t
An AMQP Transport object.
Definition: types.h:255
PN_EXTERN pn_delivery_t * pn_event_delivery(pn_event_t *event)
Get the delivery associated with an event.
The connection has been unbound from its transport.
Definition: event.h:106