include/asterisk/cel.h

   1 /*
   2  * Asterisk -- An open source telephony toolkit.
   3  *
   4  * Copyright (C) 2008 - 2009, Digium, Inc.
   5  *
   6  * See http://www.asterisk.org for more information about
   7  * the Asterisk project. Please do not directly contact
   8  * any of the maintainers of this project for assistance;
   9  * the project provides a web site, mailing lists and IRC
  10  * channels for your use.
  11  *
  12  * This program is free software, distributed under the terms of
  13  * the GNU General Public License Version 2. See the LICENSE file
  14  * at the top of the source tree.
  15  */
  16
  17 /*!
  18  * \file
  19  * \brief Call Event Logging API
  20  *
  21  * \todo TODO: There some event types that have been defined here, but are not
  22  *       yet used anywhere in the code. It would be really awesome if someone
  23  *       went through and had Asterisk generate these events where it is
  24  *       appropriate to do so. The defined, but unused events are:
  25  *       CONF_ENTER, CONF_EXIT, CONF_START, CONF_END, 3WAY_START, 3WAY_END,
  26  *       TRANSFER, and HOOKFLASH.
  27  */
  28
  29 #ifndef __AST_CEL_H__
  30 #define __AST_CEL_H__
  31
  32 #if defined(__cplusplus) || defined(c_plusplus)
  33 extern "C" {
  34 #endif
  35
  36 #include "asterisk/event.h"
  37
  38 /*!
  39  * \brief CEL event types
  40  */
  41 enum ast_cel_event_type {
  42         /*! \brief channel birth */
  43         AST_CEL_CHANNEL_START = 1,
  44         /*! \brief channel end */
  45         AST_CEL_CHANNEL_END = 2,
  46         /*! \brief hangup terminates connection */
  47         AST_CEL_HANGUP = 3,
  48         /*! \brief A ringing phone is answered */
  49         AST_CEL_ANSWER = 4,
  50         /*! \brief an app starts */
  51         AST_CEL_APP_START = 5,
  52         /*! \brief an app ends */
  53         AST_CEL_APP_END = 6,
  54         /*! \brief a bridge is established */
  55         AST_CEL_BRIDGE_START = 7,
  56         /*! \brief a bridge is torn down */
  57         AST_CEL_BRIDGE_END = 8,
  58         /*! \brief a conference is started */
  59         AST_CEL_CONF_START = 9,
  60         /*! \brief a conference is ended */
  61         AST_CEL_CONF_END = 10,
  62         /*! \brief a channel is parked */
  63         AST_CEL_PARK_START = 11,
  64         /*! \brief channel out of the park */
  65         AST_CEL_PARK_END = 12,
  66         /*! \brief a transfer occurs */
  67         AST_CEL_BLINDTRANSFER = 13,
  68         /*! \brief a transfer occurs */
  69         AST_CEL_ATTENDEDTRANSFER = 14,
  70         /*! \brief a 3-way conference, usually part of a transfer */
  71         AST_CEL_HOOKFLASH = 16,
  72         /*! \brief a 3-way conference, usually part of a transfer */
  73         AST_CEL_3WAY_START = 17,
  74         /*! \brief a 3-way conference, usually part of a transfer */
  75         AST_CEL_3WAY_END = 18,
  76         /*! \brief channel enters a conference */
  77         AST_CEL_CONF_ENTER = 19,
  78         /*! \brief channel exits a conference */
  79         AST_CEL_CONF_EXIT = 20,
  80         /*! \brief a user-defined event, the event name field should be set  */
  81         AST_CEL_USER_DEFINED = 21,
  82         /*! \brief the last channel with the given linkedid is retired  */
  83         AST_CEL_LINKEDID_END = 22,
  84         /*! \brief a directed pickup was performed on this channel  */
  85         AST_CEL_PICKUP = 24,
  86         /*! \brief this call was forwarded somewhere else  */
  87         AST_CEL_FORWARD = 25,
  88         /*! \brief a bridge turned into a conference and will be treated as such until it is torn down */
  89         AST_CEL_BRIDGE_TO_CONF = 26,
  90         /*! \brief A local channel optimization occurred */
  91         AST_CEL_LOCAL_OPTIMIZE = 27,
  92 };
  93
  94 /*!
  95  * \brief Check to see if CEL is enabled
  96  *
  97  * \since 1.8
  98  *
  99  * \retval zero not enabled
 100  * \retval non-zero enabled
 101  */
 102 unsigned int ast_cel_check_enabled(void);
 103
 104 /*!
 105  * \brief Allocate a CEL record
 106  *
 107  * \since 1.8
 108  *
 109  * \note The CEL record must be destroyed with ast_cel_destroy().
 110  *
 111  * \retval non-NULL an allocated ast_cel structure
 112  * \retval NULL error
 113  */
 114 struct ast_cel *ast_cel_alloc(void);
 115
 116 /*!
 117  * \brief Destroy a CEL record.
 118  *
 119  * \param cel the record to destroy
 120  *
 121  * \since 1.8
 122  *
 123  * \return nothing.
 124  */
 125 void ast_cel_destroy(struct ast_cel *cel);
 126
 127 /*!
 128  * \brief Get the name of a CEL event type
 129  *
 130  * \param type the type to get the name of
 131  *
 132  * \since 1.8
 133  *
 134  * \return the string representation of the type
 135  */
 136 const char *ast_cel_get_type_name(enum ast_cel_event_type type);
 137
 138 /*!
 139  * \brief Get the event type from a string
 140  *
 141  * \param name the event type name as a string
 142  *
 143  * \since 1.8
 144  *
 145  * \return the ast_cel_event_type given by the string
 146  */
 147 enum ast_cel_event_type ast_cel_str_to_event_type(const char *name);
 148
 149 /*!
 150  * \brief Create a fake channel from data in a CEL event
 151  *
 152  * \note
 153  * This function creates a fake channel containing the
 154  * serialized channel data in the given cel event.  It should be
 155  * released with ast_channel_unref() but could be released with
 156  * ast_channel_release().
 157  *
 158  * \param event the CEL event
 159  *
 160  * \since 1.8
 161  *
 162  * \return a channel with the data filled in, or NULL on error
 163  *
 164  * \todo This function is \b very expensive, especially given that some CEL backends
 165  *       use it on \b every CEL event.  This function really needs to go away at
 166  *       some point.
 167  */
 168 struct ast_channel *ast_cel_fabricate_channel_from_event(const struct ast_event *event);
 169
 170 /*!
 171  * \brief Helper struct for getting the fields out of a CEL event
 172  */
 173 struct ast_cel_event_record {
 174         /*!
 175          * \brief struct ABI version
 176          * \note This \b must be incremented when the struct changes.
 177          */
 178         #define AST_CEL_EVENT_RECORD_VERSION 2
 179         /*!
 180          * \brief struct ABI version
 181          * \note This \b must stay as the first member.
 182          */
 183         uint32_t version;
 184         enum ast_cel_event_type event_type;
 185         struct timeval event_time;
 186         const char *event_name;
 187         const char *user_defined_name;
 188         const char *caller_id_name;
 189         const char *caller_id_num;
 190         const char *caller_id_ani;
 191         const char *caller_id_rdnis;
 192         const char *caller_id_dnid;
 193         const char *extension;
 194         const char *context;
 195         const char *channel_name;
 196         const char *application_name;
 197         const char *application_data;
 198         const char *account_code;
 199         const char *peer_account;
 200         const char *unique_id;
 201         const char *linked_id;
 202         uint amaflag;
 203         const char *user_field;
 204         const char *peer;
 205         const char *extra;
 206 };
 207
 208 /*!
 209  * \brief Fill in an ast_cel_event_record from a CEL event
 210  *
 211  * \param[in] event the CEL event
 212  * \param[out] r the ast_cel_event_record to fill in
 213  *
 214  * \since 1.8
 215  *
 216  * \retval 0 success
 217  * \retval non-zero failure
 218  */
 219 int ast_cel_fill_record(const struct ast_event *event, struct ast_cel_event_record *r);
 220
 221 /*!
 222  * \brief Publish a CEL event
 223  * \since 12
 224  *
 225  * \param chan This is the primary channel associated with this channel event.
 226  * \param event_type This is the type of call event being reported.
 227  * \param blob This contains any additional parameters that need to be conveyed for this event.
 228  */
 229 void ast_cel_publish_event(struct ast_channel *chan,
 230         enum ast_cel_event_type event_type,
 231         struct ast_json *blob);
 232
 233 /*!
 234  * \brief Get the CEL topic
 235  *
 236  * \retval The CEL topic
 237  * \retval NULL if not allocated
 238  */
 239 struct stasis_topic *ast_cel_topic(void);
 240
 241 /*! \brief A structure to hold CEL global configuration options */
 242 struct ast_cel_general_config {
 243         AST_DECLARE_STRING_FIELDS(
 244                 AST_STRING_FIELD(date_format); /*!< The desired date format for logging */
 245         );
 246         int enable;                     /*!< Whether CEL is enabled */
 247         int64_t events;                 /*!< The events to be logged */
 248         /*! The apps for which to log app start and end events. This is
 249          * ast_str_container_alloc()ed and filled with ao2-allocated
 250          * char* which are all-lowercase application names. */
 251         struct ao2_container *apps;
 252 };
 253
 254 /*!
 255  * \brief Allocate a CEL configuration object
 256  *
 257  * \retval NULL on error
 258  * \retval The new CEL configuration object
 259  */
 260 void *ast_cel_general_config_alloc(void);
 261
 262 /*!
 263  * \since 12
 264  * \brief Obtain the current CEL configuration
 265  *
 266  * The configuration is a ref counted object. The caller of this function must
 267  * decrement the ref count when finished with the configuration.
 268  *
 269  * \retval NULL on error
 270  * \retval The current CEL configuration
 271  */
 272 struct ast_cel_general_config *ast_cel_get_config(void);
 273
 274 /*!
 275  * \since 12
 276  * \brief Set the current CEL configuration
 277  *
 278  * \param config The new CEL configuration
 279  */
 280 void ast_cel_set_config(struct ast_cel_general_config *config);
 281
 282 struct ast_channel_snapshot;
 283 /*!
 284  * \brief Allocate and populate a CEL event structure
 285  *
 286  * \param snapshot An ast_channel_snapshot of the primary channel associated
 287  *        with this channel event.
 288  * \param event_type The type of call event being reported.
 289  * \param userdefevname Custom name for the call event. (optional)
 290  * \param extra An event-specific opaque JSON blob to be rendered and placed
 291  *        in the "CEL_EXTRA" information element of the call event. (optional)
 292  * \param peer_name The peer name to be placed into the event. (optional)
 293  *
 294  * \since 12
 295  *
 296  * \retval The created ast_event structure
 297  * \retval NULL on failure
 298  */
 299 struct ast_event *ast_cel_create_event(struct ast_channel_snapshot *snapshot,
 300                 enum ast_cel_event_type event_type, const char *userdefevname,
 301                 struct ast_json *extra, const char *peer_name);
 302
 303 #if defined(__cplusplus) || defined(c_plusplus)
 304 }
 305 #endif
 306
 307 #endif /* __AST_CEL_H__ */