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