Asterisk - The Open Source Telephony Project  21.4.1
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)
33 extern "C" {
34 #endif
35 
36 #include "asterisk/event.h"
37 
38 /*!
39  * \brief CEL event types
40  */
42  AST_CEL_INVALID_VALUE = -1,
43  AST_CEL_ALL = 0,
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  */
90 unsigned 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  */
101 const char *ast_cel_get_type_name(enum ast_cel_event_type type);
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;
149  enum ast_cel_event_type event_type;
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;
167  uint amaflag;
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  */
184 int 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  */
194 void 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  */
210 void ast_cel_publish_user_event(struct ast_channel *chan,
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  */
220 struct stasis_topic *ast_cel_topic(void);
221 
222 /*! \brief A structure to hold CEL global configuration options */
224  AST_DECLARE_STRING_FIELDS(
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  */
241 void *ast_cel_general_config_alloc(void);
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  */
261 void ast_cel_set_config(struct ast_cel_general_config *config);
262 
263 struct ast_channel_snapshot;
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  */
280 struct ast_event *ast_cel_create_event(struct ast_channel_snapshot *snapshot,
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);*/
310 typedef 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  */
322 int 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  */
333 int ast_cel_backend_unregister(const char *name);
334 
335 #if defined(__cplusplus) || defined(c_plusplus)
336 }
337 #endif
338 
339 #endif /* __AST_CEL_H__ */
the last channel with the given linkedid is retired
Definition: cel.h:71
Helper struct for getting the fields out of a CEL event.
Definition: cel.h:138
Main Channel structure associated with a channel.
An event.
Definition: event.c:81
int ast_cel_backend_register(const char *name, ast_cel_backend_cb backend_callback)
Register a CEL backend.
Definition: cel.c:1781
A local channel optimization occurred, this marks the end.
Definition: cel.h:77
Structure representing a snapshot of channel state.
channel birth
Definition: cel.h:45
unsigned int ast_cel_check_enabled(void)
Check to see if CEL is enabled.
Definition: cel.c:345
Definition: astman.c:222
A local channel optimization has begun.
Definition: cel.h:79
int64_t events
Definition: cel.h:228
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
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
void ast_cel_set_config(struct ast_cel_general_config *config)
Set the current CEL configuration.
Definition: cel.c:1743
channel enters a bridge
Definition: cel.h:57
void(* ast_cel_backend_cb)(struct ast_event *event)
CEL backend callback.
Definition: cel.h:310
an app ends
Definition: cel.h:55
#define AST_STRING_FIELD(name)
Declare a string field.
Definition: stringfields.h:303
structure to hold extensions
uint32_t version
struct ABI version
Definition: cel.h:148
hangup terminates connection
Definition: cel.h:49
a transfer occurs
Definition: cel.h:65
a channel is parked
Definition: cel.h:61
int ast_cel_backend_unregister(const char *name)
Unregister a CEL backend.
Definition: cel.c:1769
a transfer occurs
Definition: cel.h:67
struct ao2_container * apps
Definition: cel.h:232
channel end
Definition: cel.h:47
struct ast_cel_general_config * ast_cel_get_config(void)
Obtain the current CEL configuration.
Definition: cel.c:1731
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
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
A structure to hold CEL global configuration options.
Definition: cel.h:223
struct stasis_topic * ast_cel_topic(void)
Get the CEL topic.
Definition: cel.c:1726
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_general_config_alloc(void)
Allocate a CEL configuration object.
Definition: cel.c:189
A ringing phone is answered.
Definition: cel.h:51
channel out of the park
Definition: cel.h:63
Abstract JSON element (object, array, string, int, ...).
a user-defined event, the event name field should be set
Definition: cel.h:69
channel exits a bridge
Definition: cel.h:59
ast_cel_event_type
CEL event types.
Definition: cel.h:41
Generic container type.
an app starts
Definition: cel.h:53
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
char name[0]
Definition: cel.c:330
a directed pickup was performed on this channel
Definition: cel.h:73
this call was forwarded somewhere else
Definition: cel.h:75
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
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