event.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 2007 - 2008, Digium, Inc.
00005  *
00006  * Russell Bryant <russell@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 /*!
00020  * \file
00021  * \author Russell Bryant <russell@digium.com>
00022  * \ref AstGenericEvents
00023  */
00024 
00025 /*!
00026  * \page AstGenericEvents Generic event system
00027  *
00028  * Prior to the creation of \ref stasis, the purpose of this API was to provide
00029  * a generic way to share events between Asterisk modules. Once there was a need
00030  * to disseminate data whose definition was provided by the producers/consumers,
00031  * it was no longer possible to use the binary representation in the generic
00032  * event system.
00033  *
00034  * That aside, the generic event system is still useful and used by several
00035  * modules in Asterisk.
00036  *  - CEL uses the \ref ast_event representation to pass information to registered
00037  *    backends.
00038  *  - The \file res_corosync module publishes \ref ast_event representations of
00039  *    information to other Asterisk instances in a cluster.
00040  *  - Security event represent their event types and data using this system.
00041  *  - Theoretically, any \ref stasis message can use this system to pass
00042  *    information around in a binary format.
00043  *
00044  * Events have an associated event type, as well as information elements.  The
00045  * information elements are the meta data that go along with each event.  For
00046  * example, in the case of message waiting indication, the event type is MWI,
00047  * and each MWI event contains at least three information elements: the
00048  * mailbox, the number of new messages, and the number of old messages.
00049  */
00050 
00051 #ifndef AST_EVENT_H
00052 #define AST_EVENT_H
00053 
00054 #if defined(__cplusplus) || defined(c_plusplus)
00055 extern "C" {
00056 #endif
00057 
00058 #include "asterisk/event_defs.h"
00059 
00060 /*!
00061  * \brief Create a new event
00062  *
00063  * \param event_type The type of event to create
00064  *
00065  * The rest of the arguments to this function specify information elements to
00066  * add to the event.  They are specified in the form:
00067  * \code
00068  *    <enum ast_event_ie_type>, [enum ast_event_ie_pltype, [payload] ]
00069  * \endcode
00070  * and must end with AST_EVENT_IE_END.
00071  *
00072  * If the ie_type specified is *not* AST_EVENT_IE_END, then it must be followed
00073  * by a valid IE payload type.  A payload must also be specified
00074  * after the IE payload type.
00075  *
00076  * \note The EID IE will be appended automatically when this function is used
00077  *       with at least one IE specified.
00078  *
00079  * \return This returns the event that has been created.  If there is an error
00080  *         creating the event, NULL will be returned.
00081  *
00082  * Example usage:
00083  *
00084  * \code
00085  * if (!(event = ast_event_new(AST_EVENT_MWI,
00086  *     AST_EVENT_IE_MAILBOX, AST_EVENT_IE_PLTYPE_STR, mailbox,
00087  *     AST_EVENT_IE_NEWMSGS, AST_EVENT_IE_PLTYPE_UINT, new,
00088  *     AST_EVENT_IE_OLDMSGS, AST_EVENT_IE_PLTYPE_UINT, old,
00089  *     AST_EVENT_IE_END))) {
00090  *       return;
00091  * }
00092  * \endcode
00093  *
00094  * This creates a MWI event with 3 information elements, a mailbox which is
00095  * a string, and the number of new and old messages, specified as integers.
00096  */
00097 struct ast_event *ast_event_new(enum ast_event_type event_type, ...);
00098 
00099 /*!
00100  * \brief Destroy an event
00101  *
00102  * \param event the event to destroy
00103  *
00104  * \return Nothing
00105  *
00106  */
00107 void ast_event_destroy(struct ast_event *event);
00108 
00109 /*!
00110  * \brief Append an information element that has a string payload
00111  *
00112  * \param event the event that the IE will be appended to
00113  * \param ie_type the type of IE to append
00114  * \param str The string for the payload of the IE
00115  *
00116  * \retval 0 success
00117  * \retval -1 failure
00118  *
00119  * The pointer to the event will get updated with the new location for the event
00120  * that now contains the appended information element.  If the re-allocation of
00121  * the memory for this event fails, it will be set to NULL.
00122  */
00123 int ast_event_append_ie_str(struct ast_event **event, enum ast_event_ie_type ie_type,
00124    const char *str);
00125 
00126 /*!
00127  * \brief Append an information element that has an integer payload
00128  *
00129  * \param event the event that the IE will be appended to
00130  * \param ie_type the type of IE to append
00131  * \param data The integer for the payload of the IE
00132  *
00133  * \retval 0 success
00134  * \retval -1 failure
00135  *
00136  * The pointer to the event will get updated with the new location for the event
00137  * that now contains the appended information element.  If the re-allocation of
00138  * the memory for this event fails, it will be set to NULL.
00139  */
00140 int ast_event_append_ie_uint(struct ast_event **event, enum ast_event_ie_type ie_type,
00141    uint32_t data);
00142 
00143 /*!
00144  * \brief Append an information element that has a bitflags payload
00145  *
00146  * \param event the event that the IE will be appended to
00147  * \param ie_type the type of IE to append
00148  * \param bitflags the flags that are the payload of the IE
00149  *
00150  * \retval 0 success
00151  * \retval -1 failure
00152  * \since 1.8
00153  *
00154  * The pointer to the event will get updated with the new location for the event
00155  * that now contains the appended information element.  If the re-allocation of
00156  * the memory for this event fails, it will be set to NULL.
00157  */
00158 int ast_event_append_ie_bitflags(struct ast_event **event, enum ast_event_ie_type ie_type,
00159    uint32_t bitflags);
00160 
00161 /*!
00162  * \brief Append an information element that has a raw payload
00163  *
00164  * \param event the event that the IE will be appended to
00165  * \param ie_type the type of IE to append
00166  * \param data A pointer to the raw data for the payload of the IE
00167  * \param data_len The amount of data to copy into the payload
00168  *
00169  * \retval 0 success
00170  * \retval -1 failure
00171  *
00172  * The pointer to the event will get updated with the new location for the event
00173  * that now contains the appended information element.  If the re-allocation of
00174  * the memory for this event fails, it will be set to NULL.
00175  */
00176 int ast_event_append_ie_raw(struct ast_event **event, enum ast_event_ie_type ie_type,
00177    const void *data, size_t data_len);
00178 
00179 /*!
00180  * \brief Append the global EID IE
00181  *
00182  * \param event the event to append IE to
00183  *
00184  * \note For ast_event_new() that includes IEs, this is done automatically
00185  *       for you.
00186  *
00187  * \retval 0 success
00188  * \retval -1 failure
00189  */
00190 int ast_event_append_eid(struct ast_event **event);
00191 
00192 /*!
00193  * \brief Get the value of an information element that has an integer payload
00194  *
00195  * \param event The event to get the IE from
00196  * \param ie_type the type of information element to retrieve
00197  *
00198  * \return This returns the payload of the information element with the given type.
00199  *         However, an IE with a payload of 0, and the case where no IE is found
00200  *         yield the same return value.
00201  */
00202 uint32_t ast_event_get_ie_uint(const struct ast_event *event, enum ast_event_ie_type ie_type);
00203 
00204 /*!
00205  * \brief Get the value of an information element that has a string payload
00206  *
00207  * \param event The event to get the IE from
00208  * \param ie_type the type of information element to retrieve
00209  *
00210  * \return This returns the payload of the information element with the given type.
00211  *         If the information element isn't found, NULL will be returned.
00212  */
00213 const char *ast_event_get_ie_str(const struct ast_event *event, enum ast_event_ie_type ie_type);
00214 
00215 /*!
00216  * \brief Get the value of an information element that has a raw payload
00217  *
00218  * \param event The event to get the IE from
00219  * \param ie_type the type of information element to retrieve
00220  *
00221  * \return This returns the payload of the information element with the given type.
00222  *         If the information element isn't found, NULL will be returned.
00223  */
00224 const void *ast_event_get_ie_raw(const struct ast_event *event, enum ast_event_ie_type ie_type);
00225 
00226 /*!
00227  * \brief Get the length of the raw payload for a particular IE
00228  *
00229  * \param event The event to get the IE payload length from
00230  * \param ie_type the type of information element to get the length of
00231  *
00232  * \return If an IE of type ie_type is found, its payload length is returned.
00233  *         Otherwise, 0 is returned.
00234  */
00235 uint16_t ast_event_get_ie_raw_payload_len(const struct ast_event *event, enum ast_event_ie_type ie_type);
00236 
00237 /*!
00238  * \brief Get the string representation of the type of the given event
00239  *
00240  * \arg event the event to get the type of
00241  *
00242  * \return the string representation of the event type of the provided event
00243  * \since 1.6.1
00244  */
00245 const char *ast_event_get_type_name(const struct ast_event *event);
00246 
00247 /*!
00248  * \brief Get the string representation of an information element type
00249  *
00250  * \param ie_type the information element type to get the string representation of
00251  *
00252  * \return the string representation of the information element type
00253  * \since 1.6.1
00254  */
00255 const char *ast_event_get_ie_type_name(enum ast_event_ie_type ie_type);
00256 
00257 /*!
00258  * \brief Get the payload type for a given information element type
00259  *
00260  * \param ie_type the information element type to get the payload type of
00261  *
00262  * \return the payload type for the provided IE type
00263  * \since 1.6.1
00264  */
00265 enum ast_event_ie_pltype ast_event_get_ie_pltype(enum ast_event_ie_type ie_type);
00266 
00267 /*!
00268  * \brief Get the type for an event
00269  *
00270  * \param event the event to get the type for
00271  *
00272  * \return the event type as represented by one of the values in the
00273  *         ast_event_type enum
00274  */
00275 enum ast_event_type ast_event_get_type(const struct ast_event *event);
00276 
00277 /*!
00278  * \brief Convert a string to an IE type
00279  *
00280  * \param str the string to convert
00281  * \param ie_type an output parameter for the IE type
00282  *
00283  * \retval 0 success
00284  * \retval non-zero failure
00285  * \since 1.6.1
00286  */
00287 int ast_event_str_to_ie_type(const char *str, enum ast_event_ie_type *ie_type);
00288 
00289 /*!
00290  * \brief Get the size of an event
00291  *
00292  * \param event the event to get the size of
00293  *
00294  * \return the number of bytes contained in the event
00295  * \since 1.6.1
00296  */
00297 size_t ast_event_get_size(const struct ast_event *event);
00298 
00299 /*!
00300  * \brief Initialize an event iterator instance
00301  *
00302  * \param iterator The iterator instance to initialize
00303  * \param event The event that will be iterated through
00304  *
00305  * \retval 0 Success, there are IEs available to iterate
00306  * \retval -1 Failure, there are no IEs in the event to iterate
00307  */
00308 int ast_event_iterator_init(struct ast_event_iterator *iterator, const struct ast_event *event);
00309 
00310 /*!
00311  * \brief Move iterator instance to next IE
00312  *
00313  * \param iterator The iterator instance
00314  *
00315  * \retval 0 on success
00316  * \retval -1 if end is reached
00317  */
00318 int ast_event_iterator_next(struct ast_event_iterator *iterator);
00319 
00320 /*!
00321  * \brief Get the type of the current IE in the iterator instance
00322  *
00323  * \param iterator The iterator instance
00324  *
00325  * \return the ie type as represented by one of the value sin the
00326  *         ast_event_ie_type enum
00327  */
00328 enum ast_event_ie_type ast_event_iterator_get_ie_type(struct ast_event_iterator *iterator);
00329 
00330 /*!
00331  * \brief Get the value of the current IE in the iterator as an integer payload
00332  *
00333  * \param iterator The iterator instance
00334  *
00335  * \return This returns the payload of the information element as a uint.
00336  */
00337 uint32_t ast_event_iterator_get_ie_uint(struct ast_event_iterator *iterator);
00338 
00339 /*!
00340  * \brief Get the value of the current IE in the iterator as a string payload
00341  *
00342  * \param iterator The iterator instance
00343  *
00344  * \return This returns the payload of the information element as a string.
00345  */
00346 const char *ast_event_iterator_get_ie_str(struct ast_event_iterator *iterator);
00347 
00348 /*!
00349  * \brief Get the minimum length of an ast_event.
00350  *
00351  * \return minimum amount of memory that will be consumed by any ast_event.
00352  */
00353 size_t ast_event_minimum_length(void);
00354 
00355 #if defined(__cplusplus) || defined(c_plusplus)
00356 }
00357 #endif
00358 
00359 #endif /* AST_EVENT_H */

Generated on Thu Apr 16 06:27:33 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6