Sat Mar 10 01:54:06 2012

Asterisk developer's documentation


cel.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 2008 - 2009, Digium, Inc.
00005  *
00006  * See http://www.asterisk.org for more information about
00007  * the Asterisk project. Please do not directly contact
00008  * any of the maintainers of this project for assistance;
00009  * the project provides a web site, mailing lists and IRC
00010  * channels for your use.
00011  *
00012  * This program is free software, distributed under the terms of
00013  * the GNU General Public License Version 2. See the LICENSE file
00014  * at the top of the source tree.
00015  */
00016 
00017 /*! 
00018  * \file
00019  * \brief Call Event Logging API 
00020  */
00021 
00022 #ifndef __AST_CEL_H__
00023 #define __AST_CEL_H__
00024 
00025 #if defined(__cplusplus) || defined(c_plusplus)
00026 extern "C" {
00027 #endif
00028 
00029 #include "asterisk/event.h"
00030 
00031 /*!
00032  * \brief AMA Flags
00033  *
00034  * \note This must much up with the AST_CDR_* defines for AMA flags.
00035  */
00036 enum ast_cel_ama_flag {
00037    AST_CEL_AMA_FLAG_NONE,
00038    AST_CEL_AMA_FLAG_OMIT,
00039    AST_CEL_AMA_FLAG_BILLING,
00040    AST_CEL_AMA_FLAG_DOCUMENTATION,
00041    /*! \brief Must be final entry */
00042    AST_CEL_AMA_FLAG_TOTAL,
00043 };
00044 
00045 /*!
00046  * \brief CEL event types
00047  */
00048 enum ast_cel_event_type {
00049    /*! \brief channel birth */
00050    AST_CEL_CHANNEL_START = 1,
00051    /*! \brief channel end */
00052    AST_CEL_CHANNEL_END = 2,
00053    /*! \brief hangup terminates connection */
00054    AST_CEL_HANGUP = 3,
00055    /*! \brief A ringing phone is answered */
00056    AST_CEL_ANSWER = 4,
00057    /*! \brief an app starts */
00058    AST_CEL_APP_START = 5,
00059    /*! \brief an app ends */
00060    AST_CEL_APP_END = 6,
00061    /*! \brief a bridge is established */
00062    AST_CEL_BRIDGE_START = 7,
00063    /*! \brief a bridge is torn down */
00064    AST_CEL_BRIDGE_END = 8,
00065    /*! \brief a conference is started */
00066    AST_CEL_CONF_START = 9,
00067    /*! \brief a conference is ended */
00068    AST_CEL_CONF_END = 10,
00069    /*! \brief a channel is parked */
00070    AST_CEL_PARK_START = 11,
00071    /*! \brief channel out of the park */
00072    AST_CEL_PARK_END = 12,
00073    /*! \brief a transfer occurs */
00074    AST_CEL_BLINDTRANSFER = 13,
00075    /*! \brief a transfer occurs */
00076    AST_CEL_ATTENDEDTRANSFER = 14,
00077    /*! \brief a transfer occurs */
00078    AST_CEL_TRANSFER = 15,
00079    /*! \brief a 3-way conference, usually part of a transfer */
00080    AST_CEL_HOOKFLASH = 16,
00081    /*! \brief a 3-way conference, usually part of a transfer */
00082    AST_CEL_3WAY_START = 17,
00083    /*! \brief a 3-way conference, usually part of a transfer */
00084    AST_CEL_3WAY_END = 18,
00085    /*! \brief channel enters a conference */
00086    AST_CEL_CONF_ENTER = 19,
00087    /*! \brief channel exits a conference */
00088    AST_CEL_CONF_EXIT = 20,
00089    /*! \brief a user-defined event, the event name field should be set  */
00090    AST_CEL_USER_DEFINED = 21,
00091    /*! \brief the last channel with the given linkedid is retired  */
00092    AST_CEL_LINKEDID_END = 22,
00093    /*! \brief a masquerade happened to alter the participants on a bridge  */
00094    AST_CEL_BRIDGE_UPDATE = 23,
00095    /*! \brief a directed pickup was performed on this channel  */
00096    AST_CEL_PICKUP = 24,
00097    /*! \brief this call was forwarded somewhere else  */
00098    AST_CEL_FORWARD = 25,
00099 };
00100 
00101 /*! 
00102  * \brief Check to see if CEL is enabled
00103  *
00104  * \since 1.8
00105  *
00106  * \retval zero not enabled
00107  * \retval non-zero enabled
00108  */
00109 unsigned int ast_cel_check_enabled(void);
00110 
00111 /*! 
00112  * \brief Allocate a CEL record 
00113  *
00114  * \since 1.8
00115  *
00116  * \note The CEL record must be destroyed with ast_cel_destroy().
00117  *
00118  * \retval non-NULL an allocated ast_cel structure
00119  * \retval NULL error
00120  */
00121 struct ast_cel *ast_cel_alloc(void);
00122 
00123 /*! 
00124  * \brief Destroy a CEL record.
00125  *
00126  * \param cel the record to destroy
00127  *
00128  * \since 1.8
00129  *
00130  * \return nothing.
00131  */
00132 void ast_cel_destroy(struct ast_cel *cel);
00133 
00134 /*!
00135  * \brief Get the name of a CEL event type
00136  *
00137  * \param type the type to get the name of
00138  *
00139  * \since 1.8
00140  *
00141  * \return the string representation of the type
00142  */
00143 const char *ast_cel_get_type_name(enum ast_cel_event_type type);
00144 
00145 /*!
00146  * \brief Get the event type from a string
00147  *
00148  * \param name the event type name as a string
00149  *
00150  * \since 1.8
00151  *
00152  * \return the ast_cel_event_type given by the string
00153  */
00154 enum ast_cel_event_type ast_cel_str_to_event_type(const char *name);
00155 
00156 /*!
00157  * \brief Convert AMA flag to printable string
00158  * 
00159  * \param[in] flag the flag to convert to a string
00160  *
00161  * \since 1.8
00162  *
00163  * \return the string representation of the flag
00164  */
00165 const char *ast_cel_get_ama_flag_name(enum ast_cel_ama_flag flag);
00166 
00167 /*! 
00168  * \brief Check and potentially retire a Linked ID
00169  *
00170  * \param chan channel that is being destroyed or its linkedid is changing
00171  *
00172  * \since 1.8
00173  *
00174  * If at least one CEL backend is looking for CEL_LINKEDID_END
00175  * events, this function will check if the given channel is the last
00176  * active channel with that linkedid, and if it is, emit a
00177  * CEL_LINKEDID_END event.
00178  *
00179  * \return nothing
00180  */
00181 void ast_cel_check_retire_linkedid(struct ast_channel *chan);
00182 
00183 /*!
00184  * \brief Create a fake channel from data in a CEL event
00185  *
00186  * \note
00187  * This function creates a fake channel containing the
00188  * serialized channel data in the given cel event.  It should be
00189  * released with ast_channel_unref() but could be released with
00190  * ast_channel_release().
00191  *
00192  * \param event the CEL event
00193  *
00194  * \since 1.8
00195  *
00196  * \return a channel with the data filled in, or NULL on error
00197  *
00198  * \todo This function is \b very expensive, especially given that some CEL backends
00199  *       use it on \b every CEL event.  This function really needs to go away at
00200  *       some point.
00201  */
00202 struct ast_channel *ast_cel_fabricate_channel_from_event(const struct ast_event *event);
00203 
00204 /*!
00205  * \brief Report a channel event
00206  *
00207  * \param chan This argument is required.  This is the primary channel associated with
00208  *        this channel event.
00209  * \param event_type This is the type of call event being reported.
00210  * \param userdefevname This is an optional custom name for the call event.
00211  * \param extra This is an optional opaque field that will go into the "CEL_EXTRA"
00212  *        information element of the call event.
00213  * \param peer2 All CEL events contain a "peer name" information element.  The first
00214  *        place the code will look to get a peer name is from the bridged channel to
00215  *        chan.  If chan has no bridged channel and peer2 is specified, then the name
00216  *        of peer2 will go into the "peer name" field.  If neither are available, the
00217  *        peer name field will be blank.
00218  *
00219  * \since 1.8
00220  *
00221  * \pre chan and peer2 are both unlocked
00222  *
00223  * \retval 0 success
00224  * \retval non-zero failure
00225  */
00226 int ast_cel_report_event(struct ast_channel *chan, enum ast_cel_event_type event_type,
00227       const char *userdefevname, const char *extra, struct ast_channel *peer2);
00228 
00229 /*!
00230  * \brief Helper struct for getting the fields out of a CEL event
00231  */
00232 struct ast_cel_event_record {
00233    /*!
00234     * \brief struct ABI version
00235     * \note This \b must be incremented when the struct changes.
00236     */
00237    #define AST_CEL_EVENT_RECORD_VERSION 2
00238    /*!
00239     * \brief struct ABI version
00240     * \note This \b must stay as the first member.
00241     */
00242    uint32_t version;
00243    enum ast_cel_event_type event_type;
00244    struct timeval event_time;
00245    const char *event_name;
00246    const char *user_defined_name;
00247    const char *caller_id_name;
00248    const char *caller_id_num;
00249    const char *caller_id_ani;
00250    const char *caller_id_rdnis;
00251    const char *caller_id_dnid;
00252    const char *extension;
00253    const char *context;
00254    const char *channel_name;
00255    const char *application_name;
00256    const char *application_data;
00257    const char *account_code;
00258    const char *peer_account;
00259    const char *unique_id;
00260    const char *linked_id;
00261    uint amaflag;
00262    const char *user_field;
00263    const char *peer;
00264    const char *extra;
00265 };
00266 
00267 /*!
00268  * \brief Fill in an ast_cel_event_record from a CEL event
00269  *
00270  * \param[in] event the CEL event
00271  * \param[out] r the ast_cel_event_record to fill in
00272  *
00273  * \since 1.8
00274  *
00275  * \retval 0 success
00276  * \retval non-zero failure
00277  */
00278 int ast_cel_fill_record(const struct ast_event *event, struct ast_cel_event_record *r);
00279 
00280 #if defined(__cplusplus) || defined(c_plusplus)
00281 }
00282 #endif
00283 
00284 #endif /* __AST_CEL_H__ */

Generated on Sat Mar 10 01:54:06 2012 for Asterisk - The Open Source Telephony Project by  doxygen 1.4.7