22a8bddb3ec0946be8c6a8909dd5fecec1b3a148
[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 /*! \brief AMA Flags */
39 enum ast_cel_ama_flag {
40         AST_CEL_AMA_FLAG_OMIT,
41         AST_CEL_AMA_FLAG_BILLING,
42         AST_CEL_AMA_FLAG_DOCUMENTATION,
43         /*! \brief Must be final entry */
44         AST_CEL_AMA_FLAG_TOTAL,
45 };
46
47 /*!
48  * \brief CEL event types
49  */
50 enum ast_cel_event_type {
51         /*! \brief channel birth */
52         AST_CEL_CHANNEL_START = 1,
53         /*! \brief channel end */
54         AST_CEL_CHANNEL_END = 2,
55         /*! \brief hangup terminates connection */
56         AST_CEL_HANGUP = 3,
57         /*! \brief A ringing phone is answered */
58         AST_CEL_ANSWER = 4,
59         /*! \brief an app starts */
60         AST_CEL_APP_START = 5,
61         /*! \brief an app ends */
62         AST_CEL_APP_END = 6,
63         /*! \brief a bridge is established */
64         AST_CEL_BRIDGE_START = 7,
65         /*! \brief a bridge is torn down */
66         AST_CEL_BRIDGE_END = 8,
67         /*! \brief a conference is started */
68         AST_CEL_CONF_START = 9,
69         /*! \brief a conference is ended */
70         AST_CEL_CONF_END = 10,
71         /*! \brief a channel is parked */
72         AST_CEL_PARK_START = 11,
73         /*! \brief channel out of the park */
74         AST_CEL_PARK_END = 12,
75         /*! \brief a transfer occurs */
76         AST_CEL_BLINDTRANSFER = 13,
77         /*! \brief a transfer occurs */
78         AST_CEL_ATTENDEDTRANSFER = 14,
79         /*! \brief a transfer occurs */
80         AST_CEL_TRANSFER = 15,
81         /*! \brief a 3-way conference, usually part of a transfer */
82         AST_CEL_HOOKFLASH = 16,
83         /*! \brief a 3-way conference, usually part of a transfer */
84         AST_CEL_3WAY_START = 17,
85         /*! \brief a 3-way conference, usually part of a transfer */
86         AST_CEL_3WAY_END = 18,
87         /*! \brief channel enters a conference */
88         AST_CEL_CONF_ENTER = 19,
89         /*! \brief channel exits a conference */
90         AST_CEL_CONF_EXIT = 20,
91         /*! \brief a user-defined event, the event name field should be set  */
92         AST_CEL_USER_DEFINED = 21,
93         /*! \brief the last channel with the given linkedid is retired  */
94         AST_CEL_LINKEDID_END = 22,
95         /*! \brief a masquerade happened to alter the participants on a bridge  */
96         AST_CEL_BRIDGE_UPDATE = 23,
97         /*! \brief a directed pickup was performed on this channel  */
98         AST_CEL_PICKUP = 24,
99         /*! \brief this call was forwarded somewhere else  */
100         AST_CEL_FORWARD = 25,
101 };
102
103 /*! 
104  * \brief Check to see if CEL is enabled
105  *
106  * \since 1.8
107  *
108  * \retval zero not enabled
109  * \retval non-zero enabled
110  */
111 unsigned int ast_cel_check_enabled(void);
112
113 /*! 
114  * \brief Allocate a CEL record 
115  *
116  * \since 1.8
117  *
118  * \note The CEL record must be destroyed with ast_cel_destroy().
119  *
120  * \retval non-NULL an allocated ast_cel structure
121  * \retval NULL error
122  */
123 struct ast_cel *ast_cel_alloc(void);
124
125 /*! 
126  * \brief Destroy a CEL record.
127  *
128  * \param cel the record to destroy
129  *
130  * \since 1.8
131  *
132  * \return nothing.
133  */
134 void ast_cel_destroy(struct ast_cel *cel);
135
136 /*!
137  * \brief Get the name of a CEL event type
138  *
139  * \param type the type to get the name of
140  *
141  * \since 1.8
142  *
143  * \return the string representation of the type
144  */
145 const char *ast_cel_get_type_name(enum ast_cel_event_type type);
146
147 /*!
148  * \brief Get the event type from a string
149  *
150  * \param name the event type name as a string
151  *
152  * \since 1.8
153  *
154  * \return the ast_cel_event_type given by the string
155  */
156 enum ast_cel_event_type ast_cel_str_to_event_type(const char *name);
157
158 /*!
159  * \brief Convert AMA flag to printable string
160  * 
161  * \param[in] flag the flag to convert to a string
162  *
163  * \since 1.8
164  *
165  * \return the string representation of the flag
166  */
167 const char *ast_cel_get_ama_flag_name(enum ast_cel_ama_flag flag);
168
169 /*! 
170  * \brief Check and potentially retire a Linked ID
171  *
172  * \param chan channel that is being destroyed or its linkedid is changing
173  *
174  * \since 1.8
175  *
176  * If at least one CEL backend is looking for CEL_LINKEDID_END
177  * events, this function will check if the given channel is the last
178  * active channel with that linkedid, and if it is, emit a
179  * CEL_LINKEDID_END event.
180  *
181  * \return nothing
182  */
183 void ast_cel_check_retire_linkedid(struct ast_channel *chan);
184
185 /*!
186  * \brief Create a fake channel from data in a CEL event
187  *
188  * This function creates a fake channel containing the serialized channel data 
189  * in the given cel event.  It must be released with ast_channel_release.
190  *
191  * \param event the CEL event
192  *
193  * \since 1.8
194  *
195  * \return a channel with the data filled in, or NULL on error
196  *
197  * \todo This function is \b very expensive, especially given that some CEL backends
198  *       use it on \b every CEL event.  This function really needs to go away at
199  *       some point.
200  */
201 struct ast_channel *ast_cel_fabricate_channel_from_event(const struct ast_event *event);
202
203 /*!
204  * \brief Report a channel event
205  *
206  * \param chan This argument is required.  This is the primary channel associated with
207  *        this channel event.
208  * \param event_type This is the type of call event being reported.
209  * \param userdefevname This is an optional custom name for the call event.
210  * \param extra This is an optional opaque field that will go into the "CEL_EXTRA"
211  *        information element of the call event.
212  * \param peer2 All CEL events contain a "peer name" information element.  The first
213  *        place the code will look to get a peer name is from the bridged channel to
214  *        chan.  If chan has no bridged channel and peer2 is specified, then the name
215  *        of peer2 will go into the "peer name" field.  If neither are available, the
216  *        peer name field will be blank.
217  *
218  * \since 1.8
219  *
220  * \pre chan and peer2 are both unlocked
221  *
222  * \retval 0 success
223  * \retval non-zero failure
224  */
225 int ast_cel_report_event(struct ast_channel *chan, enum ast_cel_event_type event_type,
226                 const char *userdefevname, const char *extra, struct ast_channel *peer2);
227
228 /*!
229  * \brief Helper struct for getting the fields out of a CEL event
230  */
231 struct ast_cel_event_record {
232         /*!
233          * \brief struct ABI version
234          * \note This \b must be incremented when the struct changes.
235          */
236         #define AST_CEL_EVENT_RECORD_VERSION 2
237         /*!
238          * \brief struct ABI version
239          * \note This \b must stay as the first member.
240          */
241         uint32_t version;
242         enum ast_cel_event_type event_type;
243         struct timeval event_time;
244         const char *event_name;
245         const char *user_defined_name;
246         const char *caller_id_name;
247         const char *caller_id_num;
248         const char *caller_id_ani;
249         const char *caller_id_rdnis;
250         const char *caller_id_dnid;
251         const char *extension;
252         const char *context;
253         const char *channel_name;
254         const char *application_name;
255         const char *application_data;
256         const char *account_code;
257         const char *peer_account;
258         const char *unique_id;
259         const char *linked_id;
260         uint amaflag;
261         const char *user_field;
262         const char *peer;
263         const char *extra;
264 };
265
266 /*!
267  * \brief Fill in an ast_cel_event_record from a CEL event
268  *
269  * \param[in] event the CEL event
270  * \param[out] r the ast_cel_event_record to fill in
271  *
272  * \since 1.8
273  *
274  * \retval 0 success
275  * \retval non-zero failure
276  */
277 int ast_cel_fill_record(const struct ast_event *event, struct ast_cel_event_record *r);
278
279 #if defined(__cplusplus) || defined(c_plusplus)
280 }
281 #endif
282
283 #endif /* __AST_CEL_H__ */