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 AMA Flags
  40  *
  41  * \note This must much up with the AST_CDR_* defines for AMA flags.
  42  */
  43 enum ast_cel_ama_flag {
  44         AST_CEL_AMA_FLAG_NONE,
  45         AST_CEL_AMA_FLAG_OMIT,
  46         AST_CEL_AMA_FLAG_BILLING,
  47         AST_CEL_AMA_FLAG_DOCUMENTATION,
  48         /*! \brief Must be final entry */
  49         AST_CEL_AMA_FLAG_TOTAL,
  50 };
  51
  52 /*!
  53  * \brief CEL event types
  54  */
  55 enum ast_cel_event_type {
  56         /*! \brief channel birth */
  57         AST_CEL_CHANNEL_START = 1,
  58         /*! \brief channel end */
  59         AST_CEL_CHANNEL_END = 2,
  60         /*! \brief hangup terminates connection */
  61         AST_CEL_HANGUP = 3,
  62         /*! \brief A ringing phone is answered */
  63         AST_CEL_ANSWER = 4,
  64         /*! \brief an app starts */
  65         AST_CEL_APP_START = 5,
  66         /*! \brief an app ends */
  67         AST_CEL_APP_END = 6,
  68         /*! \brief a bridge is established */
  69         AST_CEL_BRIDGE_START = 7,
  70         /*! \brief a bridge is torn down */
  71         AST_CEL_BRIDGE_END = 8,
  72         /*! \brief a conference is started */
  73         AST_CEL_CONF_START = 9,
  74         /*! \brief a conference is ended */
  75         AST_CEL_CONF_END = 10,
  76         /*! \brief a channel is parked */
  77         AST_CEL_PARK_START = 11,
  78         /*! \brief channel out of the park */
  79         AST_CEL_PARK_END = 12,
  80         /*! \brief a transfer occurs */
  81         AST_CEL_BLINDTRANSFER = 13,
  82         /*! \brief a transfer occurs */
  83         AST_CEL_ATTENDEDTRANSFER = 14,
  84         /*! \brief a transfer occurs */
  85         AST_CEL_TRANSFER = 15,
  86         /*! \brief a 3-way conference, usually part of a transfer */
  87         AST_CEL_HOOKFLASH = 16,
  88         /*! \brief a 3-way conference, usually part of a transfer */
  89         AST_CEL_3WAY_START = 17,
  90         /*! \brief a 3-way conference, usually part of a transfer */
  91         AST_CEL_3WAY_END = 18,
  92         /*! \brief channel enters a conference */
  93         AST_CEL_CONF_ENTER = 19,
  94         /*! \brief channel exits a conference */
  95         AST_CEL_CONF_EXIT = 20,
  96         /*! \brief a user-defined event, the event name field should be set  */
  97         AST_CEL_USER_DEFINED = 21,
  98         /*! \brief the last channel with the given linkedid is retired  */
  99         AST_CEL_LINKEDID_END = 22,
 100         /*! \brief a masquerade happened to alter the participants on a bridge  */
 101         AST_CEL_BRIDGE_UPDATE = 23,
 102         /*! \brief a directed pickup was performed on this channel  */
 103         AST_CEL_PICKUP = 24,
 104         /*! \brief this call was forwarded somewhere else  */
 105         AST_CEL_FORWARD = 25,
 106         /*! \brief a bridge turned into a conference and will be treated as such until it is torn down */
 107         AST_CEL_BRIDGE_TO_CONF = 26,
 108 };
 109
 110 /*!
 111  * \brief Check to see if CEL is enabled
 112  *
 113  * \since 1.8
 114  *
 115  * \retval zero not enabled
 116  * \retval non-zero enabled
 117  */
 118 unsigned int ast_cel_check_enabled(void);
 119
 120 /*!
 121  * \brief Allocate a CEL record
 122  *
 123  * \since 1.8
 124  *
 125  * \note The CEL record must be destroyed with ast_cel_destroy().
 126  *
 127  * \retval non-NULL an allocated ast_cel structure
 128  * \retval NULL error
 129  */
 130 struct ast_cel *ast_cel_alloc(void);
 131
 132 /*!
 133  * \brief Destroy a CEL record.
 134  *
 135  * \param cel the record to destroy
 136  *
 137  * \since 1.8
 138  *
 139  * \return nothing.
 140  */
 141 void ast_cel_destroy(struct ast_cel *cel);
 142
 143 /*!
 144  * \brief Get the name of a CEL event type
 145  *
 146  * \param type the type to get the name of
 147  *
 148  * \since 1.8
 149  *
 150  * \return the string representation of the type
 151  */
 152 const char *ast_cel_get_type_name(enum ast_cel_event_type type);
 153
 154 /*!
 155  * \brief Get the event type from a string
 156  *
 157  * \param name the event type name as a string
 158  *
 159  * \since 1.8
 160  *
 161  * \return the ast_cel_event_type given by the string
 162  */
 163 enum ast_cel_event_type ast_cel_str_to_event_type(const char *name);
 164
 165 /*!
 166  * \brief Convert AMA flag to printable string
 167  *
 168  * \param[in] flag the flag to convert to a string
 169  *
 170  * \since 1.8
 171  *
 172  * \return the string representation of the flag
 173  */
 174 const char *ast_cel_get_ama_flag_name(enum ast_cel_ama_flag flag);
 175
 176 /*!
 177  * \brief Check and potentially retire a Linked ID
 178  *
 179  * \param chan channel that is being destroyed or its linkedid is changing
 180  *
 181  * \since 1.8
 182  *
 183  * If at least one CEL backend is looking for CEL_LINKEDID_END
 184  * events, this function will check if the given channel is the last
 185  * active channel with that linkedid, and if it is, emit a
 186  * CEL_LINKEDID_END event.
 187  *
 188  * \return nothing
 189  */
 190 void ast_cel_check_retire_linkedid(struct ast_channel *chan);
 191
 192 /*!
 193  * \brief Inform CEL that a new linkedid is being used
 194  * \since 11
 195  *
 196  * \retval -1 error
 197  * \retval 0 success
 198  */
 199 int ast_cel_linkedid_ref(const char *linkedid);
 200
 201 /*!
 202  * \brief Create a fake channel from data in a CEL event
 203  *
 204  * \note
 205  * This function creates a fake channel containing the
 206  * serialized channel data in the given cel event.  It should be
 207  * released with ast_channel_unref() but could be released with
 208  * ast_channel_release().
 209  *
 210  * \param event the CEL event
 211  *
 212  * \since 1.8
 213  *
 214  * \return a channel with the data filled in, or NULL on error
 215  *
 216  * \todo This function is \b very expensive, especially given that some CEL backends
 217  *       use it on \b every CEL event.  This function really needs to go away at
 218  *       some point.
 219  */
 220 struct ast_channel *ast_cel_fabricate_channel_from_event(const struct ast_event *event);
 221
 222 /*!
 223  * \brief Report a channel event
 224  *
 225  * \param chan This argument is required.  This is the primary channel associated with
 226  *        this channel event.
 227  * \param event_type This is the type of call event being reported.
 228  * \param userdefevname This is an optional custom name for the call event.
 229  * \param extra This is an optional opaque field that will go into the "CEL_EXTRA"
 230  *        information element of the call event.
 231  * \param peer2 All CEL events contain a "peer name" information element.  The first
 232  *        place the code will look to get a peer name is from the bridged channel to
 233  *        chan.  If chan has no bridged channel and peer2 is specified, then the name
 234  *        of peer2 will go into the "peer name" field.  If neither are available, the
 235  *        peer name field will be blank.
 236  *
 237  * \since 1.8
 238  *
 239  * \pre chan and peer2 are both unlocked
 240  *
 241  * \retval 0 success
 242  * \retval non-zero failure
 243  */
 244 int ast_cel_report_event(struct ast_channel *chan, enum ast_cel_event_type event_type,
 245                 const char *userdefevname, const char *extra, struct ast_channel *peer2);
 246
 247 /*!
 248  * \brief Helper struct for getting the fields out of a CEL event
 249  */
 250 struct ast_cel_event_record {
 251         /*!
 252          * \brief struct ABI version
 253          * \note This \b must be incremented when the struct changes.
 254          */
 255         #define AST_CEL_EVENT_RECORD_VERSION 2
 256         /*!
 257          * \brief struct ABI version
 258          * \note This \b must stay as the first member.
 259          */
 260         uint32_t version;
 261         enum ast_cel_event_type event_type;
 262         struct timeval event_time;
 263         const char *event_name;
 264         const char *user_defined_name;
 265         const char *caller_id_name;
 266         const char *caller_id_num;
 267         const char *caller_id_ani;
 268         const char *caller_id_rdnis;
 269         const char *caller_id_dnid;
 270         const char *extension;
 271         const char *context;
 272         const char *channel_name;
 273         const char *application_name;
 274         const char *application_data;
 275         const char *account_code;
 276         const char *peer_account;
 277         const char *unique_id;
 278         const char *linked_id;
 279         uint amaflag;
 280         const char *user_field;
 281         const char *peer;
 282         const char *extra;
 283 };
 284
 285 /*!
 286  * \brief Fill in an ast_cel_event_record from a CEL event
 287  *
 288  * \param[in] event the CEL event
 289  * \param[out] r the ast_cel_event_record to fill in
 290  *
 291  * \since 1.8
 292  *
 293  * \retval 0 success
 294  * \retval non-zero failure
 295  */
 296 int ast_cel_fill_record(const struct ast_event *event, struct ast_cel_event_record *r);
 297
 298 #if defined(__cplusplus) || defined(c_plusplus)
 299 }
 300 #endif
 301
 302 #endif /* __AST_CEL_H__ */