2 * Asterisk -- An open source telephony toolkit.
4 * Copyright (C) 2008 - 2009, Digium, Inc.
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.
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.
19 * \brief Call Event Logging API
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.
32 #if defined(__cplusplus) || defined(c_plusplus)
36 #include "asterisk/event.h"
39 * \brief CEL event types
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 */
48 /*! \brief A ringing phone is answered */
50 /*! \brief an app starts */
51 AST_CEL_APP_START = 5,
52 /*! \brief an app ends */
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 */
86 /*! \brief this call was forwarded somewhere else */
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,
95 * \brief Check to see if CEL is enabled
99 * \retval zero not enabled
100 * \retval non-zero enabled
102 unsigned int ast_cel_check_enabled(void);
105 * \brief Allocate a CEL record
109 * \note The CEL record must be destroyed with ast_cel_destroy().
111 * \retval non-NULL an allocated ast_cel structure
114 struct ast_cel *ast_cel_alloc(void);
117 * \brief Destroy a CEL record.
119 * \param cel the record to destroy
125 void ast_cel_destroy(struct ast_cel *cel);
128 * \brief Get the name of a CEL event type
130 * \param type the type to get the name of
134 * \return the string representation of the type
136 const char *ast_cel_get_type_name(enum ast_cel_event_type type);
139 * \brief Get the event type from a string
141 * \param name the event type name as a string
145 * \return the ast_cel_event_type given by the string
147 enum ast_cel_event_type ast_cel_str_to_event_type(const char *name);
150 * \brief Create a fake channel from data in a CEL event
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().
158 * \param event the CEL event
162 * \return a channel with the data filled in, or NULL on error
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
168 struct ast_channel *ast_cel_fabricate_channel_from_event(const struct ast_event *event);
171 * \brief Helper struct for getting the fields out of a CEL event
173 struct ast_cel_event_record {
175 * \brief struct ABI version
176 * \note This \b must be incremented when the struct changes.
178 #define AST_CEL_EVENT_RECORD_VERSION 2
180 * \brief struct ABI version
181 * \note This \b must stay as the first member.
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;
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;
203 const char *user_field;
209 * \brief Fill in an ast_cel_event_record from a CEL event
211 * \param[in] event the CEL event
212 * \param[out] r the ast_cel_event_record to fill in
217 * \retval non-zero failure
219 int ast_cel_fill_record(const struct ast_event *event, struct ast_cel_event_record *r);
222 * \brief Publish a CEL event
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.
229 void ast_cel_publish_event(struct ast_channel *chan,
230 enum ast_cel_event_type event_type,
231 struct ast_json *blob);
234 * \brief Get the CEL topic
236 * \retval The CEL topic
237 * \retval NULL if not allocated
239 struct stasis_topic *ast_cel_topic(void);
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 */
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;
255 * \brief Allocate a CEL configuration object
257 * \retval NULL on error
258 * \retval The new CEL configuration object
260 void *ast_cel_general_config_alloc(void);
264 * \brief Obtain the current CEL configuration
266 * The configuration is a ref counted object. The caller of this function must
267 * decrement the ref count when finished with the configuration.
269 * \retval NULL on error
270 * \retval The current CEL configuration
272 struct ast_cel_general_config *ast_cel_get_config(void);
276 * \brief Set the current CEL configuration
278 * \param config The new CEL configuration
280 void ast_cel_set_config(struct ast_cel_general_config *config);
282 struct ast_channel_snapshot;
284 * \brief Allocate and populate a CEL event structure
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)
296 * \retval The created ast_event structure
297 * \retval NULL on failure
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);
303 #if defined(__cplusplus) || defined(c_plusplus)
307 #endif /* __AST_CEL_H__ */