Asterisk - The Open Source Telephony Project  21.4.1
event.h
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2007 - 2008, Digium, Inc.
5  *
6  * Russell Bryant <russell@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18 
19 /*!
20  * \file
21  * \author Russell Bryant <russell@digium.com>
22  * \ref AstGenericEvents
23  */
24 
25 /*!
26  * \page AstGenericEvents Generic event system
27  *
28  * Prior to the creation of \ref stasis, the purpose of this API was to provide
29  * a generic way to share events between Asterisk modules. Once there was a need
30  * to disseminate data whose definition was provided by the producers/consumers,
31  * it was no longer possible to use the binary representation in the generic
32  * event system.
33  *
34  * That aside, the generic event system is still useful and used by several
35  * modules in Asterisk.
36  * - CEL uses the \ref ast_event representation to pass information to registered
37  * backends.
38  * - The \file res_corosync.c module publishes \ref ast_event representations of
39  * information to other Asterisk instances in a cluster.
40  * - Security event represent their event types and data using this system.
41  * - Theoretically, any \ref stasis message can use this system to pass
42  * information around in a binary format.
43  *
44  * Events have an associated event type, as well as information elements. The
45  * information elements are the meta data that go along with each event. For
46  * example, in the case of message waiting indication, the event type is MWI,
47  * and each MWI event contains at least three information elements: the
48  * mailbox, the number of new messages, and the number of old messages.
49  */
50 
51 #ifndef AST_EVENT_H
52 #define AST_EVENT_H
53 
54 #if defined(__cplusplus) || defined(c_plusplus)
55 extern "C" {
56 #endif
57 
58 #include "asterisk/event_defs.h"
59 
60 /*!
61  * \brief Create a new event
62  *
63  * \param event_type The type of event to create
64  *
65  * The rest of the arguments to this function specify information elements to
66  * add to the event. They are specified in the form:
67  * \code
68  * <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ]
69  * \endcode
70  * and must end with AST_EVENT_IE_END.
71  *
72  * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed
73  * by a valid IE payload type. A payload must also be specified
74  * after the IE payload type.
75  *
76  * \note The EID IE will be appended automatically when this function is used
77  * with at least one IE specified.
78  *
79  * \return This returns the event that has been created. If there is an error
80  * creating the event, NULL will be returned.
81  *
82  * Example usage:
83  *
84  * \code
85  * if (!(event = ast_event_new(AST_EVENT_MWI,
86  * AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, mailbox,
87  * AST_EVENT_IE_NEWMSGS, AST_EVENT_IE_PLTYPE_UINT, new,
88  * AST_EVENT_IE_OLDMSGS, AST_EVENT_IE_PLTYPE_UINT, old,
89  * AST_EVENT_IE_END))) {
90  * return;
91  * }
92  * \endcode
93  *
94  * This creates a MWI event with 3 information elements, a mailbox which is
95  * a string, and the number of new and old messages, specified as integers.
96  */
97 struct ast_event *ast_event_new(enum ast_event_type event_type, ...);
98 
99 /*!
100  * \brief Destroy an event
101  *
102  * \param event the event to destroy
103  */
104 void ast_event_destroy(struct ast_event *event);
105 
106 /*!
107  * \brief Append an information element that has a string payload
108  *
109  * \param event the event that the IE will be appended to
110  * \param ie_type the type of IE to append
111  * \param str The string for the payload of the IE
112  *
113  * \retval 0 success
114  * \retval -1 failure
115  *
116  * The pointer to the event will get updated with the new location for the event
117  * that now contains the appended information element. If the re-allocation of
118  * the memory for this event fails, it will be set to NULL.
119  */
120 int ast_event_append_ie_str(struct ast_event **event, enum ast_event_ie_type ie_type,
121  const char *str);
122 
123 /*!
124  * \brief Append an information element that has an integer payload
125  *
126  * \param event the event that the IE will be appended to
127  * \param ie_type the type of IE to append
128  * \param data The integer for the payload of the IE
129  *
130  * \retval 0 success
131  * \retval -1 failure
132  *
133  * The pointer to the event will get updated with the new location for the event
134  * that now contains the appended information element. If the re-allocation of
135  * the memory for this event fails, it will be set to NULL.
136  */
137 int ast_event_append_ie_uint(struct ast_event **event, enum ast_event_ie_type ie_type,
138  uint32_t data);
139 
140 /*!
141  * \brief Append an information element that has a bitflags payload
142  *
143  * \param event the event that the IE will be appended to
144  * \param ie_type the type of IE to append
145  * \param bitflags the flags that are the payload of the IE
146  *
147  * \retval 0 success
148  * \retval -1 failure
149  * \since 1.8
150  *
151  * The pointer to the event will get updated with the new location for the event
152  * that now contains the appended information element. If the re-allocation of
153  * the memory for this event fails, it will be set to NULL.
154  */
156  uint32_t bitflags);
157 
158 /*!
159  * \brief Append an information element that has a raw payload
160  *
161  * \param event the event that the IE will be appended to
162  * \param ie_type the type of IE to append
163  * \param data A pointer to the raw data for the payload of the IE
164  * \param data_len The amount of data to copy into the payload
165  *
166  * \retval 0 success
167  * \retval -1 failure
168  *
169  * The pointer to the event will get updated with the new location for the event
170  * that now contains the appended information element. If the re-allocation of
171  * the memory for this event fails, it will be set to NULL.
172  */
173 int ast_event_append_ie_raw(struct ast_event **event, enum ast_event_ie_type ie_type,
174  const void *data, size_t data_len);
175 
176 /*!
177  * \brief Append the global EID IE
178  *
179  * \param event the event to append IE to
180  *
181  * \note For ast_event_new() that includes IEs, this is done automatically
182  * for you.
183  *
184  * \retval 0 success
185  * \retval -1 failure
186  */
187 int ast_event_append_eid(struct ast_event **event);
188 
189 /*!
190  * \brief Get the value of an information element that has an integer payload
191  *
192  * \param event The event to get the IE from
193  * \param ie_type the type of information element to retrieve
194  *
195  * \return This returns the payload of the information element with the given type.
196  * However, an IE with a payload of 0, and the case where no IE is found
197  * yield the same return value.
198  */
199 uint32_t ast_event_get_ie_uint(const struct ast_event *event, enum ast_event_ie_type ie_type);
200 
201 /*!
202  * \brief Get the value of an information element that has a string payload
203  *
204  * \param event The event to get the IE from
205  * \param ie_type the type of information element to retrieve
206  *
207  * \return This returns the payload of the information element with the given type.
208  * If the information element isn't found, NULL will be returned.
209  */
210 const char *ast_event_get_ie_str(const struct ast_event *event, enum ast_event_ie_type ie_type);
211 
212 /*!
213  * \brief Get the value of an information element that has a raw payload
214  *
215  * \param event The event to get the IE from
216  * \param ie_type the type of information element to retrieve
217  *
218  * \return This returns the payload of the information element with the given type.
219  * If the information element isn't found, NULL will be returned.
220  */
221 const void *ast_event_get_ie_raw(const struct ast_event *event, enum ast_event_ie_type ie_type);
222 
223 /*!
224  * \brief Get the length of the raw payload for a particular IE
225  *
226  * \param event The event to get the IE payload length from
227  * \param ie_type the type of information element to get the length of
228  *
229  * \return If an IE of type ie_type is found, its payload length is returned.
230  * Otherwise, 0 is returned.
231  */
232 uint16_t ast_event_get_ie_raw_payload_len(const struct ast_event *event, enum ast_event_ie_type ie_type);
233 
234 /*!
235  * \brief Get the string representation of the type of the given event
236  *
237  * \arg event the event to get the type of
238  *
239  * \return the string representation of the event type of the provided event
240  * \since 1.6.1
241  */
242 const char *ast_event_get_type_name(const struct ast_event *event);
243 
244 /*!
245  * \brief Get the string representation of an information element type
246  *
247  * \param ie_type the information element type to get the string representation of
248  *
249  * \return the string representation of the information element type
250  * \since 1.6.1
251  */
252 const char *ast_event_get_ie_type_name(enum ast_event_ie_type ie_type);
253 
254 /*!
255  * \brief Get the payload type for a given information element type
256  *
257  * \param ie_type the information element type to get the payload type of
258  *
259  * \return the payload type for the provided IE type
260  * \since 1.6.1
261  */
263 
264 /*!
265  * \brief Get the type for an event
266  *
267  * \param event the event to get the type for
268  *
269  * \return the event type as represented by one of the values in the
270  * ast_event_type enum
271  */
273 
274 /*!
275  * \brief Convert a string to an IE type
276  *
277  * \param str the string to convert
278  * \param ie_type an output parameter for the IE type
279  *
280  * \retval 0 success
281  * \retval non-zero failure
282  * \since 1.6.1
283  */
284 int ast_event_str_to_ie_type(const char *str, enum ast_event_ie_type *ie_type);
285 
286 /*!
287  * \brief Get the size of an event
288  *
289  * \param event the event to get the size of
290  *
291  * \return the number of bytes contained in the event
292  * \since 1.6.1
293  */
294 size_t ast_event_get_size(const struct ast_event *event);
295 
296 /*!
297  * \brief Initialize an event iterator instance
298  *
299  * \param iterator The iterator instance to initialize
300  * \param event The event that will be iterated through
301  *
302  * \retval 0 Success, there are IEs available to iterate
303  * \retval -1 Failure, there are no IEs in the event to iterate
304  */
305 int ast_event_iterator_init(struct ast_event_iterator *iterator, const struct ast_event *event);
306 
307 /*!
308  * \brief Move iterator instance to next IE
309  *
310  * \param iterator The iterator instance
311  *
312  * \retval 0 on success
313  * \retval -1 if end is reached
314  */
315 int ast_event_iterator_next(struct ast_event_iterator *iterator);
316 
317 /*!
318  * \brief Get the type of the current IE in the iterator instance
319  *
320  * \param iterator The iterator instance
321  *
322  * \return the ie type as represented by one of the value sin the
323  * ast_event_ie_type enum
324  */
326 
327 /*!
328  * \brief Get the value of the current IE in the iterator as an integer payload
329  *
330  * \param iterator The iterator instance
331  *
332  * \return This returns the payload of the information element as a uint.
333  */
334 uint32_t ast_event_iterator_get_ie_uint(struct ast_event_iterator *iterator);
335 
336 /*!
337  * \brief Get the value of the current IE in the iterator as a string payload
338  *
339  * \param iterator The iterator instance
340  *
341  * \return This returns the payload of the information element as a string.
342  */
343 const char *ast_event_iterator_get_ie_str(struct ast_event_iterator *iterator);
344 
345 /*!
346  * \brief Get the minimum length of an ast_event.
347  *
348  * \return minimum amount of memory that will be consumed by any ast_event.
349  */
350 size_t ast_event_minimum_length(void);
351 
352 #if defined(__cplusplus) || defined(c_plusplus)
353 }
354 #endif
355 
356 #endif /* AST_EVENT_H */
An event.
Definition: event.c:81
int ast_event_str_to_ie_type(const char *str, enum ast_event_ie_type *ie_type)
Convert a string to an IE type.
enum ast_event_type ast_event_get_type(const struct ast_event *event)
Get the type for an event.
Definition: event.c:288
ast_event_ie_pltype
Payload types for event information elements.
Definition: event_defs.h:321
Definition: astman.c:222
int ast_event_append_ie_bitflags(struct ast_event **event, enum ast_event_ie_type ie_type, uint32_t bitflags)
Append an information element that has a bitflags payload.
Definition: event.c:367
enum ast_event_ie_pltype ast_event_get_ie_pltype(enum ast_event_ie_type ie_type)
Get the payload type for a given information element type.
Definition: event.c:218
supposed to be an opaque type
Definition: event_defs.h:352
ast_event_ie_type
Event Information Element types.
Definition: event_defs.h:68
ast_event_type
Definition: event_defs.h:28
Generic event system.
const void * ast_event_get_ie_raw(const struct ast_event *event, enum ast_event_ie_type ie_type)
Get the value of an information element that has a raw payload.
Definition: event.c:311
int ast_event_append_ie_raw(struct ast_event **event, enum ast_event_ie_type ie_type, const void *data, size_t data_len)
Append an information element that has a raw payload.
Definition: event.c:374
int ast_event_append_ie_str(struct ast_event **event, enum ast_event_ie_type ie_type, const char *str)
Append an information element that has a string payload.
Definition: event.c:345
size_t ast_event_minimum_length(void)
Get the minimum length of an ast_event.
Definition: event.c:529
uint32_t ast_event_get_ie_uint(const struct ast_event *event, enum ast_event_ie_type ie_type)
Get the value of an information element that has an integer payload.
Definition: event.c:293
int ast_event_iterator_init(struct ast_event_iterator *iterator, const struct ast_event *event)
Initialize an event iterator instance.
Definition: event.c:242
void ast_event_destroy(struct ast_event *event)
Destroy an event.
Definition: event.c:524
int ast_event_iterator_next(struct ast_event_iterator *iterator)
Move iterator instance to next IE.
Definition: event.c:258
struct ast_event * ast_event_new(enum ast_event_type event_type,...)
Create a new event.
Definition: event.c:402
uint32_t ast_event_iterator_get_ie_uint(struct ast_event_iterator *iterator)
Get the value of the current IE in the iterator as an integer payload.
Definition: event.c:269
int ast_event_append_eid(struct ast_event **event)
Append the global EID IE.
Definition: event.c:518
const char * ast_event_get_ie_type_name(enum ast_event_ie_type ie_type)
Get the string representation of an information element type.
Definition: event.c:208
const char * ast_event_iterator_get_ie_str(struct ast_event_iterator *iterator)
Get the value of the current IE in the iterator as a string payload.
Definition: event.c:274
size_t ast_event_get_size(const struct ast_event *event)
Get the size of an event.
Definition: event.c:228
const char * ast_event_get_type_name(const struct ast_event *event)
Get the string representation of the type of the given event.
Definition: event.c:194
const char * ast_event_get_ie_str(const struct ast_event *event, enum ast_event_ie_type ie_type)
Get the value of an information element that has a string payload.
Definition: event.c:302
enum ast_event_ie_type ast_event_iterator_get_ie_type(struct ast_event_iterator *iterator)
Get the type of the current IE in the iterator instance.
Definition: event.c:264
uint16_t ast_event_get_ie_raw_payload_len(const struct ast_event *event, enum ast_event_ie_type ie_type)
Get the length of the raw payload for a particular IE.
Definition: event.c:330
int ast_event_append_ie_uint(struct ast_event **event, enum ast_event_ie_type ie_type, uint32_t data)
Append an information element that has an integer payload.
Definition: event.c:360