Refactor CEL to avoid using the event system core
[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  * The purpose of this API is to provide a generic way to share events between
29  * Asterisk modules.  Code can generate events, and other code can subscribe to
30  * them.
31  *
32  * Events have an associated event type, as well as information elements.  The
33  * information elements are the meta data that go along with each event.  For
34  * example, in the case of message waiting indication, the event type is MWI,
35  * and each MWI event contains at least three information elements: the
36  * mailbox, the number of new messages, and the number of old messages.
37  *
38  * Subscriptions to events consist of an event type and information elements,
39  * as well.  Subscriptions can be to all events, or a certain subset of events.
40  * If an event type is provided, only events of that type will be sent to this
41  * subscriber.  Furthermore, if information elements are supplied with the
42  * subscription, only events that contain the specified information elements
43  * with specified values will be sent to the subscriber.  For example, when a
44  * SIP phone subscribes to MWI for mailbox 1234, then chan_sip can subscribe
45  * to internal Asterisk MWI events with the MAILBOX information element with
46  * a value of "1234".
47  *
48  * Another key feature of this event system is the ability to cache events.
49  * It is useful for some types of events to be able to remember the last known
50  * value.  These are usually events that indicate some kind of state change.
51  * In the example of MWI, app_voicemail can instruct the event core to cache
52  * these events based on the mailbox.  So, the last known MWI state of each
53  * mailbox will be cached, and other modules can retrieve this information
54  * on demand without having to poll the mailbox directly.
55  */
56
57 #ifndef AST_EVENT_H
58 #define AST_EVENT_H
59
60 #if defined(__cplusplus) || defined(c_plusplus)
61 extern "C" {
62 #endif
63
64 #include "asterisk/event_defs.h"
65
66 /*!
67  * \brief Create a new event
68  *
69  * \param event_type The type of event to create
70  *
71  * The rest of the arguments to this function specify information elements to
72  * add to the event.  They are specified in the form:
73  * \code
74  *    <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ]
75  * \endcode
76  * and must end with AST_EVENT_IE_END.
77  *
78  * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed
79  * by a valid IE payload type.  A payload must also be specified
80  * after the IE payload type.
81  *
82  * \note The EID IE will be appended automatically when this function is used
83  *       with at least one IE specified.
84  *
85  * \return This returns the event that has been created.  If there is an error
86  *         creating the event, NULL will be returned.
87  *
88  * Example usage:
89  *
90  * \code
91  * if (!(event = ast_event_new(AST_EVENT_MWI,
92  *     AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, mailbox,
93  *     AST_EVENT_IE_NEWMSGS, AST_EVENT_IE_PLTYPE_UINT, new,
94  *     AST_EVENT_IE_OLDMSGS, AST_EVENT_IE_PLTYPE_UINT, old,
95  *     AST_EVENT_IE_END))) {
96  *       return;
97  * }
98  * \endcode
99  *
100  * This creates a MWI event with 3 information elements, a mailbox which is
101  * a string, and the number of new and old messages, specified as integers.
102  */
103 struct ast_event *ast_event_new(enum ast_event_type event_type, ...);
104
105 /*!
106  * \brief Destroy an event
107  *
108  * \param event the event to destroy
109  *
110  * \return Nothing
111  *
112  * \note Events that have been queued should *not* be destroyed by the code that
113  *       created the event.  It will be automatically destroyed after being
114  *       dispatched to the appropriate subscribers.
115  */
116 void ast_event_destroy(struct ast_event *event);
117
118 /*!
119  * \brief Append an information element that has a string payload
120  *
121  * \param event the event that the IE will be appended to
122  * \param ie_type the type of IE to append
123  * \param str The string for the payload of the IE
124  *
125  * \retval 0 success
126  * \retval -1 failure
127  *
128  * The pointer to the event will get updated with the new location for the event
129  * that now contains the appended information element.  If the re-allocation of
130  * the memory for this event fails, it will be set to NULL.
131  */
132 int ast_event_append_ie_str(struct ast_event **event, enum ast_event_ie_type ie_type,
133         const char *str);
134
135 /*!
136  * \brief Append an information element that has an integer payload
137  *
138  * \param event the event that the IE will be appended to
139  * \param ie_type the type of IE to append
140  * \param data The integer for the payload of the IE
141  *
142  * \retval 0 success
143  * \retval -1 failure
144  *
145  * The pointer to the event will get updated with the new location for the event
146  * that now contains the appended information element.  If the re-allocation of
147  * the memory for this event fails, it will be set to NULL.
148  */
149 int ast_event_append_ie_uint(struct ast_event **event, enum ast_event_ie_type ie_type,
150         uint32_t data);
151
152 /*!
153  * \brief Get the value of an information element that has an integer payload
154  *
155  * \param event The event to get the IE from
156  * \param ie_type the type of information element to retrieve
157  *
158  * \return This returns the payload of the information element with the given type.
159  *         However, an IE with a payload of 0, and the case where no IE is found
160  *         yield the same return value.
161  */
162 uint32_t ast_event_get_ie_uint(const struct ast_event *event, enum ast_event_ie_type ie_type);
163
164 /*!
165  * \brief Get the value of an information element that has a string payload
166  *
167  * \param event The event to get the IE from
168  * \param ie_type the type of information element to retrieve
169  *
170  * \return This returns the payload of the information element with the given type.
171  *         If the information element isn't found, NULL will be returned.
172  */
173 const char *ast_event_get_ie_str(const struct ast_event *event, enum ast_event_ie_type ie_type);
174
175 /*!
176  * \brief Get the string representation of an information element type
177  *
178  * \param ie_type the information element type to get the string representation of
179  *
180  * \return the string representation of the information element type
181  * \since 1.6.1
182  */
183 const char *ast_event_get_ie_type_name(enum ast_event_ie_type ie_type);
184
185 /*!
186  * \brief Get the payload type for a given information element type
187  *
188  * \param ie_type the information element type to get the payload type of
189  *
190  * \return the payload type for the provided IE type
191  * \since 1.6.1
192  */
193 enum ast_event_ie_pltype ast_event_get_ie_pltype(enum ast_event_ie_type ie_type);
194
195 /*!
196  * \brief Get the type for an event
197  *
198  * \param event the event to get the type for
199  *
200  * \return the event type as represented by one of the values in the
201  *         ast_event_type enum
202  */
203 enum ast_event_type ast_event_get_type(const struct ast_event *event);
204
205 /*!
206  * \brief Convert a string to an IE type
207  *
208  * \param str the string to convert
209  * \param ie_type an output parameter for the IE type
210  *
211  * \retval 0 success
212  * \retval non-zero failure
213  * \since 1.6.1
214  */
215 int ast_event_str_to_ie_type(const char *str, enum ast_event_ie_type *ie_type);
216
217 /*!
218  * \brief Get the size of an event
219  *
220  * \param event the event to get the size of
221  *
222  * \return the number of bytes contained in the event
223  * \since 1.6.1
224  */
225 size_t ast_event_get_size(const struct ast_event *event);
226
227 /*!
228  * \brief Initialize an event iterator instance
229  *
230  * \param iterator The iterator instance to initialize
231  * \param event The event that will be iterated through
232  *
233  * \retval 0 Success, there are IEs available to iterate
234  * \retval -1 Failure, there are no IEs in the event to iterate
235  */
236 int ast_event_iterator_init(struct ast_event_iterator *iterator, const struct ast_event *event);
237
238 /*!
239  * \brief Move iterator instance to next IE
240  *
241  * \param iterator The iterator instance
242  *
243  * \retval 0 on success
244  * \retval -1 if end is reached
245  */
246 int ast_event_iterator_next(struct ast_event_iterator *iterator);
247
248 /*!
249  * \brief Get the type of the current IE in the iterator instance
250  *
251  * \param iterator The iterator instance
252  *
253  * \return the ie type as represented by one of the value sin the
254  *         ast_event_ie_type enum
255  */
256 enum ast_event_ie_type ast_event_iterator_get_ie_type(struct ast_event_iterator *iterator);
257
258 /*!
259  * \brief Get the value of the current IE in the iterator as an integer payload
260  *
261  * \param iterator The iterator instance
262  *
263  * \return This returns the payload of the information element as a uint.
264  */
265 uint32_t ast_event_iterator_get_ie_uint(struct ast_event_iterator *iterator);
266
267 /*!
268  * \brief Get the value of the current IE in the iterator as a string payload
269  *
270  * \param iterator The iterator instance
271  *
272  * \return This returns the payload of the information element as a string.
273  */
274 const char *ast_event_iterator_get_ie_str(struct ast_event_iterator *iterator);
275
276 #if defined(__cplusplus) || defined(c_plusplus)
277 }
278 #endif
279
280 #endif /* AST_EVENT_H */