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  * \todo TODO: There some event types that have been defined here, but are not
00022  *       yet used anywhere in the code. It would be really awesome if someone
00023  *       went through and had Asterisk generate these events where it is
00024  *       appropriate to do so. The defined, but unused events are:
00025  *       CONF_ENTER, CONF_EXIT, CONF_START, CONF_END, 3WAY_START, 3WAY_END,
00026  *       TRANSFER, and HOOKFLASH.
00027  */
00028 
00029 #ifndef __AST_CEL_H__
00030 #define __AST_CEL_H__
00031 
00032 #if defined(__cplusplus) || defined(c_plusplus)
00033 extern "C" {
00034 #endif
00035 
00036 #include "asterisk/event.h"
00037 
00038 /*!
00039  * \brief CEL event types
00040  */
00041 enum ast_cel_event_type {
00042    AST_CEL_INVALID_VALUE = -1,
00043    AST_CEL_ALL = 0,
00044    /*! \brief channel birth */
00045    AST_CEL_CHANNEL_START = 1,
00046    /*! \brief channel end */
00047    AST_CEL_CHANNEL_END = 2,
00048    /*! \brief hangup terminates connection */
00049    AST_CEL_HANGUP = 3,
00050    /*! \brief A ringing phone is answered */
00051    AST_CEL_ANSWER = 4,
00052    /*! \brief an app starts */
00053    AST_CEL_APP_START = 5,
00054    /*! \brief an app ends */
00055    AST_CEL_APP_END = 6,
00056    /*! \brief channel enters a bridge */
00057    AST_CEL_BRIDGE_ENTER = 7,
00058    /*! \brief channel exits a bridge */
00059    AST_CEL_BRIDGE_EXIT = 8,
00060    /*! \brief a channel is parked */
00061    AST_CEL_PARK_START = 9,
00062    /*! \brief channel out of the park */
00063    AST_CEL_PARK_END = 10,
00064    /*! \brief a transfer occurs */
00065    AST_CEL_BLINDTRANSFER = 11,
00066    /*! \brief a transfer occurs */
00067    AST_CEL_ATTENDEDTRANSFER = 12,
00068    /*! \brief a user-defined event, the event name field should be set  */
00069    AST_CEL_USER_DEFINED = 13,
00070    /*! \brief the last channel with the given linkedid is retired  */
00071    AST_CEL_LINKEDID_END = 14,
00072    /*! \brief a directed pickup was performed on this channel  */
00073    AST_CEL_PICKUP = 15,
00074    /*! \brief this call was forwarded somewhere else  */
00075    AST_CEL_FORWARD = 16,
00076    /*! \brief A local channel optimization occurred */
00077    AST_CEL_LOCAL_OPTIMIZE = 17,
00078 };
00079 
00080 /*!
00081  * \brief Check to see if CEL is enabled
00082  *
00083  * \since 1.8
00084  *
00085  * \retval zero not enabled
00086  * \retval non-zero enabled
00087  */
00088 unsigned int ast_cel_check_enabled(void);
00089 
00090 /*! 
00091  * \brief Allocate a CEL record 
00092  *
00093  * \since 1.8
00094  *
00095  * \note The CEL record must be destroyed with ast_cel_destroy().
00096  *
00097  * \retval non-NULL an allocated ast_cel structure
00098  * \retval NULL error
00099  */
00100 struct ast_cel *ast_cel_alloc(void);
00101 
00102 /*! 
00103  * \brief Destroy a CEL record.
00104  *
00105  * \param cel the record to destroy
00106  *
00107  * \since 1.8
00108  *
00109  * \return nothing.
00110  */
00111 void ast_cel_destroy(struct ast_cel *cel);
00112 
00113 /*!
00114  * \brief Get the name of a CEL event type
00115  *
00116  * \param type the type to get the name of
00117  *
00118  * \since 1.8
00119  *
00120  * \return the string representation of the type
00121  */
00122 const char *ast_cel_get_type_name(enum ast_cel_event_type type);
00123 
00124 /*!
00125  * \brief Get the event type from a string
00126  *
00127  * \param name the event type name as a string
00128  *
00129  * \since 1.8
00130  *
00131  * \return the ast_cel_event_type given by the string
00132  */
00133 enum ast_cel_event_type ast_cel_str_to_event_type(const char *name);
00134 
00135 /*!
00136  * \brief Create a fake channel from data in a CEL event
00137  *
00138  * \note
00139  * This function creates a fake channel containing the
00140  * serialized channel data in the given cel event.  It should be
00141  * released with ast_channel_unref() but could be released with
00142  * ast_channel_release().
00143  *
00144  * \param event the CEL event
00145  *
00146  * \since 1.8
00147  *
00148  * \return a channel with the data filled in, or NULL on error
00149  *
00150  * \todo This function is \b very expensive, especially given that some CEL backends
00151  *       use it on \b every CEL event.  This function really needs to go away at
00152  *       some point.
00153  */
00154 struct ast_channel *ast_cel_fabricate_channel_from_event(const struct ast_event *event);
00155 
00156 /*!
00157  * \brief Helper struct for getting the fields out of a CEL event
00158  */
00159 struct ast_cel_event_record {
00160    /*!
00161     * \brief struct ABI version
00162     * \note This \b must be incremented when the struct changes.
00163     */
00164    #define AST_CEL_EVENT_RECORD_VERSION 2
00165    /*!
00166     * \brief struct ABI version
00167     * \note This \b must stay as the first member.
00168     */
00169    uint32_t version;
00170    enum ast_cel_event_type event_type;
00171    struct timeval event_time;
00172    const char *event_name;
00173    const char *user_defined_name;
00174    const char *caller_id_name;
00175    const char *caller_id_num;
00176    const char *caller_id_ani;
00177    const char *caller_id_rdnis;
00178    const char *caller_id_dnid;
00179    const char *extension;
00180    const char *context;
00181    const char *channel_name;
00182    const char *application_name;
00183    const char *application_data;
00184    const char *account_code;
00185    const char *peer_account;
00186    const char *unique_id;
00187    const char *linked_id;
00188    uint amaflag;
00189    const char *user_field;
00190    const char *peer;
00191    const char *extra;
00192 };
00193 
00194 /*!
00195  * \brief Fill in an ast_cel_event_record from a CEL event
00196  *
00197  * \param[in] event the CEL event
00198  * \param[out] r the ast_cel_event_record to fill in
00199  *
00200  * \since 1.8
00201  *
00202  * \retval 0 success
00203  * \retval non-zero failure
00204  */
00205 int ast_cel_fill_record(const struct ast_event *event, struct ast_cel_event_record *r);
00206 
00207 /*!
00208  * \brief Publish a CEL event
00209  * \since 12
00210  *
00211  * \param chan This is the primary channel associated with this channel event.
00212  * \param event_type This is the type of call event being reported.
00213  * \param blob This contains any additional parameters that need to be conveyed for this event.
00214  */
00215 void ast_cel_publish_event(struct ast_channel *chan,
00216    enum ast_cel_event_type event_type,
00217    struct ast_json *blob);
00218 
00219 /*!
00220  * \brief Get the CEL topic
00221  *
00222  * \retval The CEL topic
00223  * \retval NULL if not allocated
00224  */
00225 struct stasis_topic *ast_cel_topic(void);
00226 
00227 /*! \brief A structure to hold CEL global configuration options */
00228 struct ast_cel_general_config {
00229    AST_DECLARE_STRING_FIELDS(
00230       AST_STRING_FIELD(date_format); /*!< The desired date format for logging */
00231    );
00232    int enable;       /*!< Whether CEL is enabled */
00233    int64_t events;         /*!< The events to be logged */
00234    /*! The apps for which to log app start and end events. This is
00235     * ast_str_container_alloc()ed and filled with ao2-allocated
00236     * char* which are all-lowercase application names. */
00237    struct ao2_container *apps;
00238 };
00239 
00240 /*!
00241  * \brief Allocate a CEL configuration object
00242  *
00243  * \retval NULL on error
00244  * \retval The new CEL configuration object
00245  */
00246 void *ast_cel_general_config_alloc(void);
00247 
00248 /*!
00249  * \since 12
00250  * \brief Obtain the current CEL configuration
00251  *
00252  * The configuration is a ref counted object. The caller of this function must
00253  * decrement the ref count when finished with the configuration.
00254  *
00255  * \retval NULL on error
00256  * \retval The current CEL configuration
00257  */
00258 struct ast_cel_general_config *ast_cel_get_config(void);
00259 
00260 /*!
00261  * \since 12
00262  * \brief Set the current CEL configuration
00263  *
00264  * \param config The new CEL configuration
00265  */
00266 void ast_cel_set_config(struct ast_cel_general_config *config);
00267 
00268 struct ast_channel_snapshot;
00269 /*!
00270  * \brief Allocate and populate a CEL event structure
00271  *
00272  * \param snapshot An ast_channel_snapshot of the primary channel associated
00273  *        with this channel event.
00274  * \param event_type The type of call event being reported.
00275  * \param userdefevname Custom name for the call event. (optional)
00276  * \param extra An event-specific opaque JSON blob to be rendered and placed
00277  *        in the "CEL_EXTRA" information element of the call event. (optional)
00278  * \param peer_str A list of comma-separated peer channel names. (optional)
00279  *
00280  * \since 12
00281  *
00282  * \retval The created ast_event structure
00283  * \retval NULL on failure
00284  */
00285 struct ast_event *ast_cel_create_event(struct ast_channel_snapshot *snapshot,
00286       enum ast_cel_event_type event_type, const char *userdefevname,
00287       struct ast_json *extra, const char *peer_str);
00288 
00289 /*!
00290  * \brief CEL backend callback
00291  */
00292 /*typedef int (*ast_cel_backend_cb)(struct ast_cel_event_record *cel);*/
00293 typedef void (*ast_cel_backend_cb)(struct ast_event *event);
00294 
00295 /*!
00296  * \brief Register a CEL backend
00297  *
00298  * \param name Name of backend to register
00299  * \param backend_callback Callback to register
00300  *
00301  * \retval zero on success
00302  * \retval non-zero on failure
00303  * \since 12
00304  */
00305 int ast_cel_backend_register(const char *name, ast_cel_backend_cb backend_callback);
00306 
00307 /*!
00308  * \brief Unregister a CEL backend
00309  *
00310  * \param name Name of backend to unregister
00311  *
00312  * \retval zero on success
00313  * \retval non-zero on failure
00314  * \since 12
00315  */
00316 int ast_cel_backend_unregister(const char *name);
00317 
00318 #if defined(__cplusplus) || defined(c_plusplus)
00319 }
00320 #endif
00321 
00322 #endif /* __AST_CEL_H__ */

Generated on Thu Apr 16 06:27:18 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6