Wed Jan 8 2020 09:49:43

Asterisk developer's documentation


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