Asterisk - The Open Source Telephony Project GIT-master-650240a
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 * \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)
33extern "C" {
34#endif
35
36#include "asterisk/event.h"
37
38/*!
39 * \brief CEL event types
40 */
44 /*! \brief channel birth */
46 /*! \brief channel end */
48 /*! \brief hangup terminates connection */
50 /*! \brief A ringing phone is answered */
52 /*! \brief an app starts */
54 /*! \brief an app ends */
56 /*! \brief channel enters a bridge */
58 /*! \brief channel exits a bridge */
60 /*! \brief a channel is parked */
62 /*! \brief channel out of the park */
64 /*! \brief a transfer occurs */
66 /*! \brief a transfer occurs */
68 /*! \brief a user-defined event, the event name field should be set */
70 /*! \brief the last channel with the given linkedid is retired */
72 /*! \brief a directed pickup was performed on this channel */
74 /*! \brief this call was forwarded somewhere else */
76 /*! \brief A local channel optimization occurred, this marks the end */
78 /*! \brief A local channel optimization has begun */
80};
81
82/*!
83 * \brief Check to see if CEL is enabled
84 *
85 * \since 1.8
86 *
87 * \retval zero not enabled
88 * \retval non-zero enabled
89 */
90unsigned int ast_cel_check_enabled(void);
91
92/*!
93 * \brief Get the name of a CEL event type
94 *
95 * \param type the type to get the name of
96 *
97 * \since 1.8
98 *
99 * \return the string representation of the type
100 */
102
103/*!
104 * \brief Get the event type from a string
105 *
106 * \param name the event type name as a string
107 *
108 * \since 1.8
109 *
110 * \return the ast_cel_event_type given by the string
111 */
113
114/*!
115 * \brief Create a fake channel from data in a CEL event
116 *
117 * \note
118 * This function creates a fake channel containing the
119 * serialized channel data in the given cel event. It should be
120 * released with ast_channel_unref() but could be released with
121 * ast_channel_release().
122 *
123 * \param event the CEL event
124 *
125 * \since 1.8
126 *
127 * \return a channel with the data filled in, or NULL on error
128 *
129 * \todo This function is \b very expensive, especially given that some CEL backends
130 * use it on \b every CEL event. This function really needs to go away at
131 * some point.
132 */
134
135/*!
136 * \brief Helper struct for getting the fields out of a CEL event
137 */
139 /*!
140 * \brief struct ABI version
141 * \note This \b must be incremented when the struct changes.
142 */
143 #define AST_CEL_EVENT_RECORD_VERSION 2
144 /*!
145 * \brief struct ABI version
146 * \note This \b must stay as the first member.
147 */
148 uint32_t version;
150 struct timeval event_time;
151 const char *event_name;
152 const char *user_defined_name;
153 const char *caller_id_name;
154 const char *caller_id_num;
155 const char *caller_id_ani;
156 const char *caller_id_rdnis;
157 const char *caller_id_dnid;
158 const char *extension;
159 const char *context;
160 const char *channel_name;
161 const char *application_name;
162 const char *application_data;
163 const char *account_code;
164 const char *peer_account;
165 const char *unique_id;
166 const char *linked_id;
168 const char *user_field;
169 const char *peer;
170 const char *extra;
171};
172
173/*!
174 * \brief Fill in an ast_cel_event_record from a CEL event
175 *
176 * \param[in] event the CEL event
177 * \param[out] r the ast_cel_event_record to fill in
178 *
179 * \since 1.8
180 *
181 * \retval 0 success
182 * \retval non-zero failure
183 */
184int ast_cel_fill_record(const struct ast_event *event, struct ast_cel_event_record *r);
185
186/*!
187 * \brief Publish a CEL event
188 * \since 12
189 *
190 * \param chan This is the primary channel associated with this channel event.
191 * \param event_type This is the type of call event being reported.
192 * \param blob This contains any additional parameters that need to be conveyed for this event.
193 */
194void ast_cel_publish_event(struct ast_channel *chan,
195 enum ast_cel_event_type event_type,
196 struct ast_json *blob);
197
198/*!
199 * \brief Publish a CEL user event
200 * \since 18
201 *
202 * \note
203 * This serves as a wrapper function around ast_cel_publish_event() to help pack the
204 * extra details before publishing.
205 *
206 * \param chan This is the primary channel associated with this channel event.
207 * \param event This is the user event being reported.
208 * \param extra This contains any extra parameters that need to be conveyed for this event.
209 */
211 const char *event,
212 const char *extra);
213
214/*!
215 * \brief Get the CEL topic
216 *
217 * \retval The CEL topic
218 * \retval NULL if not allocated
219 */
220struct stasis_topic *ast_cel_topic(void);
221
222/*! \brief A structure to hold CEL global configuration options */
225 AST_STRING_FIELD(date_format); /*!< The desired date format for logging */
226 );
227 int enable; /*!< Whether CEL is enabled */
228 int64_t events; /*!< The events to be logged */
229 /*! The apps for which to log app start and end events. This is
230 * ast_str_container_alloc()ed and filled with ao2-allocated
231 * char* which are all-lowercase application names. */
233};
234
235/*!
236 * \brief Allocate a CEL configuration object
237 *
238 * \retval NULL on error
239 * \retval The new CEL configuration object
240 */
242
243/*!
244 * \since 12
245 * \brief Obtain the current CEL configuration
246 *
247 * The configuration is a ref counted object. The caller of this function must
248 * decrement the ref count when finished with the configuration.
249 *
250 * \retval NULL on error
251 * \retval The current CEL configuration
252 */
254
255/*!
256 * \since 12
257 * \brief Set the current CEL configuration
258 *
259 * \param config The new CEL configuration
260 */
262
264/*!
265 * \brief Allocate and populate a CEL event structure
266 *
267 * \param snapshot An ast_channel_snapshot of the primary channel associated
268 * with this channel event.
269 * \param event_type The type of call event being reported.
270 * \param userdefevname Custom name for the call event. (optional)
271 * \param extra An event-specific opaque JSON blob to be rendered and placed
272 * in the "CEL_EXTRA" information element of the call event. (optional)
273 * \param peer_str A list of comma-separated peer channel names. (optional)
274 *
275 * \since 12
276 *
277 * \retval The created ast_event structure
278 * \retval NULL on failure
279 */
281 enum ast_cel_event_type event_type, const char *userdefevname,
282 struct ast_json *extra, const char *peer_str);
283
284/*!
285 * \brief Allocate and populate a CEL event structure
286 *
287 * \param snapshot An ast_channel_snapshot of the primary channel associated
288 * with this channel event.
289 * \param event_type The type of call event being reported.
290 * \param event_time The time at which the event occurred.
291 * \param userdefevname Custom name for the call event. (optional)
292 * \param extra An event-specific opaque JSON blob to be rendered and placed
293 * in the "CEL_EXTRA" information element of the call event. (optional)
294 * \param peer_str A list of comma-separated peer channel names. (optional)
295 *
296 * \since 13.29.0
297 * \since 16.6.0
298 *
299 * \retval The created ast_event structure
300 * \retval NULL on failure
301 */
303 enum ast_cel_event_type event_type, const struct timeval *event_time,
304 const char *userdefevname, struct ast_json *extra, const char *peer_str);
305
306/*!
307 * \brief CEL backend callback
308 */
309/*typedef int (*ast_cel_backend_cb)(struct ast_cel_event_record *cel);*/
310typedef void (*ast_cel_backend_cb)(struct ast_event *event);
311
312/*!
313 * \brief Register a CEL backend
314 *
315 * \param name Name of backend to register
316 * \param backend_callback Callback to register
317 *
318 * \retval zero on success
319 * \retval non-zero on failure
320 * \since 12
321 */
322int ast_cel_backend_register(const char *name, ast_cel_backend_cb backend_callback);
323
324/*!
325 * \brief Unregister a CEL backend
326 *
327 * \param name Name of backend to unregister
328 *
329 * \retval zero on success
330 * \retval non-zero on failure
331 * \since 12
332 */
333int ast_cel_backend_unregister(const char *name);
334
335#if defined(__cplusplus) || defined(c_plusplus)
336}
337#endif
338
339#endif /* __AST_CEL_H__ */
struct ast_event * ast_cel_create_event_with_time(struct ast_channel_snapshot *snapshot, enum ast_cel_event_type event_type, const struct timeval *event_time, const char *userdefevname, struct ast_json *extra, const char *peer_str)
Allocate and populate a CEL event structure.
Definition: cel.c:529
void ast_cel_publish_user_event(struct ast_channel *chan, const char *event, const char *extra)
Publish a CEL user event.
Definition: cel.c:1692
void ast_cel_set_config(struct ast_cel_general_config *config)
Set the current CEL configuration.
Definition: cel.c:1743
struct ast_event * ast_cel_create_event(struct ast_channel_snapshot *snapshot, enum ast_cel_event_type event_type, const char *userdefevname, struct ast_json *extra, const char *peer_str)
Allocate and populate a CEL event structure.
Definition: cel.c:519
int ast_cel_backend_unregister(const char *name)
Unregister a CEL backend.
Definition: cel.c:1769
enum ast_cel_event_type ast_cel_str_to_event_type(const char *name)
Get the event type from a string.
Definition: cel.c:420
void ast_cel_publish_event(struct ast_channel *chan, enum ast_cel_event_type event_type, struct ast_json *blob)
Publish a CEL event.
Definition: cel.c:1707
ast_cel_event_type
CEL event types.
Definition: cel.h:41
@ AST_CEL_CHANNEL_END
channel end
Definition: cel.h:47
@ AST_CEL_APP_END
an app ends
Definition: cel.h:55
@ AST_CEL_ANSWER
A ringing phone is answered.
Definition: cel.h:51
@ AST_CEL_PARK_START
a channel is parked
Definition: cel.h:61
@ AST_CEL_LINKEDID_END
the last channel with the given linkedid is retired
Definition: cel.h:71
@ AST_CEL_INVALID_VALUE
Definition: cel.h:42
@ AST_CEL_BRIDGE_EXIT
channel exits a bridge
Definition: cel.h:59
@ AST_CEL_FORWARD
this call was forwarded somewhere else
Definition: cel.h:75
@ AST_CEL_HANGUP
hangup terminates connection
Definition: cel.h:49
@ AST_CEL_USER_DEFINED
a user-defined event, the event name field should be set
Definition: cel.h:69
@ AST_CEL_PICKUP
a directed pickup was performed on this channel
Definition: cel.h:73
@ AST_CEL_APP_START
an app starts
Definition: cel.h:53
@ AST_CEL_LOCAL_OPTIMIZE_BEGIN
A local channel optimization has begun.
Definition: cel.h:79
@ AST_CEL_ALL
Definition: cel.h:43
@ AST_CEL_PARK_END
channel out of the park
Definition: cel.h:63
@ AST_CEL_CHANNEL_START
channel birth
Definition: cel.h:45
@ AST_CEL_ATTENDEDTRANSFER
a transfer occurs
Definition: cel.h:67
@ AST_CEL_BRIDGE_ENTER
channel enters a bridge
Definition: cel.h:57
@ AST_CEL_BLINDTRANSFER
a transfer occurs
Definition: cel.h:65
@ AST_CEL_LOCAL_OPTIMIZE
A local channel optimization occurred, this marks the end.
Definition: cel.h:77
void * ast_cel_general_config_alloc(void)
Allocate a CEL configuration object.
Definition: cel.c:189
unsigned int ast_cel_check_enabled(void)
Check to see if CEL is enabled.
Definition: cel.c:345
void(* ast_cel_backend_cb)(struct ast_event *event)
CEL backend callback.
Definition: cel.h:310
struct stasis_topic * ast_cel_topic(void)
Get the CEL topic.
Definition: cel.c:1726
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:662
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:821
struct ast_cel_general_config * ast_cel_get_config(void)
Obtain the current CEL configuration.
Definition: cel.c:1731
int ast_cel_backend_register(const char *name, ast_cel_backend_cb backend_callback)
Register a CEL backend.
Definition: cel.c:1781
const char * ast_cel_get_type_name(enum ast_cel_event_type type)
Get the name of a CEL event type.
Definition: cel.c:493
static const char type[]
Definition: chan_ooh323.c:109
static const char config[]
Definition: chan_ooh323.c:111
static const char name[]
Definition: format_mp3.c:68
#define AST_STRING_FIELD(name)
Declare a string field.
Definition: stringfields.h:303
Generic container type.
Helper struct for getting the fields out of a CEL event.
Definition: cel.h:138
const char * caller_id_dnid
Definition: cel.h:157
const char * application_data
Definition: cel.h:162
const char * account_code
Definition: cel.h:163
const char * caller_id_rdnis
Definition: cel.h:156
const char * extra
Definition: cel.h:170
const char * extension
Definition: cel.h:158
const char * caller_id_num
Definition: cel.h:154
const char * channel_name
Definition: cel.h:160
const char * linked_id
Definition: cel.h:166
const char * peer_account
Definition: cel.h:164
const char * peer
Definition: cel.h:169
enum ast_cel_event_type event_type
Definition: cel.h:149
const char * unique_id
Definition: cel.h:165
const char * user_defined_name
Definition: cel.h:152
const char * context
Definition: cel.h:159
const char * application_name
Definition: cel.h:161
struct timeval event_time
Definition: cel.h:150
uint32_t version
struct ABI version
Definition: cel.h:148
const char * user_field
Definition: cel.h:168
const char * caller_id_ani
Definition: cel.h:155
const char * caller_id_name
Definition: cel.h:153
const char * event_name
Definition: cel.h:151
A structure to hold CEL global configuration options.
Definition: cel.h:223
int64_t events
Definition: cel.h:228
AST_DECLARE_STRING_FIELDS(AST_STRING_FIELD(date_format);)
struct ao2_container * apps
Definition: cel.h:232
Structure representing a snapshot of channel state.
Main Channel structure associated with a channel.
An event.
Definition: event.c:81
Abstract JSON element (object, array, string, int, ...).
Definition: astman.c:222