Asterisk - The Open Source Telephony Project  21.4.1
app_waitforsilence.c
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2005, Digium, Inc.
5  *
6  * WaitForSilence Application by David C. Troy <dave@popvox.com>
7  * Version 1.11 2006-06-29
8  *
9  * Mark Spencer <markster@digium.com>
10  *
11  * See http://www.asterisk.org for more information about
12  * the Asterisk project. Please do not directly contact
13  * any of the maintainers of this project for assistance;
14  * the project provides a web site, mailing lists and IRC
15  * channels for your use.
16  *
17  * This program is free software, distributed under the terms of
18  * the GNU General Public License Version 2. See the LICENSE file
19  * at the top of the source tree.
20  */
21 
22 /*! \file
23  *
24  * \brief Wait for Silence
25  * - Waits for up to 'x' milliseconds of silence, 'y' times \n
26  *
27  * \author David C. Troy <dave@popvox.com>
28  *
29  * \brief Wait For Noise
30  * The same as Wait For Silence but listenes noise on the chennel that is above \n
31  * the pre-configured silence threshold from dsp.conf
32  *
33  * \author Philipp Skadorov <skadorov@yahoo.com>
34  *
35  * \ingroup applications
36  */
37 
38 /*** MODULEINFO
39  <support_level>extended</support_level>
40  ***/
41 
42 #include "asterisk.h"
43 
44 #include "asterisk/app.h"
45 #include "asterisk/file.h"
46 #include "asterisk/channel.h"
47 #include "asterisk/pbx.h"
48 #include "asterisk/dsp.h"
49 #include "asterisk/module.h"
50 #include "asterisk/format_cache.h"
51 
52 /*** DOCUMENTATION
53  <application name="WaitForSilence" language="en_US">
54  <synopsis>
55  Waits for a specified amount of silence.
56  </synopsis>
57  <syntax>
58  <parameter name="silencerequired">
59  <para>If not specified, defaults to <literal>1000</literal> milliseconds.</para>
60  </parameter>
61  <parameter name="iterations">
62  <para>If not specified, defaults to <literal>1</literal>.</para>
63  </parameter>
64  <parameter name="timeout">
65  <para>Is specified only to avoid an infinite loop in cases where silence is never achieved.</para>
66  </parameter>
67  </syntax>
68  <description>
69  <para>Waits for up to <replaceable>silencerequired</replaceable> milliseconds of silence,
70  <replaceable>iterations</replaceable> times. An optional <replaceable>timeout</replaceable>
71  specified the number of seconds to return after, even if we do not receive the specified amount of silence.
72  Use <replaceable>timeout</replaceable> with caution, as it may defeat the purpose of this application, which
73  is to wait indefinitely until silence is detected on the line. This is particularly useful for reverse-911-type
74  call broadcast applications where you need to wait for an answering machine to complete its spiel before
75  playing a message.</para>
76  <para>Typically you will want to include two or more calls to WaitForSilence when dealing with an answering
77  machine; first waiting for the spiel to finish, then waiting for the beep, etc.</para>
78  <example title="Wait for half a second of silence, twice">
79  same => n,WaitForSilence(500,2)
80  </example>
81  <example title="Wait for one second of silence, once">
82  same => n,WaitForSilence(1000)
83  </example>
84  <example title="Wait for 300 ms of silence, 3 times, and returns after 10 seconds, even if no silence detected">
85  same => n,WaitForSilence(300,3,10)
86  </example>
87  <para>Sets the channel variable <variable>WAITSTATUS</variable> to one of these values:</para>
88  <variablelist>
89  <variable name="WAITSTATUS">
90  <value name="SILENCE">
91  if exited with silence detected.
92  </value>
93  <value name="TIMEOUT">
94  if exited without silence detected after timeout.
95  </value>
96  </variable>
97  </variablelist>
98  </description>
99  <see-also>
100  <ref type="application">WaitForNoise</ref>
101  </see-also>
102  </application>
103  <application name="WaitForNoise" language="en_US">
104  <synopsis>
105  Waits for a specified amount of noise.
106  </synopsis>
107  <syntax>
108  <parameter name="noiserequired">
109  <para>If not specified, defaults to <literal>1000</literal> milliseconds.</para>
110  </parameter>
111  <parameter name="iterations">
112  <para>If not specified, defaults to <literal>1</literal>.</para>
113  </parameter>
114  <parameter name="timeout">
115  <para>Is specified only to avoid an infinite loop in cases where silence is never achieved.</para>
116  </parameter>
117  </syntax>
118  <description>
119  <para>Waits for up to <replaceable>noiserequired</replaceable> milliseconds of noise,
120  <replaceable>iterations</replaceable> times. An optional <replaceable>timeout</replaceable>
121  specified the number of seconds to return after, even if we do not receive the specified amount of noise.
122  Use <replaceable>timeout</replaceable> with caution, as it may defeat the purpose of this application, which
123  is to wait indefinitely until noise is detected on the line.</para>
124  </description>
125  <see-also>
126  <ref type="application">WaitForSilence</ref>
127  </see-also>
128  </application>
129  ***/
130 
131 static char *app_silence = "WaitForSilence";
132 static char *app_noise = "WaitForNoise";
133 
134 struct wait_type {
135  const char *name;
136  const char *status;
137  int stop_on_frame_timeout;
138  int (*func)(struct ast_dsp *, struct ast_frame *, int *);
139 };
140 
141 static const struct wait_type wait_for_silence = {
142  .name = "silence",
143  .status = "SILENCE",
144  .stop_on_frame_timeout = 1,
145  .func = ast_dsp_silence,
146 };
147 
148 static const struct wait_type wait_for_noise = {
149  .name = "noise",
150  .status = "NOISE",
151  .stop_on_frame_timeout = 0,
152  .func = ast_dsp_noise,
153 };
154 
155 static int do_waiting(struct ast_channel *chan, int timereqd, time_t waitstart, int timeout, const struct wait_type *wait_for)
156 {
157  RAII_VAR(struct ast_format *, rfmt, NULL, ao2_cleanup);
158  int res;
159  struct ast_dsp *sildet;
160 
161  rfmt = ao2_bump(ast_channel_readformat(chan));
162  if ((res = ast_set_read_format(chan, ast_format_slin)) < 0) {
163  ast_log(LOG_WARNING, "Unable to set channel to linear mode, giving up\n");
164  return -1;
165  }
166 
167  /* Create the silence detector */
168  if (!(sildet = ast_dsp_new())) {
169  ast_log(LOG_WARNING, "Unable to create silence detector\n");
170  return -1;
171  }
173 
174  for (;;) {
175  int dsptime = 0;
176 
177  res = ast_waitfor(chan, timereqd);
178 
179  /* Must have gotten a hangup; let's exit */
180  if (res < 0) {
181  pbx_builtin_setvar_helper(chan, "WAITSTATUS", "HANGUP");
182  break;
183  }
184 
185  /* We waited and got no frame; sounds like digital silence or a muted digital channel */
186  if (res == 0) {
187  if (wait_for->stop_on_frame_timeout) {
188  dsptime = timereqd;
189  }
190  } else {
191  /* Looks like we did get a frame, so let's check it out */
192  struct ast_frame *f = ast_read(chan);
193  if (!f) {
194  pbx_builtin_setvar_helper(chan, "WAITSTATUS", "HANGUP");
195  break;
196  }
197  if (f->frametype == AST_FRAME_VOICE) {
198  wait_for->func(sildet, f, &dsptime);
199  }
200  ast_frfree(f);
201  }
202 
203  ast_debug(1, "Got %dms of %s < %dms required\n", dsptime, wait_for->name, timereqd);
204 
205  if (dsptime >= timereqd) {
206  ast_verb(3, "Exiting with %dms of %s >= %dms required\n", dsptime, wait_for->name, timereqd);
207  pbx_builtin_setvar_helper(chan, "WAITSTATUS", wait_for->status);
208  ast_debug(1, "WAITSTATUS was set to %s\n", wait_for->status);
209  res = 1;
210  break;
211  }
212 
213  if (timeout && difftime(time(NULL), waitstart) >= timeout) {
214  pbx_builtin_setvar_helper(chan, "WAITSTATUS", "TIMEOUT");
215  ast_debug(1, "WAITSTATUS was set to TIMEOUT\n");
216  res = 0;
217  break;
218  }
219  }
220 
221  if (rfmt && ast_set_read_format(chan, rfmt)) {
222  ast_log(LOG_WARNING, "Unable to restore format %s to channel '%s'\n", ast_format_get_name(rfmt), ast_channel_name(chan));
223  }
224 
225  ast_dsp_free(sildet);
226  return res;
227 }
228 
229 static int waitfor_exec(struct ast_channel *chan, const char *data, const struct wait_type *wait_for)
230 {
231  int res = 1;
232  int timereqd = 1000;
233  int timeout = 0;
234  int iterations = 1, i;
235  time_t waitstart;
236  char *parse;
237  struct ast_silence_generator *silgen = NULL;
238 
240  AST_APP_ARG(timereqd);
241  AST_APP_ARG(iterations);
242  AST_APP_ARG(timeout);
243  );
244 
245  parse = ast_strdupa(data);
246  AST_STANDARD_APP_ARGS(args, parse);
247 
248  if (!ast_strlen_zero(args.timereqd)) {
249  if (sscanf(args.timereqd, "%30d", &timereqd) != 1 || timereqd < 0) {
250  ast_log(LOG_ERROR, "Argument '%srequired' must be an integer greater than or equal to zero.\n",
251  wait_for->name);
252  return -1;
253  }
254  }
255 
256  if (!ast_strlen_zero(args.iterations)) {
257  if (sscanf(args.iterations, "%30d", &iterations) != 1 || iterations < 1) {
258  ast_log(LOG_ERROR, "Argument 'iterations' must be an integer greater than 0.\n");
259  return -1;
260  }
261  }
262 
263  if (!ast_strlen_zero(args.timeout)) {
264  if (sscanf(args.timeout, "%30d", &timeout) != 1 || timeout < 0) {
265  ast_log(LOG_ERROR, "Argument 'timeout' must be an integer greater than or equal to zero.\n");
266  return -1;
267  }
268  }
269 
270  if (ast_channel_state(chan) != AST_STATE_UP) {
271  ast_answer(chan); /* Answer the channel */
272  }
273 
274  ast_verb(3, "Waiting %d time(s) for %dms of %s with %ds timeout\n",
275  iterations, timereqd, wait_for->name, timeout);
276 
277  if (ast_opt_transmit_silence) {
279  }
280 
281  time(&waitstart);
282  for (i = 0; i < iterations && res == 1; i++) {
283  res = do_waiting(chan, timereqd, waitstart, timeout, wait_for);
284  }
285 
286  if (silgen) {
288  }
289 
290  return res > 0 ? 0 : res;
291 }
292 
293 static int waitforsilence_exec(struct ast_channel *chan, const char *data)
294 {
295  return waitfor_exec(chan, data, &wait_for_silence);
296 }
297 
298 static int waitfornoise_exec(struct ast_channel *chan, const char *data)
299 {
300  return waitfor_exec(chan, data, &wait_for_noise);
301 }
302 
303 static int unload_module(void)
304 {
305  int res;
306  res = ast_unregister_application(app_silence);
307  res |= ast_unregister_application(app_noise);
308 
309  return res;
310 }
311 
312 static int load_module(void)
313 {
314  int res;
315 
316  res = ast_register_application_xml(app_silence, waitforsilence_exec);
317  res |= ast_register_application_xml(app_noise, waitfornoise_exec);
318  return res;
319 }
320 
321 AST_MODULE_INFO_STANDARD_EXTENDED(ASTERISK_GPL_KEY, "Wait For Silence/Noise");
Main Channel structure associated with a channel.
Asterisk main include file. File version handling, generic pbx functions.
Convenient Signal Processing routines.
#define AST_STANDARD_APP_ARGS(args, parse)
Performs the 'standard' argument separation process for an application.
struct ast_dsp * ast_dsp_new(void)
Allocates a new dsp, assumes 8khz for internal sample rate.
Definition: dsp.c:1758
struct ast_frame * ast_read(struct ast_channel *chan)
Reads a frame.
Definition: channel.c:4257
ast_channel_state
ast_channel states
Definition: channelstate.h:35
Definition of a media format.
Definition: format.c:43
const char * ast_format_get_name(const struct ast_format *format)
Get the name associated with a format.
Definition: format.c:334
Generic File Format Support. Should be included by clients of the file handling routines. File service providers should instead include mod_format.h.
int ast_unregister_application(const char *app)
Unregister an application.
Definition: pbx_app.c:392
#define ao2_bump(obj)
Bump refcount on an AO2 object by one, returning the object.
Definition: astobj2.h:480
General Asterisk PBX channel definitions.
int ast_set_read_format(struct ast_channel *chan, struct ast_format *format)
Sets read format on channel chan.
Definition: channel.c:5762
Definition: dsp.c:407
#define ast_strdupa(s)
duplicate a string in memory from the stack
Definition: astmm.h:298
#define ast_debug(level,...)
Log a DEBUG message.
Core PBX routines and definitions.
void ast_dsp_set_threshold(struct ast_dsp *dsp, int threshold)
Set the minimum average magnitude threshold to determine talking by the DSP.
Definition: dsp.c:1788
struct ast_silence_generator * ast_channel_start_silence_generator(struct ast_channel *chan)
Starts a silence generator on the given channel.
Definition: channel.c:8164
void ast_channel_stop_silence_generator(struct ast_channel *chan, struct ast_silence_generator *state)
Stops a previously-started silence generator on the given channel.
Definition: channel.c:8210
union ast_frame::@224 data
int pbx_builtin_setvar_helper(struct ast_channel *chan, const char *name, const char *value)
Add a variable to the channel variable stack, removing the most recently set value for the same name...
int ast_dsp_silence(struct ast_dsp *dsp, struct ast_frame *f, int *totalsilence)
Process the audio frame for silence.
Definition: dsp.c:1488
int ast_waitfor(struct ast_channel *chan, int ms)
Wait for input on a channel.
Definition: channel.c:3162
int ast_answer(struct ast_channel *chan)
Answer a channel.
Definition: channel.c:2805
Data structure associated with a single frame of data.
enum ast_frame_type frametype
#define ASTERISK_GPL_KEY
The text the key() function should return.
Definition: module.h:46
struct ast_format * ast_format_slin
Built-in cached signed linear 8kHz format.
Definition: format_cache.c:41
int ast_dsp_get_threshold_from_settings(enum threshold which)
Get silence threshold from dsp.conf.
Definition: dsp.c:2009
Asterisk module definitions.
#define RAII_VAR(vartype, varname, initval, dtor)
Declare a variable that will call a destructor function when it goes out of scope.
Definition: utils.h:941
#define AST_DECLARE_APP_ARGS(name, arglist)
Declare a structure to hold an application's arguments.
Application convenience functions, designed to give consistent look and feel to Asterisk apps...
#define ast_register_application_xml(app, execute)
Register an application using XML documentation.
Definition: module.h:640
Media Format Cache API.
int ast_dsp_noise(struct ast_dsp *dsp, struct ast_frame *f, int *totalnoise)
Process the audio frame for noise.
Definition: dsp.c:1493
#define AST_APP_ARG(name)
Define an application argument.