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
proton-c
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 Mon Jun 2 2014 22:59:05 for proton by
1.8.1.2