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