res_corosync: Update module to work with Stasis (and compile)
[asterisk/asterisk.git] / include / asterisk / event.h
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 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  * \return Nothing
105  *
106  */
107 void ast_event_destroy(struct ast_event *event);
108
109 /*!
110  * \brief Append an information element that has a string payload
111  *
112  * \param event the event that the IE will be appended to
113  * \param ie_type the type of IE to append
114  * \param str The string for the payload of the IE
115  *
116  * \retval 0 success
117  * \retval -1 failure
118  *
119  * The pointer to the event will get updated with the new location for the event
120  * that now contains the appended information element.  If the re-allocation of
121  * the memory for this event fails, it will be set to NULL.
122  */
123 int ast_event_append_ie_str(struct ast_event **event, enum ast_event_ie_type ie_type,
124         const char *str);
125
126 /*!
127  * \brief Append an information element that has an integer payload
128  *
129  * \param event the event that the IE will be appended to
130  * \param ie_type the type of IE to append
131  * \param data The integer for the payload of the IE
132  *
133  * \retval 0 success
134  * \retval -1 failure
135  *
136  * The pointer to the event will get updated with the new location for the event
137  * that now contains the appended information element.  If the re-allocation of
138  * the memory for this event fails, it will be set to NULL.
139  */
140 int ast_event_append_ie_uint(struct ast_event **event, enum ast_event_ie_type ie_type,
141         uint32_t data);
142
143 /*!
144  * \brief Append an information element that has a bitflags payload
145  *
146  * \param event the event that the IE will be appended to
147  * \param ie_type the type of IE to append
148  * \param bitflags the flags that are the payload of the IE
149  *
150  * \retval 0 success
151  * \retval -1 failure
152  * \since 1.8
153  *
154  * The pointer to the event will get updated with the new location for the event
155  * that now contains the appended information element.  If the re-allocation of
156  * the memory for this event fails, it will be set to NULL.
157  */
158 int ast_event_append_ie_bitflags(struct ast_event **event, enum ast_event_ie_type ie_type,
159         uint32_t bitflags);
160
161 /*!
162  * \brief Append an information element that has a raw payload
163  *
164  * \param event the event that the IE will be appended to
165  * \param ie_type the type of IE to append
166  * \param data A pointer to the raw data for the payload of the IE
167  * \param data_len The amount of data to copy into the payload
168  *
169  * \retval 0 success
170  * \retval -1 failure
171  *
172  * The pointer to the event will get updated with the new location for the event
173  * that now contains the appended information element.  If the re-allocation of
174  * the memory for this event fails, it will be set to NULL.
175  */
176 int ast_event_append_ie_raw(struct ast_event **event, enum ast_event_ie_type ie_type,
177         const void *data, size_t data_len);
178
179 /*!
180  * \brief Append the global EID IE
181  *
182  * \param event the event to append IE to
183  *
184  * \note For ast_event_new() that includes IEs, this is done automatically
185  *       for you.
186  *
187  * \retval 0 success
188  * \retval -1 failure
189  */
190 int ast_event_append_eid(struct ast_event **event);
191
192 /*!
193  * \brief Get the value of an information element that has an integer payload
194  *
195  * \param event The event to get the IE from
196  * \param ie_type the type of information element to retrieve
197  *
198  * \return This returns the payload of the information element with the given type.
199  *         However, an IE with a payload of 0, and the case where no IE is found
200  *         yield the same return value.
201  */
202 uint32_t ast_event_get_ie_uint(const struct ast_event *event, enum ast_event_ie_type ie_type);
203
204 /*!
205  * \brief Get the value of an information element that has a string payload
206  *
207  * \param event The event to get the IE from
208  * \param ie_type the type of information element to retrieve
209  *
210  * \return This returns the payload of the information element with the given type.
211  *         If the information element isn't found, NULL will be returned.
212  */
213 const char *ast_event_get_ie_str(const struct ast_event *event, enum ast_event_ie_type ie_type);
214
215 /*!
216  * \brief Get the value of an information element that has a raw payload
217  *
218  * \param event The event to get the IE from
219  * \param ie_type the type of information element to retrieve
220  *
221  * \return This returns the payload of the information element with the given type.
222  *         If the information element isn't found, NULL will be returned.
223  */
224 const void *ast_event_get_ie_raw(const struct ast_event *event, enum ast_event_ie_type ie_type);
225
226 /*!
227  * \brief Get the length of the raw payload for a particular IE
228  *
229  * \param event The event to get the IE payload length from
230  * \param ie_type the type of information element to get the length of
231  *
232  * \return If an IE of type ie_type is found, its payload length is returned.
233  *         Otherwise, 0 is returned.
234  */
235 uint16_t ast_event_get_ie_raw_payload_len(const struct ast_event *event, enum ast_event_ie_type ie_type);
236
237 /*!
238  * \brief Get the string representation of the type of the given event
239  *
240  * \arg event the event to get the type of
241  *
242  * \return the string representation of the event type of the provided event
243  * \since 1.6.1
244  */
245 const char *ast_event_get_type_name(const struct ast_event *event);
246
247 /*!
248  * \brief Get the string representation of an information element type
249  *
250  * \param ie_type the information element type to get the string representation of
251  *
252  * \return the string representation of the information element type
253  * \since 1.6.1
254  */
255 const char *ast_event_get_ie_type_name(enum ast_event_ie_type ie_type);
256
257 /*!
258  * \brief Get the payload type for a given information element type
259  *
260  * \param ie_type the information element type to get the payload type of
261  *
262  * \return the payload type for the provided IE type
263  * \since 1.6.1
264  */
265 enum ast_event_ie_pltype ast_event_get_ie_pltype(enum ast_event_ie_type ie_type);
266
267 /*!
268  * \brief Get the type for an event
269  *
270  * \param event the event to get the type for
271  *
272  * \return the event type as represented by one of the values in the
273  *         ast_event_type enum
274  */
275 enum ast_event_type ast_event_get_type(const struct ast_event *event);
276
277 /*!
278  * \brief Convert a string to an IE type
279  *
280  * \param str the string to convert
281  * \param ie_type an output parameter for the IE type
282  *
283  * \retval 0 success
284  * \retval non-zero failure
285  * \since 1.6.1
286  */
287 int ast_event_str_to_ie_type(const char *str, enum ast_event_ie_type *ie_type);
288
289 /*!
290  * \brief Get the size of an event
291  *
292  * \param event the event to get the size of
293  *
294  * \return the number of bytes contained in the event
295  * \since 1.6.1
296  */
297 size_t ast_event_get_size(const struct ast_event *event);
298
299 /*!
300  * \brief Initialize an event iterator instance
301  *
302  * \param iterator The iterator instance to initialize
303  * \param event The event that will be iterated through
304  *
305  * \retval 0 Success, there are IEs available to iterate
306  * \retval -1 Failure, there are no IEs in the event to iterate
307  */
308 int ast_event_iterator_init(struct ast_event_iterator *iterator, const struct ast_event *event);
309
310 /*!
311  * \brief Move iterator instance to next IE
312  *
313  * \param iterator The iterator instance
314  *
315  * \retval 0 on success
316  * \retval -1 if end is reached
317  */
318 int ast_event_iterator_next(struct ast_event_iterator *iterator);
319
320 /*!
321  * \brief Get the type of the current IE in the iterator instance
322  *
323  * \param iterator The iterator instance
324  *
325  * \return the ie type as represented by one of the value sin the
326  *         ast_event_ie_type enum
327  */
328 enum ast_event_ie_type ast_event_iterator_get_ie_type(struct ast_event_iterator *iterator);
329
330 /*!
331  * \brief Get the value of the current IE in the iterator as an integer payload
332  *
333  * \param iterator The iterator instance
334  *
335  * \return This returns the payload of the information element as a uint.
336  */
337 uint32_t ast_event_iterator_get_ie_uint(struct ast_event_iterator *iterator);
338
339 /*!
340  * \brief Get the value of the current IE in the iterator as a string payload
341  *
342  * \param iterator The iterator instance
343  *
344  * \return This returns the payload of the information element as a string.
345  */
346 const char *ast_event_iterator_get_ie_str(struct ast_event_iterator *iterator);
347
348 /*!
349  * \brief Get the minimum length of an ast_event.
350  *
351  * \return minimum amount of memory that will be consumed by any ast_event.
352  */
353 size_t ast_event_minimum_length(void);
354
355 #if defined(__cplusplus) || defined(c_plusplus)
356 }
357 #endif
358
359 #endif /* AST_EVENT_H */