summaryrefslogtreecommitdiff
path: root/include/asterisk/cel.h
diff options
context:
space:
mode:
authorRussell Bryant <russell@russellbryant.com>2009-06-26 15:28:53 +0000
committerRussell Bryant <russell@russellbryant.com>2009-06-26 15:28:53 +0000
commit0264eef1156b8ef7369884dd5c663646f1b2b429 (patch)
treea28e9113cf1daf97e45a8fc6d41a52c76ac69836 /include/asterisk/cel.h
parente06c6f97c4c222b4c802ac2b85f76a331991dffb (diff)
Merge the new Channel Event Logging (CEL) subsystem.
CEL is the new system for logging channel events. This was inspired after facing many problems trying to represent what is possible to happen to a call in Asterisk using CDR records. For more information on CEL, see the built in HTML or PDF documentation generated from the files in doc/tex/. Many thanks to Steve Murphy (murf) and Brian Degenhardt (bmd) for their hard work developing this code. Also, thanks to Matt Nicholson (mnicholson) and Sean Bright (seanbright) for their assistance in the final push to get this code ready for Asterisk trunk. Review: https://reviewboard.asterisk.org/r/239/ git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@203638 65c4cc65-6c06-0410-ace0-fbb531ad65f3
Diffstat (limited to 'include/asterisk/cel.h')
-rw-r--r--include/asterisk/cel.h276
1 files changed, 276 insertions, 0 deletions
diff --git a/include/asterisk/cel.h b/include/asterisk/cel.h
new file mode 100644
index 000000000..14f886db2
--- /dev/null
+++ b/include/asterisk/cel.h
@@ -0,0 +1,276 @@
+/*
+ * Asterisk -- An open source telephony toolkit.
+ *
+ * Copyright (C) 2008 - 2009, Digium, Inc.
+ *
+ * See http://www.asterisk.org for more information about
+ * the Asterisk project. Please do not directly contact
+ * any of the maintainers of this project for assistance;
+ * the project provides a web site, mailing lists and IRC
+ * channels for your use.
+ *
+ * This program is free software, distributed under the terms of
+ * the GNU General Public License Version 2. See the LICENSE file
+ * at the top of the source tree.
+ */
+
+/*!
+ * \file
+ * \brief Call Event Logging API
+ */
+
+#ifndef __AST_CEL_H__
+#define __AST_CEL_H__
+
+#if defined(__cplusplus) || defined(c_plusplus)
+extern "C" {
+#endif
+
+#include "asterisk/event.h"
+
+/*! \brief AMA Flags */
+enum ast_cel_ama_flag {
+ AST_CEL_AMA_FLAG_OMIT,
+ AST_CEL_AMA_FLAG_BILLING,
+ AST_CEL_AMA_FLAG_DOCUMENTATION,
+ /*! \brief Must be final entry */
+ AST_CEL_AMA_FLAG_TOTAL,
+};
+
+/*!
+ * \brief CEL event types
+ */
+enum ast_cel_event_type {
+ /*! \brief channel birth */
+ AST_CEL_CHANNEL_START = 1,
+ /*! \brief channel end */
+ AST_CEL_CHANNEL_END = 2,
+ /*! \brief hangup terminates connection */
+ AST_CEL_HANGUP = 3,
+ /*! \brief A ringing phone is answered */
+ AST_CEL_ANSWER = 4,
+ /*! \brief an app starts */
+ AST_CEL_APP_START = 5,
+ /*! \brief an app ends */
+ AST_CEL_APP_END = 6,
+ /*! \brief a bridge is established */
+ AST_CEL_BRIDGE_START = 7,
+ /*! \brief a bridge is torn down */
+ AST_CEL_BRIDGE_END = 8,
+ /*! \brief a conference is started */
+ AST_CEL_CONF_START = 9,
+ /*! \brief a conference is ended */
+ AST_CEL_CONF_END = 10,
+ /*! \brief a channel is parked */
+ AST_CEL_PARK_START = 11,
+ /*! \brief channel out of the park */
+ AST_CEL_PARK_END = 12,
+ /*! \brief a transfer occurs */
+ AST_CEL_BLINDTRANSFER = 13,
+ /*! \brief a transfer occurs */
+ AST_CEL_ATTENDEDTRANSFER = 14,
+ /*! \brief a transfer occurs */
+ AST_CEL_TRANSFER = 15,
+ /*! \brief a 3-way conference, usually part of a transfer */
+ AST_CEL_HOOKFLASH = 16,
+ /*! \brief a 3-way conference, usually part of a transfer */
+ AST_CEL_3WAY_START = 17,
+ /*! \brief a 3-way conference, usually part of a transfer */
+ AST_CEL_3WAY_END = 18,
+ /*! \brief channel enters a conference */
+ AST_CEL_CONF_ENTER = 19,
+ /*! \brief channel exits a conference */
+ AST_CEL_CONF_EXIT = 20,
+ /*! \brief a user-defined event, the event name field should be set */
+ AST_CEL_USER_DEFINED = 21,
+ /*! \brief the last channel with the given linkedid is retired */
+ AST_CEL_LINKEDID_END = 22,
+ /*! \brief a masquerade happened to alter the participants on a bridge */
+ AST_CEL_BRIDGE_UPDATE = 23,
+ /*! \brief a directed pickup was performed on this channel */
+ AST_CEL_PICKUP = 24,
+ /*! \brief this call was forwarded somewhere else */
+ AST_CEL_FORWARD = 25,
+};
+
+/*!
+ * \brief Check to see if CEL is enabled
+ *
+ * \since 1.6.3
+ *
+ * \retval zero not enabled
+ * \retval non-zero enabled
+ */
+unsigned int ast_cel_check_enabled(void);
+
+/*!
+ * \brief Allocate a CEL record
+ *
+ * \since 1.6.3
+ *
+ * \note The CEL record must be destroyed with ast_cel_destroy().
+ *
+ * \retval non-NULL an allocated ast_cel structure
+ * \retval NULL error
+ */
+struct ast_cel *ast_cel_alloc(void);
+
+/*!
+ * \brief Destroy a CEL record.
+ *
+ * \param cel the record to destroy
+ *
+ * \since 1.6.3
+ *
+ * \return nothing.
+ */
+void ast_cel_destroy(struct ast_cel *cel);
+
+/*!
+ * \brief Get the name of a CEL event type
+ *
+ * \param type the type to get the name of
+ *
+ * \since 1.6.3
+ *
+ * \return the string representation of the type
+ */
+const char *ast_cel_get_type_name(enum ast_cel_event_type type);
+
+/*!
+ * \brief Get the event type from a string
+ *
+ * \param name the event type name as a string
+ *
+ * \since 1.6.3
+ *
+ * \return the ast_cel_event_type given by the string
+ */
+enum ast_cel_event_type ast_cel_str_to_event_type(const char *name);
+
+/*!
+ * \brief Convert AMA flag to printable string
+ *
+ * \param[in] flag the flag to convert to a string
+ *
+ * \since 1.6.3
+ *
+ * \return the string representation of the flag
+ */
+const char *ast_cel_get_ama_flag_name(enum ast_cel_ama_flag flag);
+
+/*!
+ * \brief Check and potentially retire a Linked ID
+ *
+ * \param chan channel that is being destroyed or its linkedid is changing
+ *
+ * \since 1.6.3
+ *
+ * If at least one CEL backend is looking for CEL_LINKEDID_END
+ * events, this function will check if the given channel is the last
+ * active channel with that linkedid, and if it is, emit a
+ * CEL_LINKEDID_END event.
+ *
+ * \return nothing
+ */
+void ast_cel_check_retire_linkedid(struct ast_channel *chan);
+
+/*!
+ * \brief Create a fake channel from data in a CEL event
+ *
+ * This function creates a fake channel containing the serialized channel data
+ * in the given cel event. It must be released with ast_channel_release.
+ *
+ * \param event the CEL event
+ *
+ * \since 1.6.3
+ *
+ * \return a channel with the data filled in, or NULL on error
+ *
+ * \todo This function is \b very expensive, especially given that some CEL backends
+ * use it on \b every CEL event. This function really needs to go away at
+ * some point.
+ */
+struct ast_channel *ast_cel_fabricate_channel_from_event(const struct ast_event *event);
+
+/*!
+ * \brief Report a channel event
+ *
+ * \param chan This argument is required. This is the primary channel associated with
+ * this channel event.
+ * \param event_type This is the type of call event being reported.
+ * \param userdefevname This is an optional custom name for the call event.
+ * \param extra This is an optional opaque field that will go into the "CEL_EXTRA"
+ * information element of the call event.
+ * \param peer2 All CEL events contain a "peer name" information element. The first
+ * place the code will look to get a peer name is from the bridged channel to
+ * chan. If chan has no bridged channel and peer2 is specified, then the name
+ * of peer2 will go into the "peer name" field. If neither are available, the
+ * peer name field will be blank.
+ *
+ * \since 1.6.3
+ *
+ * \pre chan and peer2 are both unlocked
+ *
+ * \retval 0 success
+ * \retval non-zero failure
+ */
+int ast_cel_report_event(struct ast_channel *chan, enum ast_cel_event_type event_type,
+ const char *userdefevname, const char *extra, struct ast_channel *peer2);
+
+/*!
+ * \brief Helper struct for getting the fields out of a CEL event
+ */
+struct ast_cel_event_record {
+ /*!
+ * \brief struct ABI version
+ * \note This \b must be incremented when the struct changes.
+ */
+ #define AST_CEL_EVENT_RECORD_VERSION 2
+ /*!
+ * \brief struct ABI version
+ * \note This \b must stay as the first member.
+ */
+ uint32_t version;
+ enum ast_cel_event_type event_type;
+ struct timeval event_time;
+ const char *event_name;
+ const char *user_defined_name;
+ const char *caller_id_name;
+ const char *caller_id_num;
+ const char *caller_id_ani;
+ const char *caller_id_rdnis;
+ const char *caller_id_dnid;
+ const char *extension;
+ const char *context;
+ const char *channel_name;
+ const char *application_name;
+ const char *application_data;
+ const char *account_code;
+ const char *peer_account;
+ const char *unique_id;
+ const char *linked_id;
+ uint amaflag;
+ const char *user_field;
+ const char *peer;
+ const char *extra;
+};
+
+/*!
+ * \brief Fill in an ast_cel_event_record from a CEL event
+ *
+ * \param[in] event the CEL event
+ * \param[out] r the ast_cel_event_record to fill in
+ *
+ * \since 1.6.3
+ *
+ * \retval 0 success
+ * \retval non-zero failure
+ */
+int ast_cel_fill_record(const struct ast_event *event, struct ast_cel_event_record *r);
+
+#if defined(__cplusplus) || defined(c_plusplus)
+}
+#endif
+
+#endif /* __AST_CEL_H__ */