505204a4fda0cc2d5331adf11943050b78e390c7
[asterisk/asterisk.git] / 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 CEL event types
40  */
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 */
47         AST_CEL_HANGUP = 3,
48         /*! \brief A ringing phone is answered */
49         AST_CEL_ANSWER = 4,
50         /*! \brief an app starts */
51         AST_CEL_APP_START = 5,
52         /*! \brief an app ends */
53         AST_CEL_APP_END = 6,
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 transfer occurs */
71         AST_CEL_TRANSFER = 15,
72         /*! \brief a 3-way conference, usually part of a transfer */
73         AST_CEL_HOOKFLASH = 16,
74         /*! \brief a 3-way conference, usually part of a transfer */
75         AST_CEL_3WAY_START = 17,
76         /*! \brief a 3-way conference, usually part of a transfer */
77         AST_CEL_3WAY_END = 18,
78         /*! \brief channel enters a conference */
79         AST_CEL_CONF_ENTER = 19,
80         /*! \brief channel exits a conference */
81         AST_CEL_CONF_EXIT = 20,
82         /*! \brief a user-defined event, the event name field should be set  */
83         AST_CEL_USER_DEFINED = 21,
84         /*! \brief the last channel with the given linkedid is retired  */
85         AST_CEL_LINKEDID_END = 22,
86         /*! \brief a directed pickup was performed on this channel  */
87         AST_CEL_PICKUP = 24,
88         /*! \brief this call was forwarded somewhere else  */
89         AST_CEL_FORWARD = 25,
90         /*! \brief a bridge turned into a conference and will be treated as such until it is torn down */
91         AST_CEL_BRIDGE_TO_CONF = 26,
92 };
93
94 /*! 
95  * \brief Check to see if CEL is enabled
96  *
97  * \since 1.8
98  *
99  * \retval zero not enabled
100  * \retval non-zero enabled
101  */
102 unsigned int ast_cel_check_enabled(void);
103
104 /*! 
105  * \brief Allocate a CEL record 
106  *
107  * \since 1.8
108  *
109  * \note The CEL record must be destroyed with ast_cel_destroy().
110  *
111  * \retval non-NULL an allocated ast_cel structure
112  * \retval NULL error
113  */
114 struct ast_cel *ast_cel_alloc(void);
115
116 /*! 
117  * \brief Destroy a CEL record.
118  *
119  * \param cel the record to destroy
120  *
121  * \since 1.8
122  *
123  * \return nothing.
124  */
125 void ast_cel_destroy(struct ast_cel *cel);
126
127 /*!
128  * \brief Get the name of a CEL event type
129  *
130  * \param type the type to get the name of
131  *
132  * \since 1.8
133  *
134  * \return the string representation of the type
135  */
136 const char *ast_cel_get_type_name(enum ast_cel_event_type type);
137
138 /*!
139  * \brief Get the event type from a string
140  *
141  * \param name the event type name as a string
142  *
143  * \since 1.8
144  *
145  * \return the ast_cel_event_type given by the string
146  */
147 enum ast_cel_event_type ast_cel_str_to_event_type(const char *name);
148
149 /*!
150  * \brief Create a fake channel from data in a CEL event
151  *
152  * \note
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().
157  *
158  * \param event the CEL event
159  *
160  * \since 1.8
161  *
162  * \return a channel with the data filled in, or NULL on error
163  *
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
166  *       some point.
167  */
168 struct ast_channel *ast_cel_fabricate_channel_from_event(const struct ast_event *event);
169
170 /*!
171  * \brief Report a channel event
172  *
173  * \param chan This argument is required.  This is the primary channel associated with
174  *        this channel event.
175  * \param event_type This is the type of call event being reported.
176  * \param userdefevname This is an optional custom name for the call event.
177  * \param extra This is an optional opaque field that will go into the "CEL_EXTRA"
178  *        information element of the call event.
179  * \param peer2 All CEL events contain a "peer name" information element.  The first
180  *        place the code will look to get a peer name is from the bridged channel to
181  *        chan.  If chan has no bridged channel and peer2 is specified, then the name
182  *        of peer2 will go into the "peer name" field.  If neither are available, the
183  *        peer name field will be blank.
184  *
185  * \since 1.8
186  *
187  * \pre chan and peer2 are both unlocked
188  *
189  * \retval 0 success
190  * \retval non-zero failure
191  */
192 int ast_cel_report_event(struct ast_channel *chan, enum ast_cel_event_type event_type,
193                 const char *userdefevname, const char *extra, struct ast_channel *peer2);
194
195 /*!
196  * \brief Helper struct for getting the fields out of a CEL event
197  */
198 struct ast_cel_event_record {
199         /*!
200          * \brief struct ABI version
201          * \note This \b must be incremented when the struct changes.
202          */
203         #define AST_CEL_EVENT_RECORD_VERSION 2
204         /*!
205          * \brief struct ABI version
206          * \note This \b must stay as the first member.
207          */
208         uint32_t version;
209         enum ast_cel_event_type event_type;
210         struct timeval event_time;
211         const char *event_name;
212         const char *user_defined_name;
213         const char *caller_id_name;
214         const char *caller_id_num;
215         const char *caller_id_ani;
216         const char *caller_id_rdnis;
217         const char *caller_id_dnid;
218         const char *extension;
219         const char *context;
220         const char *channel_name;
221         const char *application_name;
222         const char *application_data;
223         const char *account_code;
224         const char *peer_account;
225         const char *unique_id;
226         const char *linked_id;
227         uint amaflag;
228         const char *user_field;
229         const char *peer;
230         const char *extra;
231 };
232
233 /*!
234  * \brief Fill in an ast_cel_event_record from a CEL event
235  *
236  * \param[in] event the CEL event
237  * \param[out] r the ast_cel_event_record to fill in
238  *
239  * \since 1.8
240  *
241  * \retval 0 success
242  * \retval non-zero failure
243  */
244 int ast_cel_fill_record(const struct ast_event *event, struct ast_cel_event_record *r);
245
246 /*!
247  * \brief Publish a CEL event
248  * \since 12
249  *
250  * \param chan This is the primary channel associated with this channel event.
251  * \param event_type This is the type of call event being reported.
252  * \param blob This contains any additional parameters that need to be conveyed for this event.
253  */
254 void ast_cel_publish_event(struct ast_channel *chan,
255         enum ast_cel_event_type event_type,
256         struct ast_json *blob);
257
258 /*!
259  * \brief Get the CEL topic
260  *
261  * \retval The CEL topic
262  * \retval NULL if not allocated
263  */
264 struct stasis_topic *ast_cel_topic(void);
265
266 /*! \brief A structure to hold CEL global configuration options */
267 struct ast_cel_general_config {
268         AST_DECLARE_STRING_FIELDS(
269                 AST_STRING_FIELD(date_format); /*!< The desired date format for logging */
270         );
271         int enable;                     /*!< Whether CEL is enabled */
272         int64_t events;                 /*!< The events to be logged */
273         /*! The apps for which to log app start and end events. This is
274          * ast_str_container_alloc()ed and filled with ao2-allocated
275          * char* which are all-lowercase application names. */
276         struct ao2_container *apps;
277 };
278
279 /*!
280  * \brief Allocate a CEL configuration object
281  *
282  * \retval NULL on error
283  * \retval The new CEL configuration object
284  */
285 void *ast_cel_general_config_alloc(void);
286
287 /*!
288  * \since 12
289  * \brief Obtain the current CEL configuration
290  *
291  * The configuration is a ref counted object. The caller of this function must
292  * decrement the ref count when finished with the configuration.
293  *
294  * \retval NULL on error
295  * \retval The current CEL configuration
296  */
297 struct ast_cel_general_config *ast_cel_get_config(void);
298
299 /*!
300  * \since 12
301  * \brief Set the current CEL configuration
302  *
303  * \param config The new CEL configuration
304  */
305 void ast_cel_set_config(struct ast_cel_general_config *config);
306
307 struct ast_channel_snapshot;
308 /*!
309  * \brief Allocate and populate a CEL event structure
310  *
311  * \param snapshot An ast_channel_snapshot of the primary channel associated
312  *        with this channel event.
313  * \param event_type The type of call event being reported.
314  * \param userdefevname Custom name for the call event. (optional)
315  * \param extra An opaque field that will go into the "CEL_EXTRA" information
316  *        element of the call event. (optional)
317  * \param peer_name The peer name to be placed into the event. (optional)
318  *
319  * \since 12
320  *
321  * \retval The created ast_event structure
322  * \retval NULL on failure
323  */
324 struct ast_event *ast_cel_create_event(struct ast_channel_snapshot *snapshot,
325                 enum ast_cel_event_type event_type, const char *userdefevname,
326                 const char *extra, const char *peer_name);
327
328 #if defined(__cplusplus) || defined(c_plusplus)
329 }
330 #endif
331
332 #endif /* __AST_CEL_H__ */