src/esl_event.h

   1 /*
   2  * Copyright (c) 2007, Anthony Minessale II
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  *
   9  * * Redistributions of source code must retain the above copyright
  10  * notice, this list of conditions and the following disclaimer.
  11  *
  12  * * Redistributions in binary form must reproduce the above copyright
  13  * notice, this list of conditions and the following disclaimer in the
  14  * documentation and/or other materials provided with the distribution.
  15  *
  16  * * Neither the name of the original author; nor the names of any contributors
  17  * may be used to endorse or promote products derived from this software
  18  * without specific prior written permission.
  19  *
  20  *
  21  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  22  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  23  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  24  * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER
  25  * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  26  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  27  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  28  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  29  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  30  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  31  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32  */
  33
  34 #ifndef ESL_EVENT_H
  35 #define ESL_EVENT_H
  36
  37 #include <esl.h>
  38
  39 #ifdef __cplusplus
  40 extern "C" {
  41 #endif /* defined(__cplusplus) */
  42
  43 typedef enum {
  44         ESL_STACK_BOTTOM,
  45         ESL_STACK_TOP
  46 } esl_stack_t;
  47
  48 typedef enum {
  49         ESL_EVENT_CUSTOM,
  50         ESL_EVENT_CLONE,
  51         ESL_EVENT_CHANNEL_CREATE,
  52         ESL_EVENT_CHANNEL_DESTROY,
  53         ESL_EVENT_CHANNEL_STATE,
  54         ESL_EVENT_CHANNEL_ANSWER,
  55         ESL_EVENT_CHANNEL_HANGUP,
  56         ESL_EVENT_CHANNEL_EXECUTE,
  57         ESL_EVENT_CHANNEL_EXECUTE_COMPLETE,
  58         ESL_EVENT_CHANNEL_BRIDGE,
  59         ESL_EVENT_CHANNEL_UNBRIDGE,
  60         ESL_EVENT_CHANNEL_PROGRESS,
  61         ESL_EVENT_CHANNEL_PROGRESS_MEDIA,
  62         ESL_EVENT_CHANNEL_OUTGOING,
  63         ESL_EVENT_CHANNEL_PARK,
  64         ESL_EVENT_CHANNEL_UNPARK,
  65         ESL_EVENT_CHANNEL_APPLICATION,
  66         ESL_EVENT_CHANNEL_ORIGINATE,
  67         ESL_EVENT_CHANNEL_UUID,
  68         ESL_EVENT_API,
  69         ESL_EVENT_LOG,
  70         ESL_EVENT_INBOUND_CHAN,
  71         ESL_EVENT_OUTBOUND_CHAN,
  72         ESL_EVENT_STARTUP,
  73         ESL_EVENT_SHUTDOWN,
  74         ESL_EVENT_PUBLISH,
  75         ESL_EVENT_UNPUBLISH,
  76         ESL_EVENT_TALK,
  77         ESL_EVENT_NOTALK,
  78         ESL_EVENT_SESSION_CRASH,
  79         ESL_EVENT_MODULE_LOAD,
  80         ESL_EVENT_MODULE_UNLOAD,
  81         ESL_EVENT_DTMF,
  82         ESL_EVENT_MESSAGE,
  83         ESL_EVENT_PRESENCE_IN,
  84         ESL_EVENT_NOTIFY_IN,
  85         ESL_EVENT_PRESENCE_OUT,
  86         ESL_EVENT_PRESENCE_PROBE,
  87         ESL_EVENT_MESSAGE_WAITING,
  88         ESL_EVENT_MESSAGE_QUERY,
  89         ESL_EVENT_ROSTER,
  90         ESL_EVENT_CODEC,
  91         ESL_EVENT_BACKGROUND_JOB,
  92         ESL_EVENT_DETECTED_SPEECH,
  93         ESL_EVENT_DETECTED_TONE,
  94         ESL_EVENT_PRIVATE_COMMAND,
  95         ESL_EVENT_HEARTBEAT,
  96         ESL_EVENT_TRAP,
  97         ESL_EVENT_ADD_SCHEDULE,
  98         ESL_EVENT_DEL_SCHEDULE,
  99         ESL_EVENT_EXE_SCHEDULE,
 100         ESL_EVENT_RE_SCHEDULE,
 101         ESL_EVENT_RELOADXML,
 102         ESL_EVENT_NOTIFY,
 103         ESL_EVENT_SEND_MESSAGE,
 104         ESL_EVENT_RECV_MESSAGE,
 105         ESL_EVENT_REQUEST_PARAMS,
 106         ESL_EVENT_CHANNEL_DATA,
 107         ESL_EVENT_GENERAL,
 108         ESL_EVENT_COMMAND,
 109         ESL_EVENT_SESSION_HEARTBEAT,
 110         ESL_EVENT_CLIENT_DISCONNECTED,
 111         ESL_EVENT_SERVER_DISCONNECTED,
 112         ESL_EVENT_ALL
 113 } esl_event_types_t;
 114
 115 typedef enum {
 116         ESL_PRIORITY_NORMAL,
 117         ESL_PRIORITY_LOW,
 118         ESL_PRIORITY_HIGH
 119 } esl_priority_t;
 120
 121 /*! \brief An event Header */
 122         struct esl_event_header {
 123         /*! the header name */
 124         char *name;
 125         /*! the header value */
 126         char *value;
 127         /*! hash of the header name */
 128         unsigned long hash;
 129         struct esl_event_header *next;
 130 };
 131
 132
 133 /*! \brief Representation of an event */
 134 struct esl_event {
 135         /*! the event id (descriptor) */
 136         esl_event_types_t event_id;
 137         /*! the priority of the event */
 138         esl_priority_t priority;
 139         /*! the owner of the event */
 140         char *owner;
 141         /*! the subclass of the event */
 142         char *subclass_name;
 143         /*! the event headers */
 144         esl_event_header_t *headers;
 145         /*! the event headers tail pointer */
 146         esl_event_header_t *last_header;
 147         /*! the body of the event */
 148         char *body;
 149         /*! user data from the subclass provider */
 150         void *bind_user_data;
 151         /*! user data from the event sender */
 152         void *event_user_data;
 153         /*! unique key */
 154         unsigned long key;
 155         struct esl_event *next;
 156 };
 157
 158
 159
 160 #define ESL_EVENT_SUBCLASS_ANY NULL
 161
 162 /*!
 163   \brief Create an event
 164   \param event a NULL pointer on which to create the event
 165   \param event_id the event id enumeration of the desired event
 166   \param subclass_name the subclass name for custom event (only valid when event_id is ESL_EVENT_CUSTOM)
 167   \return ESL_STATUS_SUCCESS on success
 168 */
 169 ESL_DECLARE(esl_status_t) esl_event_create_subclass(esl_event_t **event, esl_event_types_t event_id, const char *subclass_name);
 170
 171 /*!
 172   \brief Set the priority of an event
 173   \param event the event to set the priority on
 174   \param priority the event priority
 175   \return ESL_STATUS_SUCCESS
 176 */
 177 ESL_DECLARE(esl_status_t) esl_event_set_priority(esl_event_t *event, esl_priority_t priority);
 178
 179 /*!
 180   \brief Retrieve a header value from an event
 181   \param event the event to read the header from
 182   \param header_name the name of the header to read
 183   \return the value of the requested header
 184 */
 185 ESL_DECLARE(char *)esl_event_get_header(esl_event_t *event, const char *header_name);
 186
 187 /*!
 188   \brief Retrieve the body value from an event
 189   \param event the event to read the body from
 190   \return the value of the body or NULL
 191 */
 192 ESL_DECLARE(char *)esl_event_get_body(esl_event_t *event);
 193
 194 /*!
 195   \brief Add a header to an event
 196   \param event the event to add the header to
 197   \param stack the stack sense (stack it on the top or on the bottom)
 198   \param header_name the name of the header to add
 199   \param fmt the value of the header (varargs see standard sprintf family)
 200   \return ESL_STATUS_SUCCESS if the header was added
 201 */
 202 ESL_DECLARE(esl_status_t) esl_event_add_header(esl_event_t *event, esl_stack_t stack,
 203                                                                                            const char *header_name, const char *fmt, ...); //PRINTF_FUNCTION(4, 5);
 204
 205 /*!
 206   \brief Add a string header to an event
 207   \param event the event to add the header to
 208   \param stack the stack sense (stack it on the top or on the bottom)
 209   \param header_name the name of the header to add
 210   \param data the value of the header
 211   \return ESL_STATUS_SUCCESS if the header was added
 212 */
 213 ESL_DECLARE(esl_status_t) esl_event_add_header_string(esl_event_t *event, esl_stack_t stack, const char *header_name, const char *data);
 214
 215 ESL_DECLARE(esl_status_t) esl_event_del_header(esl_event_t *event, const char *header_name);
 216
 217 /*!
 218   \brief Destroy an event
 219   \param event pointer to the pointer to event to destroy
 220 */
 221 ESL_DECLARE(void) esl_event_destroy(esl_event_t **event);
 222 #define esl_event_safe_destroy(_event) if (_event) esl_event_destroy(_event)
 223
 224 /*!
 225   \brief Duplicate an event
 226   \param event a NULL pointer on which to duplicate the event
 227   \param todup an event to duplicate
 228   \return ESL_STATUS_SUCCESS if the event was duplicated
 229 */
 230 ESL_DECLARE(esl_status_t) esl_event_dup(esl_event_t **event, esl_event_t *todup);
 231
 232 /*!
 233   \brief Render the name of an event id enumeration
 234   \param event the event id to render the name of
 235   \return the rendered name
 236 */
 237 ESL_DECLARE(const char *)esl_event_name(esl_event_types_t event);
 238
 239 /*!
 240   \brief return the event id that matches a given event name
 241   \param name the name of the event
 242   \param type the event id to return
 243   \return ESL_STATUS_SUCCESS if there was a match
 244 */
 245 ESL_DECLARE(esl_status_t) esl_name_event(const char *name, esl_event_types_t *type);
 246
 247 /*!
 248   \brief Render a string representation of an event sutable for printing or network transport
 249   \param event the event to render
 250   \param str a string pointer to point at the allocated data
 251   \param encode url encode the headers
 252   \return ESL_STATUS_SUCCESS if the operation was successful
 253   \note you must free the resulting string when you are finished with it
 254 */
 255 ESL_DECLARE(esl_status_t) esl_event_serialize(esl_event_t *event, char **str, esl_bool_t encode);
 256
 257 /*!
 258   \brief Add a body to an event
 259   \param event the event to add to body to
 260   \param fmt optional body of the event (varargs see standard sprintf family)
 261   \return ESL_STATUS_SUCCESS if the body was added to the event
 262   \note the body parameter can be shadowed by the esl_event_reserve_subclass_detailed function
 263 */
 264 ESL_DECLARE(esl_status_t) esl_event_add_body(esl_event_t *event, const char *fmt, ...);
 265
 266 /*!
 267   \brief Create a new event assuming it will not be custom event and therefore hiding the unused parameters
 268   \param event a NULL pointer on which to create the event
 269   \param id the event id enumeration of the desired event
 270   \return ESL_STATUS_SUCCESS on success
 271 */
 272 #define esl_event_create(event, id) esl_event_create_subclass(event, id, ESL_EVENT_SUBCLASS_ANY)
 273
 274 ESL_DECLARE(const char *)esl_priority_name(esl_priority_t priority);
 275
 276 ///\}
 277
 278 #ifdef __cplusplus
 279 }
 280 #endif /* defined(__cplusplus) */
 281
 282 #endif /* defined(ESL_EVENT_H) */
 283
 284 /* For Emacs:
 285  * Local Variables:
 286  * mode:c
 287  * indent-tabs-mode:t
 288  * tab-width:4
 289  * c-basic-offset:4
 290  * End:
 291  * For VIM:
 292  * vim:set softtabstop=4 shiftwidth=4 tabstop=4:
 293  */