proton
0
Main Page
Related Pages
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Macros
Groups
Pages
include
proton
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
{
83
PN_EVENT_CATEGORY_NONE
= 0,
84
PN_EVENT_CATEGORY_PROTOCOL
= 0x00010000,
85
PN_EVENT_CATEGORY_COUNT
= 2
86
}
pn_event_category_t
;
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
*/
96
PN_EVENT_NONE
= 0,
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
*/
102
PN_CONNECTION_REMOTE_STATE
=
PN_EVENT_CATEGORY_PROTOCOL
+1,
103
PN_CONNECTION_LOCAL_STATE
=
PN_EVENT_CATEGORY_PROTOCOL
+2,
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
*/
109
PN_SESSION_REMOTE_STATE
=
PN_EVENT_CATEGORY_PROTOCOL
+3,
110
PN_SESSION_LOCAL_STATE
=
PN_EVENT_CATEGORY_PROTOCOL
+4,
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
*/
116
PN_LINK_REMOTE_STATE
=
PN_EVENT_CATEGORY_PROTOCOL
+5,
117
PN_LINK_LOCAL_STATE
=
PN_EVENT_CATEGORY_PROTOCOL
+6,
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
*/
123
PN_LINK_FLOW
=
PN_EVENT_CATEGORY_PROTOCOL
+7,
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
*/
129
PN_DELIVERY
=
PN_EVENT_CATEGORY_PROTOCOL
+8,
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
*/
135
PN_TRANSPORT
=
PN_EVENT_CATEGORY_PROTOCOL
+9
136
}
pn_event_type_t
;
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
*/
144
PN_EXTERN
const
char
*
pn_event_type_name
(
pn_event_type_t
type);
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
*/
154
PN_EXTERN
pn_collector_t
*
pn_collector
(
void
);
155
156
/**
157
* Free a collector.
158
*
159
* @param[in] collector a collector to free, or NULL
160
*/
161
PN_EXTERN
void
pn_collector_free
(
pn_collector_t
*collector);
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
*/
174
PN_EXTERN
pn_event_t
*
pn_collector_peek
(
pn_collector_t
*collector);
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
*/
190
PN_EXTERN
pn_event_type_t
pn_event_type
(
pn_event_t
*event);
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
*/
198
PN_EXTERN
pn_event_category_t
pn_event_category
(
pn_event_t
*event);
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
*/
206
PN_EXTERN
pn_connection_t
*
pn_event_connection
(
pn_event_t
*event);
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
*/
214
PN_EXTERN
pn_session_t
*
pn_event_session
(
pn_event_t
*event);
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
*/
222
PN_EXTERN
pn_link_t
*
pn_event_link
(
pn_event_t
*event);
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
*/
230
PN_EXTERN
pn_delivery_t
*
pn_event_delivery
(
pn_event_t
*event);
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
*/
238
PN_EXTERN
pn_transport_t
*
pn_event_transport
(
pn_event_t
*event);
239
240
#ifdef __cplusplus
241
}
242
#endif
243
244
/** @}
245
*/
246
247
#endif
/* event.h */
Generated on Thu Jul 10 2014 02:10:59 for proton by
1.8.3.1