src/libesl/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_SEND_INFO,
 113         ESL_EVENT_RECV_INFO,
 114         ESL_EVENT_ALL
 115 } esl_event_types_t;
 116
 117 typedef enum {
 118         ESL_PRIORITY_NORMAL,
 119         ESL_PRIORITY_LOW,
 120         ESL_PRIORITY_HIGH
 121 } esl_priority_t;
 122
 123 /*! \brief An event Header */
 124         struct esl_event_header {
 125         /*! the header name */
 126         char *name;
 127         /*! the header value */
 128         char *value;
 129         /*! hash of the header name */
 130         unsigned long hash;
 131         struct esl_event_header *next;
 132 };
 133
 134
 135 /*! \brief Representation of an event */
 136 struct esl_event {
 137         /*! the event id (descriptor) */
 138         esl_event_types_t event_id;
 139         /*! the priority of the event */
 140         esl_priority_t priority;
 141         /*! the owner of the event */
 142         char *owner;
 143         /*! the subclass of the event */
 144         char *subclass_name;
 145         /*! the event headers */
 146         esl_event_header_t *headers;
 147         /*! the event headers tail pointer */
 148         esl_event_header_t *last_header;
 149         /*! the body of the event */
 150         char *body;
 151         /*! user data from the subclass provider */
 152         void *bind_user_data;
 153         /*! user data from the event sender */
 154         void *event_user_data;
 155         /*! unique key */
 156         unsigned long key;
 157         struct esl_event *next;
 158 };
 159
 160
 161
 162 #define ESL_EVENT_SUBCLASS_ANY NULL
 163
 164 /*!
 165   \brief Create an event
 166   \param event a NULL pointer on which to create the event
 167   \param event_id the event id enumeration of the desired event
 168   \param subclass_name the subclass name for custom event (only valid when event_id is ESL_EVENT_CUSTOM)
 169   \return ESL_STATUS_SUCCESS on success
 170 */
 171 ESL_DECLARE(esl_status_t) esl_event_create_subclass(esl_event_t **event, esl_event_types_t event_id, const char *subclass_name);
 172
 173 /*!
 174   \brief Set the priority of an event
 175   \param event the event to set the priority on
 176   \param priority the event priority
 177   \return ESL_STATUS_SUCCESS
 178 */
 179 ESL_DECLARE(esl_status_t) esl_event_set_priority(esl_event_t *event, esl_priority_t priority);
 180
 181 /*!
 182   \brief Retrieve a header value from an event
 183   \param event the event to read the header from
 184   \param header_name the name of the header to read
 185   \return the value of the requested header
 186 */
 187 ESL_DECLARE(char *)esl_event_get_header(esl_event_t *event, const char *header_name);
 188
 189 /*!
 190   \brief Retrieve the body value from an event
 191   \param event the event to read the body from
 192   \return the value of the body or NULL
 193 */
 194 ESL_DECLARE(char *)esl_event_get_body(esl_event_t *event);
 195
 196 /*!
 197   \brief Add a header to an event
 198   \param event the event to add the header to
 199   \param stack the stack sense (stack it on the top or on the bottom)
 200   \param header_name the name of the header to add
 201   \param fmt the value of the header (varargs see standard sprintf family)
 202   \return ESL_STATUS_SUCCESS if the header was added
 203 */
 204 ESL_DECLARE(esl_status_t) esl_event_add_header(esl_event_t *event, esl_stack_t stack,
 205                                                                                            const char *header_name, const char *fmt, ...); //PRINTF_FUNCTION(4, 5);
 206
 207 /*!
 208   \brief Add a string header to an event
 209   \param event the event to add the header to
 210   \param stack the stack sense (stack it on the top or on the bottom)
 211   \param header_name the name of the header to add
 212   \param data the value of the header
 213   \return ESL_STATUS_SUCCESS if the header was added
 214 */
 215 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);
 216
 217 ESL_DECLARE(esl_status_t) esl_event_del_header(esl_event_t *event, const char *header_name);
 218
 219 /*!
 220   \brief Destroy an event
 221   \param event pointer to the pointer to event to destroy
 222 */
 223 ESL_DECLARE(void) esl_event_destroy(esl_event_t **event);
 224 #define esl_event_safe_destroy(_event) if (_event) esl_event_destroy(_event)
 225
 226 /*!
 227   \brief Duplicate an event
 228   \param event a NULL pointer on which to duplicate the event
 229   \param todup an event to duplicate
 230   \return ESL_STATUS_SUCCESS if the event was duplicated
 231 */
 232 ESL_DECLARE(esl_status_t) esl_event_dup(esl_event_t **event, esl_event_t *todup);
 233
 234 /*!
 235   \brief Render the name of an event id enumeration
 236   \param event the event id to render the name of
 237   \return the rendered name
 238 */
 239 ESL_DECLARE(const char *)esl_event_name(esl_event_types_t event);
 240
 241 /*!
 242   \brief return the event id that matches a given event name
 243   \param name the name of the event
 244   \param type the event id to return
 245   \return ESL_STATUS_SUCCESS if there was a match
 246 */
 247 ESL_DECLARE(esl_status_t) esl_name_event(const char *name, esl_event_types_t *type);
 248
 249 /*!
 250   \brief Render a string representation of an event sutable for printing or network transport
 251   \param event the event to render
 252   \param str a string pointer to point at the allocated data
 253   \param encode url encode the headers
 254   \return ESL_STATUS_SUCCESS if the operation was successful
 255   \note you must free the resulting string when you are finished with it
 256 */
 257 ESL_DECLARE(esl_status_t) esl_event_serialize(esl_event_t *event, char **str, esl_bool_t encode);
 258
 259 /*!
 260   \brief Add a body to an event
 261   \param event the event to add to body to
 262   \param fmt optional body of the event (varargs see standard sprintf family)
 263   \return ESL_STATUS_SUCCESS if the body was added to the event
 264   \note the body parameter can be shadowed by the esl_event_reserve_subclass_detailed function
 265 */
 266 ESL_DECLARE(esl_status_t) esl_event_add_body(esl_event_t *event, const char *fmt, ...);
 267
 268 /*!
 269   \brief Create a new event assuming it will not be custom event and therefore hiding the unused parameters
 270   \param event a NULL pointer on which to create the event
 271   \param id the event id enumeration of the desired event
 272   \return ESL_STATUS_SUCCESS on success
 273 */
 274 #define esl_event_create(event, id) esl_event_create_subclass(event, id, ESL_EVENT_SUBCLASS_ANY)
 275
 276 ESL_DECLARE(const char *)esl_priority_name(esl_priority_t priority);
 277
 278 ///\}
 279
 280 #ifdef __cplusplus
 281 }
 282 #endif /* defined(__cplusplus) */
 283
 284 #endif /* defined(ESL_EVENT_H) */
 285
 286 /* For Emacs:
 287  * Local Variables:
 288  * mode:c
 289  * indent-tabs-mode:t
 290  * tab-width:4
 291  * c-basic-offset:4
 292  * End:
 293  * For VIM:
 294  * vim:set softtabstop=4 shiftwidth=4 tabstop=4:
 295  */