Asterisk - The Open Source Telephony Project  18.5.0
func_frame_trace.c
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2010, Digium, Inc.
5  *
6  * David Vossel <[email protected]>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18 
19 /*! \file
20  *
21  * \brief Trace internal ast_frames on a channel.
22  *
23  * \author David Vossel <[email protected]>
24  *
25  * \ingroup functions
26  */
27 
28 /*** MODULEINFO
29  <support_level>extended</support_level>
30  ***/
31 
32 #include "asterisk.h"
33 
34 #include "asterisk/module.h"
35 #include "asterisk/channel.h"
36 #include "asterisk/pbx.h"
37 #include "asterisk/framehook.h"
38 
39 /*** DOCUMENTATION
40  <function name="FRAME_TRACE" language="en_US">
41  <synopsis>
42  View internal ast_frames as they are read and written on a channel.
43  </synopsis>
44  <syntax>
45  <parameter name="filter list type" required="true">
46  <para>A filter can be applied to the trace to limit what frames are viewed. This
47  filter can either be a <literal>white</literal> or <literal>black</literal> list
48  of frame types. When no filter type is present, <literal>white</literal> is
49  used. If no arguments are provided at all, all frames will be output.
50  </para>
51 
52  <para>Below are the different types of frames that can be filtered.</para>
53  <enumlist>
54  <enum name = "DTMF_BEGIN" />
55  <enum name = "DTMF_END" />
56  <enum name = "VOICE" />
57  <enum name = "VIDEO" />
58  <enum name = "CONTROL" />
59  <enum name = "NULL" />
60  <enum name = "IAX" />
61  <enum name = "TEXT" />
62  <enum name = "TEXT_DATA" />
63  <enum name = "IMAGE" />
64  <enum name = "HTML" />
65  <enum name = "CNG" />
66  <enum name = "MODEM" />
67  </enumlist>
68  </parameter>
69  </syntax>
70  <description>
71  <para>Examples:</para>
72  <para>exten => 1,1,Set(FRAME_TRACE(white)=DTMF_BEGIN,DTMF_END); view only DTMF frames. </para>
73  <para>exten => 1,1,Set(FRAME_TRACE()=DTMF_BEGIN,DTMF_END); view only DTMF frames. </para>
74  <para>exten => 1,1,Set(FRAME_TRACE(black)=DTMF_BEGIN,DTMF_END); view everything except DTMF frames. </para>
75  </description>
76  </function>
77  ***/
78 
79 static void print_frame(struct ast_frame *frame);
80 static struct {
81  enum ast_frame_type type;
82  const char *str;
83 } frametype2str[] = {
84  { AST_FRAME_DTMF_BEGIN, "DTMF_BEGIN" },
85  { AST_FRAME_DTMF_END, "DTMF_END" },
86  { AST_FRAME_VOICE, "VOICE" },
87  { AST_FRAME_VIDEO, "VIDEO" },
88  { AST_FRAME_CONTROL, "CONTROL" },
89  { AST_FRAME_NULL, "NULL" },
90  { AST_FRAME_IAX, "IAX" },
91  { AST_FRAME_TEXT, "TEXT" },
92  { AST_FRAME_TEXT_DATA, "TEXT_DATA" },
93  { AST_FRAME_IMAGE, "IMAGE" },
94  { AST_FRAME_HTML, "HTML" },
95  { AST_FRAME_CNG, "CNG" },
96  { AST_FRAME_MODEM, "MODEM" },
97 };
98 
99 struct frame_trace_data {
100  int list_type; /* 0 = white, 1 = black */
101  int values[ARRAY_LEN(frametype2str)];
102 };
103 
104 static void datastore_destroy_cb(void *data) {
105  ast_free(data);
106 }
107 
108 static const struct ast_datastore_info frame_trace_datastore = {
109  .type = "frametrace",
110  .destroy = datastore_destroy_cb
111 };
112 
113 static void hook_destroy_cb(void *framedata)
114 {
115  ast_free(framedata);
116 }
117 
118 static struct ast_frame *hook_event_cb(struct ast_channel *chan, struct ast_frame *frame, enum ast_framehook_event event, void *data)
119 {
120  int i;
121  int show_frame = 0;
122  struct frame_trace_data *framedata = data;
123  if (!frame) {
124  return frame;
125  }
126 
127  if ((event != AST_FRAMEHOOK_EVENT_WRITE) && (event != AST_FRAMEHOOK_EVENT_READ)) {
128  return frame;
129  }
130 
131  for (i = 0; i < ARRAY_LEN(frametype2str); i++) {
132  if (frame->frametype == frametype2str[i].type) {
133  if ((framedata->list_type == 0) && (framedata->values[i])) { /* white list */
134  show_frame = 1;
135  } else if ((framedata->list_type == 1) && (!framedata->values[i])){ /* black list */
136  show_frame = 1;
137  }
138  break;
139  }
140  }
141 
142  if (show_frame) {
143  ast_verbose("%s on Channel %s\n", event == AST_FRAMEHOOK_EVENT_READ ? "<--Read" : "--> Write", ast_channel_name(chan));
144  print_frame(frame);
145  }
146  return frame;
147 }
148 
149 static int frame_trace_helper(struct ast_channel *chan, const char *cmd, char *data, const char *value)
150 {
151  struct frame_trace_data *framedata;
152  struct ast_datastore *datastore = NULL;
153  struct ast_framehook_interface interface = {
154  .version = AST_FRAMEHOOK_INTERFACE_VERSION,
155  .event_cb = hook_event_cb,
156  .destroy_cb = hook_destroy_cb,
157  };
158  int i = 0;
159 
160  if (!chan) {
161  ast_log(LOG_WARNING, "No channel was provided to %s function.\n", cmd);
162  return -1;
163  }
164 
165  if (!(framedata = ast_calloc(1, sizeof(*framedata)))) {
166  return 0;
167  }
168 
169  interface.data = framedata;
170 
171  if (!strcasecmp(data, "black")) {
172  framedata->list_type = 1;
173  }
174  for (i = 0; i < ARRAY_LEN(frametype2str); i++) {
175  if (strcasestr(value, frametype2str[i].str)) {
176  framedata->values[i] = 1;
177  }
178  }
179 
180  ast_channel_lock(chan);
181  i = ast_framehook_attach(chan, &interface);
182  if (i >= 0) {
183  int *id;
184  if ((datastore = ast_channel_datastore_find(chan, &frame_trace_datastore, NULL))) {
185  id = datastore->data;
186  ast_framehook_detach(chan, *id);
187  ast_channel_datastore_remove(chan, datastore);
188  ast_datastore_free(datastore);
189  }
190 
191  if (!(datastore = ast_datastore_alloc(&frame_trace_datastore, NULL))) {
192  ast_framehook_detach(chan, i);
193  ast_channel_unlock(chan);
194  return 0;
195  }
196 
197  if (!(id = ast_calloc(1, sizeof(int)))) {
198  ast_datastore_free(datastore);
199  ast_framehook_detach(chan, i);
200  ast_channel_unlock(chan);
201  return 0;
202  }
203 
204  *id = i; /* Store off the id. The channel is still locked so it is safe to access this ptr. */
205  datastore->data = id;
206  ast_channel_datastore_add(chan, datastore);
207  }
208  ast_channel_unlock(chan);
209 
210  return 0;
211 }
212 
213 static void print_frame(struct ast_frame *frame)
214 {
215  switch (frame->frametype) {
216  case AST_FRAME_DTMF_END:
217  ast_verbose("FrameType: DTMF END\n");
218  ast_verbose("Digit: 0x%02X '%c'\n", (unsigned)frame->subclass.integer,
219  frame->subclass.integer < ' ' ? ' ' : frame->subclass.integer);
220  break;
221  case AST_FRAME_VOICE:
222  ast_verbose("FrameType: VOICE\n");
223  ast_verbose("Codec: %s\n", ast_format_get_name(frame->subclass.format));
224  ast_verbose("MS: %ld\n", frame->len);
225  ast_verbose("Samples: %d\n", frame->samples);
226  ast_verbose("Bytes: %d\n", frame->datalen);
227  break;
228  case AST_FRAME_VIDEO:
229  ast_verbose("FrameType: VIDEO\n");
230  ast_verbose("Codec: %s\n", ast_format_get_name(frame->subclass.format));
231  ast_verbose("MS: %ld\n", frame->len);
232  ast_verbose("Samples: %d\n", frame->samples);
233  ast_verbose("Bytes: %d\n", frame->datalen);
234  break;
235  case AST_FRAME_CONTROL:
236  ast_verbose("FrameType: CONTROL\n");
237  switch ((enum ast_control_frame_type) frame->subclass.integer) {
238  case AST_CONTROL_HANGUP:
239  ast_verbose("SubClass: HANGUP\n");
240  break;
241  case AST_CONTROL_RING:
242  ast_verbose("SubClass: RING\n");
243  break;
244  case AST_CONTROL_RINGING:
245  ast_verbose("SubClass: RINGING\n");
246  break;
247  case AST_CONTROL_ANSWER:
248  ast_verbose("SubClass: ANSWER\n");
249  break;
250  case AST_CONTROL_BUSY:
251  ast_verbose("SubClass: BUSY\n");
252  break;
253  case AST_CONTROL_TAKEOFFHOOK:
254  ast_verbose("SubClass: TAKEOFFHOOK\n");
255  break;
256  case AST_CONTROL_OFFHOOK:
257  ast_verbose("SubClass: OFFHOOK\n");
258  break;
259  case AST_CONTROL_CONGESTION:
260  ast_verbose("SubClass: CONGESTION\n");
261  break;
262  case AST_CONTROL_FLASH:
263  ast_verbose("SubClass: FLASH\n");
264  break;
265  case AST_CONTROL_WINK:
266  ast_verbose("SubClass: WINK\n");
267  break;
268  case AST_CONTROL_OPTION:
269  ast_verbose("SubClass: OPTION\n");
270  break;
271  case AST_CONTROL_RADIO_KEY:
272  ast_verbose("SubClass: RADIO KEY\n");
273  break;
274  case AST_CONTROL_RADIO_UNKEY:
275  ast_verbose("SubClass: RADIO UNKEY\n");
276  break;
277  case AST_CONTROL_PROGRESS:
278  ast_verbose("SubClass: PROGRESS\n");
279  break;
280  case AST_CONTROL_PROCEEDING:
281  ast_verbose("SubClass: PROCEEDING\n");
282  break;
283  case AST_CONTROL_HOLD:
284  ast_verbose("SubClass: HOLD\n");
285  break;
286  case AST_CONTROL_UNHOLD:
287  ast_verbose("SubClass: UNHOLD\n");
288  break;
289  case AST_CONTROL_VIDUPDATE:
290  ast_verbose("SubClass: VIDUPDATE\n");
291  break;
292  case _XXX_AST_CONTROL_T38:
293  ast_verbose("SubClass: XXX T38\n");
294  break;
295  case AST_CONTROL_SRCUPDATE:
296  ast_verbose("SubClass: SRCUPDATE\n");
297  break;
298  case AST_CONTROL_TRANSFER:
299  ast_verbose("SubClass: TRANSFER\n");
300  break;
301  case AST_CONTROL_CONNECTED_LINE:
302  ast_verbose("SubClass: CONNECTED LINE\n");
303  break;
304  case AST_CONTROL_REDIRECTING:
305  ast_verbose("SubClass: REDIRECTING\n");
306  break;
307  case AST_CONTROL_T38_PARAMETERS:
308  ast_verbose("SubClass: T38 PARAMETERS\n");
309  break;
310  case AST_CONTROL_CC:
311  ast_verbose("SubClass: CC\n");
312  break;
313  case AST_CONTROL_SRCCHANGE:
314  ast_verbose("SubClass: SRCCHANGE\n");
315  break;
316  case AST_CONTROL_READ_ACTION:
317  ast_verbose("SubClass: READ ACTION\n");
318  break;
319  case AST_CONTROL_AOC:
320  ast_verbose("SubClass: AOC\n");
321  break;
322  case AST_CONTROL_MCID:
323  ast_verbose("SubClass: MCID\n");
324  break;
325  case AST_CONTROL_INCOMPLETE:
326  ast_verbose("SubClass: INCOMPLETE\n");
327  break;
328  case AST_CONTROL_END_OF_Q:
329  ast_verbose("SubClass: END_OF_Q\n");
330  break;
331  case AST_CONTROL_UPDATE_RTP_PEER:
332  ast_verbose("SubClass: UPDATE_RTP_PEER\n");
333  break;
334  case AST_CONTROL_PVT_CAUSE_CODE:
335  ast_verbose("SubClass: PVT_CAUSE_CODE\n");
336  break;
337  case AST_CONTROL_MASQUERADE_NOTIFY:
338  /* Should never happen. */
339  ast_assert(0);
340  break;
341  case AST_CONTROL_STREAM_TOPOLOGY_REQUEST_CHANGE:
342  ast_verbose("SubClass: STREAM_TOPOLOGY_REQUEST_CHANGE\n");
343  break;
344  case AST_CONTROL_STREAM_TOPOLOGY_CHANGED:
345  ast_verbose("SubClass: STREAM_TOPOLOGY_CHANGED\n");
346  break;
347  case AST_CONTROL_STREAM_TOPOLOGY_SOURCE_CHANGED:
348  ast_verbose("SubClass: STREAM_TOPOLOGY_SOURCE_CHANGED\n");
349  break;
350  case AST_CONTROL_STREAM_STOP:
351  ast_verbose("SubClass: STREAM_STOP\n");
352  break;
353  case AST_CONTROL_STREAM_SUSPEND:
354  ast_verbose("SubClass: STREAM_SUSPEND\n");
355  break;
356  case AST_CONTROL_STREAM_RESTART:
357  ast_verbose("SubClass: STREAM_RESTART\n");
358  break;
359  case AST_CONTROL_STREAM_REVERSE:
360  ast_verbose("SubClass: STREAM_REVERSE\n");
361  break;
362  case AST_CONTROL_STREAM_FORWARD:
363  ast_verbose("SubClass: STREAM_FORWARD\n");
364  break;
365  case AST_CONTROL_RECORD_CANCEL:
366  ast_verbose("SubClass: RECORD_CANCEL\n");
367  break;
368  case AST_CONTROL_RECORD_STOP:
369  ast_verbose("SubClass: RECORD_STOP\n");
370  break;
371  case AST_CONTROL_RECORD_SUSPEND:
372  ast_verbose("SubClass: RECORD_SUSPEND\n");
373  break;
374  case AST_CONTROL_RECORD_MUTE:
375  ast_verbose("SubClass: RECORD_MUTE\n");
376  break;
377  }
378 
379  if (frame->subclass.integer == -1) {
380  ast_verbose("SubClass: %d\n", frame->subclass.integer);
381  }
382  ast_verbose("Bytes: %d\n", frame->datalen);
383  break;
384  case AST_FRAME_RTCP:
385  ast_verbose("FrameType: RTCP\n");
386  break;
387  case AST_FRAME_NULL:
388  ast_verbose("FrameType: NULL\n");
389  break;
390  case AST_FRAME_IAX:
391  ast_verbose("FrameType: IAX\n");
392  break;
393  case AST_FRAME_TEXT:
394  ast_verbose("FrameType: TXT\n");
395  break;
396  case AST_FRAME_TEXT_DATA:
397  ast_verbose("FrameType: TXT_DATA\n");
398  break;
399  case AST_FRAME_IMAGE:
400  ast_verbose("FrameType: IMAGE\n");
401  break;
402  case AST_FRAME_HTML:
403  ast_verbose("FrameType: HTML\n");
404  break;
405  case AST_FRAME_CNG:
406  ast_verbose("FrameType: CNG\n");
407  break;
408  case AST_FRAME_MODEM:
409  ast_verbose("FrameType: MODEM\n");
410  break;
411  case AST_FRAME_DTMF_BEGIN:
412  ast_verbose("FrameType: DTMF BEGIN\n");
413  ast_verbose("Digit: 0x%02X '%c'\n", (unsigned)frame->subclass.integer,
414  frame->subclass.integer < ' ' ? ' ' : frame->subclass.integer);
415  break;
416  case AST_FRAME_BRIDGE_ACTION:
417  ast_verbose("FrameType: Bridge\n");
418  ast_verbose("SubClass: %d\n", frame->subclass.integer);
419  break;
420  case AST_FRAME_BRIDGE_ACTION_SYNC:
421  ast_verbose("Frametype: Synchronous Bridge\n");
422  ast_verbose("Subclass: %d\n", frame->subclass.integer);
423  break;
424  }
425 
426  ast_verbose("Src: %s\n", ast_strlen_zero(frame->src) ? "NOT PRESENT" : frame->src);
427  ast_verbose("\n");
428 }
429 
430 static struct ast_custom_function frame_trace_function = {
431  .name = "FRAME_TRACE",
432  .write = frame_trace_helper,
433 };
434 
435 static int unload_module(void)
436 {
437  return ast_custom_function_unregister(&frame_trace_function);
438 }
439 
440 static int load_module(void)
441 {
442  int res = ast_custom_function_register(&frame_trace_function);
443  return res ? AST_MODULE_LOAD_DECLINE : AST_MODULE_LOAD_SUCCESS;
444 }
445 
446 AST_MODULE_INFO_STANDARD_EXTENDED(ASTERISK_GPL_KEY, "Frame Trace for internal ast_frame debugging.");
ast_custom_function::name
const char * name
Definition: pbx.h:119
ast_datastore_info::type
const char * type
Definition: datastore.h:32
ast_framehook_interface::version
uint16_t version
Definition: framehook.h:231
ast_framehook_interface
Definition: framehook.h:229
ast_channel_lock
#define ast_channel_lock(chan)
Definition: channel.h:2945
ast_channel
Main Channel structure associated with a channel.
Definition: channel_internal_api.c:73
frame_trace_data
Definition: func_frame_trace.c:99
hook_event_cb
static struct ast_frame * hook_event_cb(struct ast_channel *chan, struct ast_frame *frame, enum ast_framehook_event event, void *data)
Definition: func_frame_trace.c:118
frame_trace_function
static struct ast_custom_function frame_trace_function
Definition: func_frame_trace.c:430
asterisk.h
Asterisk main include file. File version handling, generic pbx functions.
print_frame
static void print_frame(struct ast_frame *frame)
Definition: func_frame_trace.c:213
ARRAY_LEN
#define ARRAY_LEN(a)
Definition: isdn_lib.c:42
load_module
static int load_module(void)
Definition: func_frame_trace.c:440
hook_destroy_cb
static void hook_destroy_cb(void *framedata)
Definition: func_frame_trace.c:113
LOG_WARNING
#define LOG_WARNING
Definition: logger.h:274
ast_framehook_event
ast_framehook_event
These are the types of events that the framehook&#39;s event callback can receive.
Definition: framehook.h:151
type
enum ast_frame_type type
Definition: func_frame_trace.c:81
ast_framehook_detach
int ast_framehook_detach(struct ast_channel *chan, int framehook_id)
Detach an framehook from a channel.
Definition: framehook.c:177
ast_datastore_info
Structure for a data store type.
Definition: datastore.h:31
event
Definition: astman.c:222
ast_control_frame_type
ast_control_frame_type
Internal control frame subtype field values.
Definition: include/asterisk/frame.h:277
ast_assert
#define ast_assert(a)
Definition: utils.h:695
ast_format_get_name
const char * ast_format_get_name(const struct ast_format *format)
Get the name associated with a format.
Definition: format.c:334
ast_verbose
void ast_verbose(const char *fmt,...)
Definition: extconf.c:2207
ast_datastore
Structure for a data store object.
Definition: datastore.h:68
ast_channel_datastore_find
struct ast_datastore * ast_channel_datastore_find(struct ast_channel *chan, const struct ast_datastore_info *info, const char *uid)
Find a datastore on a channel.
Definition: channel.c:2404
NULL
#define NULL
Definition: resample.c:96
value
int value
Definition: syslog.c:37
frame_trace_data::list_type
int list_type
Definition: func_frame_trace.c:100
frametype2str
static struct @209 frametype2str[]
ast_custom_function_unregister
int ast_custom_function_unregister(struct ast_custom_function *acf)
Unregister a custom function.
Definition: pbx_functions.c:273
ast_datastore_free
int ast_datastore_free(struct ast_datastore *datastore)
Free a data store object.
Definition: datastore.c:68
ast_frame::subclass
struct ast_frame_subclass subclass
Definition: include/asterisk/frame.h:169
show_frame
static void show_frame(struct video_desc *env, int out)
Definition: console_gui.c:98
ast_strlen_zero
#define ast_strlen_zero(foo)
Definition: strings.h:52
ast_framehook_attach
int ast_framehook_attach(struct ast_channel *chan, struct ast_framehook_interface *i)
Attach an framehook onto a channel for frame interception.
Definition: framehook.c:132
datastore_destroy_cb
static void datastore_destroy_cb(void *data)
Definition: func_frame_trace.c:104
ast_frame_subclass::integer
int integer
Definition: include/asterisk/frame.h:152
ast_log
#define ast_log
Definition: astobj2.c:42
channel.h
General Asterisk PBX channel definitions.
frame_trace_helper
static int frame_trace_helper(struct ast_channel *chan, const char *cmd, char *data, const char *value)
Definition: func_frame_trace.c:149
ast_frame::src
const char * src
Definition: include/asterisk/frame.h:181
ast_custom_function
Data structure associated with a custom dialplan function.
Definition: pbx.h:118
ast_frame::datalen
int datalen
Definition: include/asterisk/frame.h:171
ast_framehook_interface::data
void * data
Definition: framehook.h:255
pbx.h
Core PBX routines and definitions.
ast_frame_type
ast_frame_type
Frame types.
Definition: include/asterisk/frame.h:97
frame_trace_data::values
int values[ARRAY_LEN(frametype2str)]
Definition: func_frame_trace.c:101
AST_MODULE_INFO_STANDARD_EXTENDED
AST_MODULE_INFO_STANDARD_EXTENDED(ASTERISK_GPL_KEY, "Frame Trace for internal ast_frame debugging.")
AST_FRAMEHOOK_INTERFACE_VERSION
#define AST_FRAMEHOOK_INTERFACE_VERSION
Definition: framehook.h:227
strcasestr
char * strcasestr(const char *, const char *)
ast_channel_unlock
#define ast_channel_unlock(chan)
Definition: channel.h:2946
ast_free
#define ast_free(a)
Definition: astmm.h:182
ast_calloc
#define ast_calloc(num, len)
A wrapper for calloc()
Definition: astmm.h:204
AST_MODULE_LOAD_DECLINE
Module has failed to load, may be in an inconsistent state.
Definition: module.h:78
str
const char * str
Definition: func_frame_trace.c:82
framehook.h
FrameHook Architecture.
ast_datastore::data
void * data
Definition: datastore.h:70
ast_channel_name
const char * ast_channel_name(const struct ast_channel *chan)
ast_frame
Data structure associated with a single frame of data.
Definition: include/asterisk/frame.h:165
ast_datastore_alloc
#define ast_datastore_alloc(info, uid)
Definition: datastore.h:89
ast_frame::data
union ast_frame::@263 data
id
enum queue_result id
Definition: app_queue.c:1507
ast_frame::frametype
enum ast_frame_type frametype
Definition: include/asterisk/frame.h:167
ast_frame_subclass::format
struct ast_format * format
Definition: include/asterisk/frame.h:155
ASTERISK_GPL_KEY
#define ASTERISK_GPL_KEY
The text the key() function should return.
Definition: module.h:46
unload_module
static int unload_module(void)
Definition: func_frame_trace.c:435
module.h
Asterisk module definitions.
frame_trace_datastore
static const struct ast_datastore_info frame_trace_datastore
Definition: func_frame_trace.c:108
ast_channel_datastore_add
int ast_channel_datastore_add(struct ast_channel *chan, struct ast_datastore *datastore)
Add a datastore to a channel.
Definition: channel.c:2390
ast_frame::len
long len
Definition: include/asterisk/frame.h:193
ast_channel_datastore_remove
int ast_channel_datastore_remove(struct ast_channel *chan, struct ast_datastore *datastore)
Remove a datastore from a channel.
Definition: channel.c:2399
ast_custom_function_register
#define ast_custom_function_register(acf)
Register a custom function.
Definition: pbx.h:1508
ast_frame::samples
int samples
Definition: include/asterisk/frame.h:173
Generated on Sun Aug 8 2021 19:43:46 for Asterisk - The Open Source Telephony Project by   doxygen 1.8.13