e8497f7caeefc74442eec01896ea50ad5d12530f
[asterisk/asterisk.git] / res / res_agi.c
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2006, Digium, Inc.
5  *
6  * Mark Spencer <markster@digium.com>
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 AGI - the Asterisk Gateway Interface
22  *
23  * \author Mark Spencer <markster@digium.com>
24  *
25  */
26
27 /*** MODULEINFO
28         <support_level>core</support_level>
29  ***/
30
31 #include "asterisk.h"
32
33 #include <math.h>
34 #include <signal.h>
35 #include <sys/time.h>
36 #include <sys/wait.h>
37 #include <sys/stat.h>
38 #include <pthread.h>
39
40 #include "asterisk/paths.h"     /* use many ast_config_AST_*_DIR */
41 #include "asterisk/network.h"
42 #include "asterisk/file.h"
43 #include "asterisk/channel.h"
44 #include "asterisk/pbx.h"
45 #include "asterisk/module.h"
46 #include "asterisk/astdb.h"
47 #include "asterisk/callerid.h"
48 #include "asterisk/cli.h"
49 #include "asterisk/image.h"
50 #include "asterisk/say.h"
51 #include "asterisk/app.h"
52 #include "asterisk/dsp.h"
53 #include "asterisk/musiconhold.h"
54 #include "asterisk/utils.h"
55 #include "asterisk/lock.h"
56 #include "asterisk/strings.h"
57 #include "asterisk/manager.h"
58 #include "asterisk/ast_version.h"
59 #include "asterisk/speech.h"
60 #include "asterisk/manager.h"
61 #include "asterisk/term.h"
62 #include "asterisk/xmldoc.h"
63 #include "asterisk/srv.h"
64 #include "asterisk/test.h"
65 #include "asterisk/netsock2.h"
66 #include "asterisk/stasis_channels.h"
67 #include "asterisk/stasis_message_router.h"
68 #include "asterisk/format_cache.h"
69
70 #define AST_API_MODULE
71 #include "asterisk/agi.h"
72
73 /*** DOCUMENTATION
74         <agi name="answer" language="en_US">
75                 <synopsis>
76                         Answer channel
77                 </synopsis>
78                 <syntax />
79                 <description>
80                         <para>Answers channel if not already in answer state. Returns <literal>-1</literal> on
81                         channel failure, or <literal>0</literal> if successful.</para>
82                 </description>
83                 <see-also>
84                         <ref type="agi">hangup</ref>
85                         <ref type="application">AGI</ref>
86                 </see-also>
87         </agi>
88         <agi name="asyncagi break" language="en_US">
89                 <synopsis>
90                         Interrupts Async AGI
91                 </synopsis>
92                 <syntax />
93                 <description>
94                         <para>Interrupts expected flow of Async AGI commands and returns control to previous source
95                         (typically, the PBX dialplan).</para>
96                 </description>
97                 <see-also>
98                         <ref type="agi">hangup</ref>
99                         <ref type="application">AGI</ref>
100                 </see-also>
101         </agi>
102         <agi name="channel status" language="en_US">
103                 <synopsis>
104                         Returns status of the connected channel.
105                 </synopsis>
106                 <syntax>
107                         <parameter name="channelname" />
108                 </syntax>
109                 <description>
110                         <para>Returns the status of the specified <replaceable>channelname</replaceable>.
111                         If no channel name is given then returns the status of the current channel.</para>
112                         <para>Return values:</para>
113                         <enumlist>
114                                 <enum name="0">
115                                         <para>Channel is down and available.</para>
116                                 </enum>
117                                 <enum name="1">
118                                         <para>Channel is down, but reserved.</para>
119                                 </enum>
120                                 <enum name="2">
121                                         <para>Channel is off hook.</para>
122                                 </enum>
123                                 <enum name="3">
124                                         <para>Digits (or equivalent) have been dialed.</para>
125                                 </enum>
126                                 <enum name="4">
127                                         <para>Line is ringing.</para>
128                                 </enum>
129                                 <enum name="5">
130                                         <para>Remote end is ringing.</para>
131                                 </enum>
132                                 <enum name="6">
133                                         <para>Line is up.</para>
134                                 </enum>
135                                 <enum name="7">
136                                         <para>Line is busy.</para>
137                                 </enum>
138                         </enumlist>
139                 </description>
140                 <see-also>
141                         <ref type="application">AGI</ref>
142                 </see-also>
143         </agi>
144         <agi name="control stream file" language="en_US">
145                 <synopsis>
146                         Sends audio file on channel and allows the listener to control the stream.
147                 </synopsis>
148                 <syntax>
149                         <parameter name="filename" required="true">
150                                 <para>The file extension must not be included in the filename.</para>
151                         </parameter>
152                         <parameter name="escape_digits" required="true" />
153                         <parameter name="skipms" />
154                         <parameter name="ffchar">
155                                 <para>Defaults to <literal>#</literal></para>
156                         </parameter>
157                         <parameter name="rewchr">
158                                 <para>Defaults to <literal>*</literal></para>
159                         </parameter>
160                         <parameter name="pausechr" />
161                         <parameter name="offsetms">
162                                 <para>Offset, in milliseconds, to start the audio playback</para>
163                         </parameter>
164                 </syntax>
165                 <description>
166                         <para>Send the given file, allowing playback to be controlled by the given
167                         digits, if any. Use double quotes for the digits if you wish none to be
168                         permitted. If offsetms is provided then the audio will seek to offsetms
169                         before play starts. Returns <literal>0</literal> if playback completes without a digit
170                         being pressed, or the ASCII numerical value of the digit if one was pressed,
171                         or <literal>-1</literal> on error or if the channel was disconnected. Returns the
172                         position where playback was terminated as endpos.</para>
173
174                         <para>It sets the following channel variables upon completion:</para>
175                         <variablelist>
176                                 <variable name="CPLAYBACKSTATUS">
177                                         <para>Contains the status of the attempt as a text string</para>
178                                         <value name="SUCCESS" />
179                                         <value name="USERSTOPPED" />
180                                         <value name="REMOTESTOPPED" />
181                                         <value name="ERROR" />
182                                 </variable>
183                                 <variable name="CPLAYBACKOFFSET">
184                                         <para>Contains the offset in ms into the file where playback
185                                         was at when it stopped. <literal>-1</literal> is end of file.</para>
186                                 </variable>
187                                 <variable name="CPLAYBACKSTOPKEY">
188                                         <para>If the playback is stopped by the user this variable contains
189                                         the key that was pressed.</para>
190                                 </variable>
191                         </variablelist>
192                 </description>
193                 <see-also>
194                         <ref type="agi">get option</ref>
195                         <ref type="agi">control stream file</ref>
196                         <ref type="application">AGI</ref>
197                 </see-also>
198         </agi>
199         <agi name="database del" language="en_US">
200                 <synopsis>
201                         Removes database key/value
202                 </synopsis>
203                 <syntax>
204                         <parameter name="family" required="true" />
205                         <parameter name="key" required="true" />
206                 </syntax>
207                 <description>
208                         <para>Deletes an entry in the Asterisk database for a given
209                         <replaceable>family</replaceable> and <replaceable>key</replaceable>.</para>
210                         <para>Returns <literal>1</literal> if successful, <literal>0</literal>
211                         otherwise.</para>
212                 </description>
213                 <see-also>
214                         <ref type="agi">database get</ref>
215                         <ref type="agi">database put</ref>
216                         <ref type="agi">database deltree</ref>
217                         <ref type="application">AGI</ref>
218                 </see-also>
219         </agi>
220         <agi name="database deltree" language="en_US">
221                 <synopsis>
222                         Removes database keytree/value
223                 </synopsis>
224                 <syntax>
225                         <parameter name="family" required="true" />
226                         <parameter name="keytree" />
227                 </syntax>
228                 <description>
229                         <para>Deletes a <replaceable>family</replaceable> or specific <replaceable>keytree</replaceable>
230                         within a <replaceable>family</replaceable> in the Asterisk database.</para>
231                         <para>Returns <literal>1</literal> if successful, <literal>0</literal> otherwise.</para>
232                 </description>
233                 <see-also>
234                         <ref type="agi">database get</ref>
235                         <ref type="agi">database put</ref>
236                         <ref type="agi">database del</ref>
237                         <ref type="application">AGI</ref>
238                 </see-also>
239         </agi>
240         <agi name="database get" language="en_US">
241                 <synopsis>
242                         Gets database value
243                 </synopsis>
244                 <syntax>
245                         <parameter name="family" required="true" />
246                         <parameter name="key" required="true" />
247                 </syntax>
248                 <description>
249                         <para>Retrieves an entry in the Asterisk database for a given <replaceable>family</replaceable>
250                         and <replaceable>key</replaceable>.</para>
251                         <para>Returns <literal>0</literal> if <replaceable>key</replaceable> is not set.
252                         Returns <literal>1</literal> if <replaceable>key</replaceable> is set and returns the variable
253                         in parenthesis.</para>
254                         <para>Example return code: 200 result=1 (testvariable)</para>
255                 </description>
256                 <see-also>
257                         <ref type="agi">database put</ref>
258                         <ref type="agi">database del</ref>
259                         <ref type="agi">database deltree</ref>
260                         <ref type="application">AGI</ref>
261                 </see-also>
262         </agi>
263         <agi name="database put" language="en_US">
264                 <synopsis>
265                         Adds/updates database value
266                 </synopsis>
267                 <syntax>
268                         <parameter name="family" required="true" />
269                         <parameter name="key" required="true" />
270                         <parameter name="value" required="true" />
271                 </syntax>
272                 <description>
273                         <para>Adds or updates an entry in the Asterisk database for a given
274                         <replaceable>family</replaceable>, <replaceable>key</replaceable>, and
275                         <replaceable>value</replaceable>.</para>
276                         <para>Returns <literal>1</literal> if successful, <literal>0</literal> otherwise.</para>
277                 </description>
278                 <see-also>
279                         <ref type="agi">database get</ref>
280                         <ref type="agi">database del</ref>
281                         <ref type="agi">database deltree</ref>
282                         <ref type="application">AGI</ref>
283                 </see-also>
284         </agi>
285         <agi name="exec" language="en_US">
286                 <synopsis>
287                         Executes a given Application
288                 </synopsis>
289                 <syntax>
290                         <parameter name="application" required="true" />
291                         <parameter name="options" required="true" />
292                 </syntax>
293                 <description>
294                         <para>Executes <replaceable>application</replaceable> with given
295                         <replaceable>options</replaceable>.</para>
296                         <para>Returns whatever the <replaceable>application</replaceable> returns, or
297                         <literal>-2</literal> on failure to find <replaceable>application</replaceable>.</para>
298                 </description>
299                 <see-also>
300                         <ref type="application">AGI</ref>
301                 </see-also>
302         </agi>
303         <agi name="get data" language="en_US">
304                 <synopsis>
305                         Prompts for DTMF on a channel
306                 </synopsis>
307                 <syntax>
308                         <parameter name="file" required="true" />
309                         <parameter name="timeout" />
310                         <parameter name="maxdigits" />
311                 </syntax>
312                 <description>
313                         <para>Stream the given <replaceable>file</replaceable>, and receive DTMF data.</para>
314                         <para>Returns the digits received from the channel at the other end.</para>
315                 </description>
316                 <see-also>
317                         <ref type="application">AGI</ref>
318                 </see-also>
319         </agi>
320         <agi name="get full variable" language="en_US">
321                 <synopsis>
322                         Evaluates a channel expression
323                 </synopsis>
324                 <syntax>
325                         <parameter name="variablename" required="true" />
326                         <parameter name="channel name" />
327                 </syntax>
328                 <description>
329                         <para>Returns <literal>0</literal> if <replaceable>variablename</replaceable> is not set
330                         or channel does not exist. Returns <literal>1</literal> if <replaceable>variablename</replaceable>
331                         is set and returns the variable in parenthesis. Understands complex variable names and builtin
332                         variables, unlike GET VARIABLE.</para>
333                         <para>Example return code: 200 result=1 (testvariable)</para>
334                 </description>
335                 <see-also>
336                         <ref type="agi">get variable</ref>
337                         <ref type="agi">set variable</ref>
338                         <ref type="application">AGI</ref>
339                 </see-also>
340         </agi>
341         <agi name="get option" language="en_US">
342                 <synopsis>
343                         Stream file, prompt for DTMF, with timeout.
344                 </synopsis>
345                 <syntax>
346                         <parameter name="filename" required="true" />
347                         <parameter name="escape_digits" required="true" />
348                         <parameter name="timeout" />
349                 </syntax>
350                 <description>
351                         <para>Behaves similar to STREAM FILE but used with a timeout option.</para>
352                 </description>
353                 <see-also>
354                         <ref type="agi">stream file</ref>
355                         <ref type="agi">control stream file</ref>
356                         <ref type="application">AGI</ref>
357                 </see-also>
358         </agi>
359         <agi name="get variable" language="en_US">
360                 <synopsis>
361                         Gets a channel variable.
362                 </synopsis>
363                 <syntax>
364                         <parameter name="variablename" required="true" />
365                 </syntax>
366                 <description>
367                         <para>Returns <literal>0</literal> if <replaceable>variablename</replaceable> is not set.
368                         Returns <literal>1</literal> if <replaceable>variablename</replaceable> is set and returns
369                         the variable in parentheses.</para>
370                         <para>Example return code: 200 result=1 (testvariable)</para>
371                 </description>
372                 <see-also>
373                         <ref type="agi">get full variable</ref>
374                         <ref type="agi">set variable</ref>
375                         <ref type="application">AGI</ref>
376                 </see-also>
377         </agi>
378         <agi name="hangup" language="en_US">
379                 <synopsis>
380                         Hangup a channel.
381                 </synopsis>
382                 <syntax>
383                         <parameter name="channelname" />
384                 </syntax>
385                 <description>
386                         <para>Hangs up the specified channel. If no channel name is given, hangs
387                         up the current channel</para>
388                 </description>
389                 <see-also>
390                         <ref type="application">AGI</ref>
391                 </see-also>
392         </agi>
393         <agi name="noop" language="en_US">
394                 <synopsis>
395                         Does nothing.
396                 </synopsis>
397                 <syntax />
398                 <description>
399                         <para>Does nothing.</para>
400                 </description>
401                 <see-also>
402                         <ref type="application">AGI</ref>
403                 </see-also>
404         </agi>
405         <agi name="receive char" language="en_US">
406                 <synopsis>
407                         Receives one character from channels supporting it.
408                 </synopsis>
409                 <syntax>
410                         <parameter name="timeout" required="true">
411                                 <para>The maximum time to wait for input in milliseconds, or <literal>0</literal>
412                                 for infinite. Most channels</para>
413                         </parameter>
414                 </syntax>
415                 <description>
416                         <para>Receives a character of text on a channel. Most channels do not support
417                         the reception of text. Returns the decimal value of the character
418                         if one is received, or <literal>0</literal> if the channel does not support
419                         text reception. Returns <literal>-1</literal> only on error/hangup.</para>
420                 </description>
421                 <see-also>
422                         <ref type="agi">receive text</ref>
423                         <ref type="application">AGI</ref>
424                 </see-also>
425         </agi>
426         <agi name="receive text" language="en_US">
427                 <synopsis>
428                         Receives text from channels supporting it.
429                 </synopsis>
430                 <syntax>
431                         <parameter name="timeout" required="true">
432                                 <para>The timeout to be the maximum time to wait for input in
433                                 milliseconds, or <literal>0</literal> for infinite.</para>
434                         </parameter>
435                 </syntax>
436                 <description>
437                         <para>Receives a string of text on a channel. Most channels
438                         do not support the reception of text. Returns <literal>-1</literal> for failure
439                         or <literal>1</literal> for success, and the string in parenthesis.</para>
440                 </description>
441                 <see-also>
442                         <ref type="agi">receive char</ref>
443                         <ref type="agi">send text</ref>
444                         <ref type="application">AGI</ref>
445                 </see-also>
446         </agi>
447         <agi name="record file" language="en_US">
448                 <synopsis>
449                         Records to a given file.
450                 </synopsis>
451                 <syntax>
452                         <parameter name="filename" required="true">
453                                 <para>The destination filename of the recorded audio.</para>
454                         </parameter>
455                         <parameter name="format" required="true">
456                                 <para>The audio format in which to save the resulting file.</para>
457                         </parameter>
458                         <parameter name="escape_digits" required="true">
459                                 <para>The DTMF digits that will terminate the recording process.</para>
460                         </parameter>
461                         <parameter name="timeout" required="true">
462                                 <para>The maximum recording time in milliseconds. Set to -1 for no
463                                 limit.</para>
464                         </parameter>
465                         <parameter name="offset_samples">
466                                 <para>Causes the recording to first seek to the specified offset before
467                                 recording begins.</para>
468                         </parameter>
469                         <parameter name="beep">
470                                 <para>Causes Asterisk to play a beep as recording begins. This argument
471                                 can take any value.</para>
472                         </parameter>
473                         <parameter name="s=silence">
474                                 <para>The number of seconds of silence that are permitted before the
475                                 recording is terminated, regardless of the
476                                 <replaceable>escape_digits</replaceable> or <replaceable>timeout</replaceable>
477                                 arguments. If specified, this parameter must be preceded by
478                                 <literal>s=</literal>.</para>
479                         </parameter>
480                 </syntax>
481                 <description>
482                         <para>Record to a file until a given dtmf digit in the sequence is received.
483                         Returns <literal>-1</literal> on hangup or error.  The format will specify what kind of file
484                         will be recorded. The <replaceable>timeout</replaceable> is the maximum record time in
485                         milliseconds, or <literal>-1</literal> for no <replaceable>timeout</replaceable>.
486                         <replaceable>offset samples</replaceable> is optional, and, if provided, will seek
487                         to the offset without exceeding the end of the
488                         file. <replaceable>beep</replaceable> can take any value, and causes Asterisk
489                         to play a beep to the channel that is about to be recorded. <replaceable>silence</replaceable> is
490                         the number of seconds of silence allowed before the function returns despite the
491                         lack of dtmf digits or reaching <replaceable>timeout</replaceable>. <replaceable>silence</replaceable>
492                         value must be preceded by <literal>s=</literal> and is also optional.</para>
493                 </description>
494                 <see-also>
495                         <ref type="application">AGI</ref>
496                 </see-also>
497         </agi>
498         <agi name="say alpha" language="en_US">
499                 <synopsis>
500                         Says a given character string.
501                 </synopsis>
502                 <syntax>
503                         <parameter name="number" required="true" />
504                         <parameter name="escape_digits" required="true" />
505                 </syntax>
506                 <description>
507                         <para>Say a given character string, returning early if any of the given DTMF digits
508                         are received on the channel. Returns <literal>0</literal> if playback completes
509                         without a digit being pressed, or the ASCII numerical value of the digit if one
510                         was pressed or <literal>-1</literal> on error/hangup.</para>
511                 </description>
512                 <see-also>
513                         <ref type="agi">say digits</ref>
514                         <ref type="agi">say number</ref>
515                         <ref type="agi">say phonetic</ref>
516                         <ref type="agi">say date</ref>
517                         <ref type="agi">say time</ref>
518                         <ref type="agi">say datetime</ref>
519                         <ref type="application">AGI</ref>
520                 </see-also>
521         </agi>
522         <agi name="say digits" language="en_US">
523                 <synopsis>
524                         Says a given digit string.
525                 </synopsis>
526                 <syntax>
527                         <parameter name="number" required="true" />
528                         <parameter name="escape_digits" required="true" />
529                 </syntax>
530                 <description>
531                         <para>Say a given digit string, returning early if any of the given DTMF digits
532                         are received on the channel. Returns <literal>0</literal> if playback completes
533                         without a digit being pressed, or the ASCII numerical value of the digit if one
534                         was pressed or <literal>-1</literal> on error/hangup.</para>
535                 </description>
536                 <see-also>
537                         <ref type="agi">say alpha</ref>
538                         <ref type="agi">say number</ref>
539                         <ref type="agi">say phonetic</ref>
540                         <ref type="agi">say date</ref>
541                         <ref type="agi">say time</ref>
542                         <ref type="agi">say datetime</ref>
543                         <ref type="application">AGI</ref>
544                 </see-also>
545         </agi>
546         <agi name="say number" language="en_US">
547                 <synopsis>
548                         Says a given number.
549                 </synopsis>
550                 <syntax>
551                         <parameter name="number" required="true" />
552                         <parameter name="escape_digits" required="true" />
553                         <parameter name="gender" />
554                 </syntax>
555                 <description>
556                         <para>Say a given number, returning early if any of the given DTMF digits
557                         are received on the channel.  Returns <literal>0</literal> if playback
558                         completes without a digit being pressed, or the ASCII numerical value of
559                         the digit if one was pressed or <literal>-1</literal> on error/hangup.</para>
560                 </description>
561                 <see-also>
562                         <ref type="agi">say alpha</ref>
563                         <ref type="agi">say digits</ref>
564                         <ref type="agi">say phonetic</ref>
565                         <ref type="agi">say date</ref>
566                         <ref type="agi">say time</ref>
567                         <ref type="agi">say datetime</ref>
568                         <ref type="application">AGI</ref>
569                 </see-also>
570         </agi>
571         <agi name="say phonetic" language="en_US">
572                 <synopsis>
573                         Says a given character string with phonetics.
574                 </synopsis>
575                 <syntax>
576                         <parameter name="string" required="true" />
577                         <parameter name="escape_digits" required="true" />
578                 </syntax>
579                 <description>
580                         <para>Say a given character string with phonetics, returning early if any of the
581                         given DTMF digits are received on the channel. Returns <literal>0</literal> if
582                         playback completes without a digit pressed, the ASCII numerical value of the digit
583                         if one was pressed, or <literal>-1</literal> on error/hangup.</para>
584                 </description>
585                 <see-also>
586                         <ref type="agi">say alpha</ref>
587                         <ref type="agi">say digits</ref>
588                         <ref type="agi">say number</ref>
589                         <ref type="agi">say date</ref>
590                         <ref type="agi">say time</ref>
591                         <ref type="agi">say datetime</ref>
592                         <ref type="application">AGI</ref>
593                 </see-also>
594         </agi>
595         <agi name="say date" language="en_US">
596                 <synopsis>
597                         Says a given date.
598                 </synopsis>
599                 <syntax>
600                         <parameter name="date" required="true">
601                                 <para>Is number of seconds elapsed since 00:00:00 on January 1, 1970.
602                                 Coordinated Universal Time (UTC).</para>
603                         </parameter>
604                         <parameter name="escape_digits" required="true" />
605                 </syntax>
606                 <description>
607                         <para>Say a given date, returning early if any of the given DTMF digits are
608                         received on the channel. Returns <literal>0</literal> if playback
609                         completes without a digit being pressed, or the ASCII numerical value of the
610                         digit if one was pressed or <literal>-1</literal> on error/hangup.</para>
611                 </description>
612                 <see-also>
613                         <ref type="agi">say alpha</ref>
614                         <ref type="agi">say digits</ref>
615                         <ref type="agi">say number</ref>
616                         <ref type="agi">say phonetic</ref>
617                         <ref type="agi">say time</ref>
618                         <ref type="agi">say datetime</ref>
619                         <ref type="application">AGI</ref>
620                 </see-also>
621         </agi>
622         <agi name="say time" language="en_US">
623                 <synopsis>
624                         Says a given time.
625                 </synopsis>
626                 <syntax>
627                         <parameter name="time" required="true">
628                                 <para>Is number of seconds elapsed since 00:00:00 on January 1, 1970.
629                                 Coordinated Universal Time (UTC).</para>
630                         </parameter>
631                         <parameter name="escape_digits" required="true" />
632                 </syntax>
633                 <description>
634                         <para>Say a given time, returning early if any of the given DTMF digits are
635                         received on the channel. Returns <literal>0</literal> if playback completes
636                         without a digit being pressed, or the ASCII numerical value of the digit if
637                         one was pressed or <literal>-1</literal> on error/hangup.</para>
638                 </description>
639                 <see-also>
640                         <ref type="agi">say alpha</ref>
641                         <ref type="agi">say digits</ref>
642                         <ref type="agi">say number</ref>
643                         <ref type="agi">say phonetic</ref>
644                         <ref type="agi">say date</ref>
645                         <ref type="agi">say datetime</ref>
646                         <ref type="application">AGI</ref>
647                 </see-also>
648         </agi>
649         <agi name="say datetime" language="en_US">
650                 <synopsis>
651                         Says a given time as specified by the format given.
652                 </synopsis>
653                 <syntax>
654                         <parameter name="time" required="true">
655                                 <para>Is number of seconds elapsed since 00:00:00
656                                 on January 1, 1970, Coordinated Universal Time (UTC)</para>
657                         </parameter>
658                         <parameter name="escape_digits" required="true" />
659                         <parameter name="format">
660                                 <para>Is the format the time should be said in. See
661                                 <filename>voicemail.conf</filename> (defaults to <literal>ABdY
662                                 'digits/at' IMp</literal>).</para>
663                         </parameter>
664                         <parameter name="timezone">
665                                 <para>Acceptable values can be found in <filename>/usr/share/zoneinfo</filename>
666                                 Defaults to machine default.</para>
667                         </parameter>
668                 </syntax>
669                 <description>
670                         <para>Say a given time, returning early if any of the given DTMF digits are
671                         received on the channel. Returns <literal>0</literal> if playback
672                         completes without a digit being pressed, or the ASCII numerical value of the
673                         digit if one was pressed or <literal>-1</literal> on error/hangup.</para>
674                 </description>
675                 <see-also>
676                         <ref type="agi">say alpha</ref>
677                         <ref type="agi">say digits</ref>
678                         <ref type="agi">say number</ref>
679                         <ref type="agi">say phonetic</ref>
680                         <ref type="agi">say date</ref>
681                         <ref type="agi">say time</ref>
682                         <ref type="application">AGI</ref>
683                 </see-also>
684         </agi>
685         <agi name="send image" language="en_US">
686                 <synopsis>
687                         Sends images to channels supporting it.
688                 </synopsis>
689                 <syntax>
690                         <parameter name="image" required="true" />
691                 </syntax>
692                 <description>
693                         <para>Sends the given image on a channel. Most channels do not support the
694                         transmission of images. Returns <literal>0</literal> if image is sent, or if
695                         the channel does not support image transmission.  Returns <literal>-1</literal>
696                         only on error/hangup. Image names should not include extensions.</para>
697                 </description>
698                 <see-also>
699                         <ref type="application">AGI</ref>
700                 </see-also>
701         </agi>
702         <agi name="send text" language="en_US">
703                 <synopsis>
704                         Sends text to channels supporting it.
705                 </synopsis>
706                 <syntax>
707                         <parameter name="text to send" required="true">
708                                 <para>Text consisting of greater than one word should be placed
709                                 in quotes since the command only accepts a single argument.</para>
710                         </parameter>
711                 </syntax>
712                 <description>
713                         <para>Sends the given text on a channel. Most channels do not support the
714                         transmission of text. Returns <literal>0</literal> if text is sent, or if the
715                         channel does not support text transmission. Returns <literal>-1</literal> only
716                         on error/hangup.</para>
717                 </description>
718                 <see-also>
719                         <ref type="agi">receive text</ref>
720                         <ref type="application">AGI</ref>
721                 </see-also>
722         </agi>
723         <agi name="set autohangup" language="en_US">
724                 <synopsis>
725                         Autohangup channel in some time.
726                 </synopsis>
727                 <syntax>
728                         <parameter name="time" required="true" />
729                 </syntax>
730                 <description>
731                         <para>Cause the channel to automatically hangup at <replaceable>time</replaceable>
732                         seconds in the future. Of course it can be hungup before then as well. Setting to
733                         <literal>0</literal> will cause the autohangup feature to be disabled on this channel.</para>
734                 </description>
735                 <see-also>
736                         <ref type="application">AGI</ref>
737                 </see-also>
738         </agi>
739         <agi name="set callerid" language="en_US">
740                 <synopsis>
741                         Sets callerid for the current channel.
742                 </synopsis>
743                 <syntax>
744                         <parameter name="number" required="true" />
745                 </syntax>
746                 <description>
747                         <para>Changes the callerid of the current channel.</para>
748                 </description>
749                 <see-also>
750                         <ref type="application">AGI</ref>
751                 </see-also>
752         </agi>
753         <agi name="set context" language="en_US">
754                 <synopsis>
755                         Sets channel context.
756                 </synopsis>
757                 <syntax>
758                         <parameter name="desired context" required="true" />
759                 </syntax>
760                 <description>
761                         <para>Sets the context for continuation upon exiting the application.</para>
762                 </description>
763                 <see-also>
764                         <ref type="agi">set extension</ref>
765                         <ref type="agi">set priority</ref>
766                         <ref type="application">AGI</ref>
767                 </see-also>
768         </agi>
769         <agi name="set extension" language="en_US">
770                 <synopsis>
771                         Changes channel extension.
772                 </synopsis>
773                 <syntax>
774                         <parameter name="new extension" required="true" />
775                 </syntax>
776                 <description>
777                         <para>Changes the extension for continuation upon exiting the application.</para>
778                 </description>
779                 <see-also>
780                         <ref type="agi">set context</ref>
781                         <ref type="agi">set priority</ref>
782                         <ref type="application">AGI</ref>
783                 </see-also>
784         </agi>
785         <agi name="set music" language="en_US">
786                 <synopsis>
787                         Enable/Disable Music on hold generator
788                 </synopsis>
789                 <syntax>
790                         <parameter required="true">
791                                 <enumlist>
792                                         <enum>
793                                                 <parameter name="on" literal="true" required="true" />
794                                         </enum>
795                                         <enum>
796                                                 <parameter name="off" literal="true" required="true" />
797                                         </enum>
798                                 </enumlist>
799                         </parameter>
800                         <parameter name="class" required="true" />
801                 </syntax>
802                 <description>
803                         <para>Enables/Disables the music on hold generator. If <replaceable>class</replaceable>
804                         is not specified, then the <literal>default</literal> music on hold class will be
805                         used. This generator will be stopped automatically when playing a file.</para>
806                         <para>Always returns <literal>0</literal>.</para>
807                 </description>
808                 <see-also>
809                         <ref type="application">AGI</ref>
810                 </see-also>
811         </agi>
812         <agi name="set priority" language="en_US">
813                 <synopsis>
814                         Set channel dialplan priority.
815                 </synopsis>
816                 <syntax>
817                         <parameter name="priority" required="true" />
818                 </syntax>
819                 <description>
820                         <para>Changes the priority for continuation upon exiting the application.
821                         The priority must be a valid priority or label.</para>
822                 </description>
823                 <see-also>
824                         <ref type="agi">set context</ref>
825                         <ref type="agi">set extension</ref>
826                         <ref type="application">AGI</ref>
827                 </see-also>
828         </agi>
829         <agi name="set variable" language="en_US">
830                 <synopsis>
831                         Sets a channel variable.
832                 </synopsis>
833                 <syntax>
834                         <parameter name="variablename" required="true" />
835                         <parameter name="value" required="true" />
836                 </syntax>
837                 <description>
838                         <para>Sets a variable to the current channel.</para>
839                 </description>
840                 <see-also>
841                         <ref type="agi">get variable</ref>
842                         <ref type="agi">get full variable</ref>
843                         <ref type="application">AGI</ref>
844                 </see-also>
845         </agi>
846         <agi name="stream file" language="en_US">
847                 <synopsis>
848                         Sends audio file on channel.
849                 </synopsis>
850                 <syntax>
851                         <parameter name="filename" required="true">
852                                 <para>File name to play. The file extension must not be
853                                 included in the <replaceable>filename</replaceable>.</para>
854                         </parameter>
855                         <parameter name="escape_digits" required="true">
856                                 <para>Use double quotes for the digits if you wish none to be
857                                 permitted.</para>
858                         </parameter>
859                         <parameter name="sample offset">
860                                 <para>If sample offset is provided then the audio will seek to sample
861                                 offset before play starts.</para>
862                         </parameter>
863                 </syntax>
864                 <description>
865                         <para>Send the given file, allowing playback to be interrupted by the given
866                         digits, if any. Returns <literal>0</literal> if playback completes without a digit
867                         being pressed, or the ASCII numerical value of the digit if one was pressed,
868                         or <literal>-1</literal> on error or if the channel was disconnected. If
869                         musiconhold is playing before calling stream file it will be automatically
870                         stopped and will not be restarted after completion.</para>
871                         <para>It sets the following channel variables upon completion:</para>
872                         <variablelist>
873                                 <variable name="PLAYBACKSTATUS">
874                                         <para>The status of the playback attempt as a text string.</para>
875                                         <value name="SUCCESS"/>
876                                         <value name="FAILED"/>
877                                 </variable>
878                         </variablelist>
879                 </description>
880                 <see-also>
881                         <ref type="agi">control stream file</ref>
882                         <ref type="agi">get option</ref>
883                         <ref type="application">AGI</ref>
884                 </see-also>
885         </agi>
886         <agi name="tdd mode" language="en_US">
887                 <synopsis>
888                         Toggles TDD mode (for the deaf).
889                 </synopsis>
890                 <syntax>
891                         <parameter name="boolean" required="true">
892                                 <enumlist>
893                                         <enum name="on" />
894                                         <enum name="off" />
895                                 </enumlist>
896                         </parameter>
897                 </syntax>
898                 <description>
899                         <para>Enable/Disable TDD transmission/reception on a channel. Returns <literal>1</literal> if
900                         successful, or <literal>0</literal> if channel is not TDD-capable.</para>
901                 </description>
902                 <see-also>
903                         <ref type="application">AGI</ref>
904                 </see-also>
905         </agi>
906         <agi name="verbose" language="en_US">
907                 <synopsis>
908                         Logs a message to the asterisk verbose log.
909                 </synopsis>
910                 <syntax>
911                         <parameter name="message" required="true" />
912                         <parameter name="level" required="true" />
913                 </syntax>
914                 <description>
915                         <para>Sends <replaceable>message</replaceable> to the console via verbose
916                         message system. <replaceable>level</replaceable> is the verbose level (1-4).
917                         Always returns <literal>1</literal></para>
918                 </description>
919                 <see-also>
920                         <ref type="application">AGI</ref>
921                 </see-also>
922         </agi>
923         <agi name="wait for digit" language="en_US">
924                 <synopsis>
925                         Waits for a digit to be pressed.
926                 </synopsis>
927                 <syntax>
928                         <parameter name="timeout" required="true" />
929                 </syntax>
930                 <description>
931                         <para>Waits up to <replaceable>timeout</replaceable> milliseconds for channel to
932                         receive a DTMF digit. Returns <literal>-1</literal> on channel failure, <literal>0</literal>
933                         if no digit is received in the timeout, or the numerical value of the ascii of the digit if
934                         one is received. Use <literal>-1</literal> for the <replaceable>timeout</replaceable> value if
935                         you desire the call to block indefinitely.</para>
936                 </description>
937                 <see-also>
938                         <ref type="application">AGI</ref>
939                 </see-also>
940         </agi>
941         <agi name="speech create" language="en_US">
942                 <synopsis>
943                         Creates a speech object.
944                 </synopsis>
945                 <syntax>
946                         <parameter name="engine" required="true" />
947                 </syntax>
948                 <description>
949                         <para>Create a speech object to be used by the other Speech AGI commands.</para>
950                 </description>
951                 <see-also>
952                         <ref type="agi">speech set</ref>
953                         <ref type="agi">speech destroy</ref>
954                         <ref type="agi">speech load grammar</ref>
955                         <ref type="agi">speech unload grammar</ref>
956                         <ref type="agi">speech activate grammar</ref>
957                         <ref type="agi">speech deactivate grammar</ref>
958                         <ref type="agi">speech recognize</ref>
959                         <ref type="application">AGI</ref>
960                 </see-also>
961         </agi>
962         <agi name="speech set" language="en_US">
963                 <synopsis>
964                         Sets a speech engine setting.
965                 </synopsis>
966                 <syntax>
967                         <parameter name="name" required="true" />
968                         <parameter name="value" required="true" />
969                 </syntax>
970                 <description>
971                         <para>Set an engine-specific setting.</para>
972                 </description>
973                 <see-also>
974                         <ref type="agi">speech create</ref>
975                         <ref type="agi">speech destroy</ref>
976                         <ref type="agi">speech load grammar</ref>
977                         <ref type="agi">speech unload grammar</ref>
978                         <ref type="agi">speech activate grammar</ref>
979                         <ref type="agi">speech deactivate grammar</ref>
980                         <ref type="agi">speech recognize</ref>
981                         <ref type="application">AGI</ref>
982                 </see-also>
983         </agi>
984         <agi name="speech destroy" language="en_US">
985                 <synopsis>
986                         Destroys a speech object.
987                 </synopsis>
988                 <syntax>
989                 </syntax>
990                 <description>
991                         <para>Destroy the speech object created by <literal>SPEECH CREATE</literal>.</para>
992                 </description>
993                 <see-also>
994                         <ref type="agi">speech create</ref>
995                         <ref type="agi">speech set</ref>
996                         <ref type="agi">speech load grammar</ref>
997                         <ref type="agi">speech unload grammar</ref>
998                         <ref type="agi">speech activate grammar</ref>
999                         <ref type="agi">speech deactivate grammar</ref>
1000                         <ref type="agi">speech recognize</ref>
1001                         <ref type="application">AGI</ref>
1002                 </see-also>
1003         </agi>
1004         <agi name="speech load grammar" language="en_US">
1005                 <synopsis>
1006                         Loads a grammar.
1007                 </synopsis>
1008                 <syntax>
1009                         <parameter name="grammar name" required="true" />
1010                         <parameter name="path to grammar" required="true" />
1011                 </syntax>
1012                 <description>
1013                         <para>Loads the specified grammar as the specified name.</para>
1014                 </description>
1015                 <see-also>
1016                         <ref type="agi">speech create</ref>
1017                         <ref type="agi">speech set</ref>
1018                         <ref type="agi">speech destroy</ref>
1019                         <ref type="agi">speech unload grammar</ref>
1020                         <ref type="agi">speech activate grammar</ref>
1021                         <ref type="agi">speech deactivate grammar</ref>
1022                         <ref type="agi">speech recognize</ref>
1023                         <ref type="application">AGI</ref>
1024                 </see-also>
1025         </agi>
1026         <agi name="speech unload grammar" language="en_US">
1027                 <synopsis>
1028                         Unloads a grammar.
1029                 </synopsis>
1030                 <syntax>
1031                         <parameter name="grammar name" required="true" />
1032                 </syntax>
1033                 <description>
1034                         <para>Unloads the specified grammar.</para>
1035                 </description>
1036                 <see-also>
1037                         <ref type="agi">speech create</ref>
1038                         <ref type="agi">speech set</ref>
1039                         <ref type="agi">speech destroy</ref>
1040                         <ref type="agi">speech load grammar</ref>
1041                         <ref type="agi">speech activate grammar</ref>
1042                         <ref type="agi">speech deactivate grammar</ref>
1043                         <ref type="agi">speech recognize</ref>
1044                         <ref type="application">AGI</ref>
1045                 </see-also>
1046         </agi>
1047         <agi name="speech activate grammar" language="en_US">
1048                 <synopsis>
1049                         Activates a grammar.
1050                 </synopsis>
1051                 <syntax>
1052                         <parameter name="grammar name" required="true" />
1053                 </syntax>
1054                 <description>
1055                         <para>Activates the specified grammar on the speech object.</para>
1056                 </description>
1057                 <see-also>
1058                         <ref type="agi">speech create</ref>
1059                         <ref type="agi">speech set</ref>
1060                         <ref type="agi">speech destroy</ref>
1061                         <ref type="agi">speech load grammar</ref>
1062                         <ref type="agi">speech unload grammar</ref>
1063                         <ref type="agi">speech deactivate grammar</ref>
1064                         <ref type="agi">speech recognize</ref>
1065                         <ref type="application">AGI</ref>
1066                 </see-also>
1067         </agi>
1068         <agi name="speech deactivate grammar" language="en_US">
1069                 <synopsis>
1070                         Deactivates a grammar.
1071                 </synopsis>
1072                 <syntax>
1073                         <parameter name="grammar name" required="true" />
1074                 </syntax>
1075                 <description>
1076                         <para>Deactivates the specified grammar on the speech object.</para>
1077                 </description>
1078                 <see-also>
1079                         <ref type="agi">speech create</ref>
1080                         <ref type="agi">speech set</ref>
1081                         <ref type="agi">speech destroy</ref>
1082                         <ref type="agi">speech load grammar</ref>
1083                         <ref type="agi">speech unload grammar</ref>
1084                         <ref type="agi">speech activate grammar</ref>
1085                         <ref type="agi">speech recognize</ref>
1086                         <ref type="application">AGI</ref>
1087                 </see-also>
1088         </agi>
1089         <agi name="speech recognize" language="en_US">
1090                 <synopsis>
1091                         Recognizes speech.
1092                 </synopsis>
1093                 <syntax>
1094                         <parameter name="prompt" required="true" />
1095                         <parameter name="timeout" required="true" />
1096                         <parameter name="offset" />
1097                 </syntax>
1098                 <description>
1099                         <para>Plays back given <replaceable>prompt</replaceable> while listening for
1100                         speech and dtmf.</para>
1101                 </description>
1102                 <see-also>
1103                         <ref type="agi">speech create</ref>
1104                         <ref type="agi">speech set</ref>
1105                         <ref type="agi">speech destroy</ref>
1106                         <ref type="agi">speech load grammar</ref>
1107                         <ref type="agi">speech unload grammar</ref>
1108                         <ref type="agi">speech activate grammar</ref>
1109                         <ref type="agi">speech deactivate grammar</ref>
1110                         <ref type="application">AGI</ref>
1111                 </see-also>
1112         </agi>
1113         <application name="AGI" language="en_US">
1114                 <synopsis>
1115                         Executes an AGI compliant application.
1116                 </synopsis>
1117                 <syntax>
1118                         <parameter name="command" required="true">
1119                                 <para>How AGI should be invoked on the channel.</para>
1120                         </parameter>
1121                         <parameter name="args">
1122                                 <para>Arguments to pass to the AGI script or server.</para>
1123                                 <argument name="arg1" required="true" />
1124                                 <argument name="arg2" multiple="yes" />
1125                         </parameter>
1126                 </syntax>
1127                 <description>
1128                         <para>Executes an Asterisk Gateway Interface compliant
1129                         program on a channel. AGI allows Asterisk to launch external programs written
1130                         in any language to control a telephony channel, play audio, read DTMF digits,
1131                         etc. by communicating with the AGI protocol.</para>
1132                         <para>The following variants of AGI exist, and are chosen based on the value
1133                         passed to <replaceable>command</replaceable>:</para>
1134                         <enumlist>
1135                                 <enum name="AGI">
1136                                         <para>The classic variant of AGI, this will launch the script
1137                                         specified by <replaceable>command</replaceable> as a new process.
1138                                         Communication with the script occurs on <literal>stdin</literal> and
1139                                         <literal>stdout</literal>. If the full path to the script is not
1140                                         provided, the <directory>astagidir</directory> specified in
1141                                         <filename>asterisk.conf</filename> will be used.
1142                                         </para>
1143                                 </enum>
1144                                 <enum name="FastAGI">
1145                                         <para>Connect Asterisk to a FastAGI server using a TCP connection.
1146                                         The URI to the FastAGI server should be given in the form
1147                                         <literal>[scheme]://host.domain[:port][/script/name]</literal>,
1148                                         where <replaceable>scheme</replaceable> is either <literal>agi</literal>
1149                                         or <literal>hagi</literal>.</para>
1150                                         <para>In the case of <literal>hagi</literal>, an SRV lookup will be
1151                                         performed to try to connect to a list of FastAGI servers. The hostname in
1152                                         the URI must be prefixed with <literal>_agi._tcp</literal>. prior to the DNS resolution. For
1153                                         example, if you specify the URI <literal>hagi://agi.example.com/foo.agi</literal>
1154                                         the DNS query would be for <literal>_agi._tcp.agi.example.com</literal>. You
1155                                         will need to make sure this resolves correctly.</para>
1156                                 </enum>
1157                                 <enum name="AsyncAGI">
1158                                         <para>Use AMI to control the channel in AGI. AGI commands can be invoked
1159                                         using the <literal>AMI</literal> action, with a variety of AGI specific
1160                                         events passed back over the AMI connection. AsyncAGI should be invoked
1161                                         by passing <literal>agi:async</literal> to the <replaceable>command</replaceable>
1162                                         parameter.</para>
1163                                 </enum>
1164                         </enumlist>
1165                         <note>
1166                         <para>As of <literal>1.6.0</literal>, this channel will
1167                         not stop dialplan execution on hangup inside of this application. Dialplan
1168                         execution will continue normally, even upon hangup until the AGI application
1169                         signals a desire to stop (either by exiting or, in the case of a net script, by
1170                         closing the connection).</para>
1171                         <para>A locally executed AGI script will receive <literal>SIGHUP</literal> on
1172                         hangup from the channel except when using <literal>DeadAGI</literal>
1173                         (or when the channel is already hungup). A fast AGI server will
1174                         correspondingly receive a <literal>HANGUP</literal> inline with the command dialog.
1175                         Both of these signals may be disabled by setting the <variable>AGISIGHUP</variable>
1176                         channel variable to <literal>no</literal> before executing the AGI application.
1177                         Alternatively, if you would like the AGI application to exit immediately
1178                         after a channel hangup is detected, set the <variable>AGIEXITONHANGUP</variable>
1179                         variable to <literal>yes</literal>.</para>
1180                         </note>
1181                         <example title="AGI invocation examples">
1182                                 ; Start the AGI script /tmp/my-cool-script.sh, passing it the contents
1183                                 ; of the channel variable FOO
1184                                 same => n,AGI(/tmp/my-cool-script.sh,${FOO})
1185
1186                                 ; Start the AGI script my-cool-script.sh located in the astagidir
1187                                 ; directory, specified in asterisk.conf
1188                                 same => n,AGI(my-cool-script.sh)
1189
1190                                 ; Connect to the FastAGI server located at 127.0.0.1 and start the script
1191                                 ; awesome-script
1192                                 same => n,AGI(agi://127.0.0.1/awesome-script)
1193
1194                                 ; Start AsyncAGI
1195                                 same => n,AGI(agi:async)
1196                         </example>
1197                         <para>This application sets the following channel variable upon completion:</para>
1198                         <variablelist>
1199                                 <variable name="AGISTATUS">
1200                                         <para>The status of the attempt to the run the AGI script
1201                                         text string, one of:</para>
1202                                         <value name="SUCCESS" />
1203                                         <value name="FAILURE" />
1204                                         <value name="NOTFOUND" />
1205                                         <value name="HANGUP" />
1206                                 </variable>
1207                         </variablelist>
1208                 </description>
1209                 <see-also>
1210                         <ref type="manager">AGI</ref>
1211                         <ref type="managerEvent">AsyncAGIStart</ref>
1212                         <ref type="managerEvent">AsyncAGIEnd</ref>
1213                         <ref type="application">EAGI</ref>
1214                         <ref type="application">DeadAGI</ref>
1215                         <ref type="filename">asterisk.conf</ref>
1216                 </see-also>
1217         </application>
1218         <application name="EAGI" language="en_US">
1219                 <synopsis>
1220                         Executes an EAGI compliant application.
1221                 </synopsis>
1222                 <syntax>
1223                         <xi:include xpointer="xpointer(/docs/application[@name='AGI']/syntax/parameter[@name='command'])" />
1224                         <xi:include xpointer="xpointer(/docs/application[@name='AGI']/syntax/parameter[@name='args'])" />
1225                 </syntax>
1226                 <description>
1227                         <para>Using 'EAGI' provides enhanced AGI, with incoming audio available out of band
1228                         on file descriptor 3. In all other respects, it behaves in the same fashion as
1229                         AGI. See the documentation for the <literal>AGI</literal> dialplan application for
1230                         more information on invoking AGI on a channel.</para>
1231                         <para>This application sets the following channel variable upon completion:</para>
1232                         <xi:include xpointer="xpointer(/docs/application[@name='AGI']/description/variablelist)" />
1233                 </description>
1234                 <see-also>
1235                         <ref type="application">AGI</ref>
1236                         <ref type="application">DeadAGI</ref>
1237                 </see-also>
1238         </application>
1239         <application name="DeadAGI" language="en_US">
1240                 <synopsis>
1241                         Executes AGI on a hungup channel.
1242                 </synopsis>
1243                 <syntax>
1244                         <xi:include xpointer="xpointer(/docs/application[@name='AGI']/syntax/parameter[@name='command'])" />
1245                         <xi:include xpointer="xpointer(/docs/application[@name='AGI']/syntax/parameter[@name='args'])" />
1246                 </syntax>
1247                 <description>
1248                         <warning>
1249                                 <para>This application is deprecated and may be removed in a future version
1250                                 of Asterisk. Use the replacement application <literal>AGI</literal> instead
1251                                 of <literal>DeadAGI</literal>.
1252                                 </para>
1253                         </warning>
1254                         <para>Execute AGI on a 'dead' or hungup channel. See the documentation for the
1255                         <literal>AGI</literal> dialplan application for more information on invoking
1256                         AGI on a channel.</para>
1257                         <para>This application sets the following channel variable upon completion:</para>
1258                         <xi:include xpointer="xpointer(/docs/application[@name='AGI']/description/variablelist)" />
1259                 </description>
1260                 <see-also>
1261                         <ref type="application">AGI</ref>
1262                         <ref type="application">EAGI</ref>
1263                 </see-also>
1264         </application>
1265         <manager name="AGI" language="en_US">
1266                 <synopsis>
1267                         Add an AGI command to execute by Async AGI.
1268                 </synopsis>
1269                 <syntax>
1270                         <xi:include xpointer="xpointer(/docs/manager[@name='Login']/syntax/parameter[@name='ActionID'])" />
1271                         <parameter name="Channel" required="true">
1272                                 <para>Channel that is currently in Async AGI.</para>
1273                         </parameter>
1274                         <parameter name="Command" required="true">
1275                                 <para>Application to execute.</para>
1276                         </parameter>
1277                         <parameter name="CommandID">
1278                                 <para>This will be sent back in CommandID header of AsyncAGI exec
1279                                 event notification.</para>
1280                         </parameter>
1281                 </syntax>
1282                 <description>
1283                         <para>Add an AGI command to the execute queue of the channel in Async AGI.</para>
1284                 </description>
1285                 <see-also>
1286                         <ref type="managerEvent">AsyncAGIStart</ref>
1287                         <ref type="managerEvent">AsyncAGIExec</ref>
1288                         <ref type="managerEvent">AsyncAGIEnd</ref>
1289                 </see-also>
1290         </manager>
1291         <managerEvent language="en_US" name="AsyncAGIStart">
1292                 <managerEventInstance class="EVENT_FLAG_AGI">
1293                         <synopsis>Raised when a channel starts AsyncAGI command processing.</synopsis>
1294                         <syntax>
1295                                 <channel_snapshot/>
1296                                 <parameter name="Env">
1297                                         <para>URL encoded string read from the AsyncAGI server.</para>
1298                                 </parameter>
1299                         </syntax>
1300                         <see-also>
1301                                 <ref type="managerEvent">AsyncAGIEnd</ref>
1302                                 <ref type="managerEvent">AsyncAGIExec</ref>
1303                                 <ref type="application">AGI</ref>
1304                                 <ref type="manager">AGI</ref>
1305                         </see-also>
1306                 </managerEventInstance>
1307         </managerEvent>
1308         <managerEvent language="en_US" name="AsyncAGIEnd">
1309                 <managerEventInstance class="EVENT_FLAG_AGI">
1310                         <synopsis>Raised when a channel stops AsyncAGI command processing.</synopsis>
1311                         <syntax>
1312                                 <channel_snapshot/>
1313                         </syntax>
1314                         <see-also>
1315                                 <ref type="managerEvent">AsyncAGIStart</ref>
1316                                 <ref type="managerEvent">AsyncAGIExec</ref>
1317                                 <ref type="application">AGI</ref>
1318                                 <ref type="manager">AGI</ref>
1319                         </see-also>
1320                 </managerEventInstance>
1321         </managerEvent>
1322         <managerEvent language="en_US" name="AsyncAGIExec">
1323                 <managerEventInstance class="EVENT_FLAG_AGI">
1324                         <synopsis>Raised when AsyncAGI completes an AGI command.</synopsis>
1325                         <syntax>
1326                                 <channel_snapshot/>
1327                                 <parameter name="CommandID" required="false">
1328                                         <para>Optional command ID sent by the AsyncAGI server to identify the command.</para>
1329                                 </parameter>
1330                                 <parameter name="Result">
1331                                         <para>URL encoded result string from the executed AGI command.</para>
1332                                 </parameter>
1333                         </syntax>
1334                         <see-also>
1335                                 <ref type="managerEvent">AsyncAGIStart</ref>
1336                                 <ref type="managerEvent">AsyncAGIEnd</ref>
1337                                 <ref type="application">AGI</ref>
1338                                 <ref type="manager">AGI</ref>
1339                         </see-also>
1340                 </managerEventInstance>
1341         </managerEvent>
1342         <managerEvent language="en_US" name="AGIExecStart">
1343                 <managerEventInstance class="EVENT_FLAG_AGI">
1344                         <synopsis>Raised when a received AGI command starts processing.</synopsis>
1345                         <syntax>
1346                                 <channel_snapshot/>
1347                                 <parameter name="Command">
1348                                         <para>The AGI command as received from the external source.</para>
1349                                 </parameter>
1350                                 <parameter name="CommandId">
1351                                         <para>Random identification number assigned to the execution of this command.</para>
1352                                 </parameter>
1353                         </syntax>
1354                         <see-also>
1355                                 <ref type="managerEvent">AGIExecEnd</ref>
1356                                 <ref type="application">AGI</ref>
1357                         </see-also>
1358                 </managerEventInstance>
1359         </managerEvent>
1360         <managerEvent language="en_US" name="AGIExecEnd">
1361                 <managerEventInstance class="EVENT_FLAG_AGI">
1362                         <synopsis>Raised when a received AGI command completes processing.</synopsis>
1363                         <syntax>
1364                                 <channel_snapshot/>
1365                                 <xi:include xpointer="xpointer(/docs/managerEvent[@name='AGIExecStart']/managerEventInstance/syntax/parameter)" />
1366                                 <parameter name="ResultCode">
1367                                         <para>The numeric result code from AGI</para>
1368                                 </parameter>
1369                                 <parameter name="Result">
1370                                         <para>The text result reason from AGI</para>
1371                                 </parameter>
1372                         </syntax>
1373                         <see-also>
1374                                 <ref type="managerEvent">AGIExecStart</ref>
1375                                 <ref type="application">AGI</ref>
1376                         </see-also>
1377                 </managerEventInstance>
1378         </managerEvent>
1379  ***/
1380
1381 #define MAX_ARGS 128
1382 #define MAX_CMD_LEN 80
1383 #define AGI_NANDFS_RETRY 3
1384 #define AGI_BUF_LEN 2048
1385 #define SRV_PREFIX "_agi._tcp."
1386
1387 static char *app = "AGI";
1388
1389 static char *eapp = "EAGI";
1390
1391 static char *deadapp = "DeadAGI";
1392
1393 static int agidebug = 0;
1394
1395 #define TONE_BLOCK_SIZE 200
1396
1397 /* Max time to connect to an AGI remote host */
1398 #define MAX_AGI_CONNECT 2000
1399
1400 #define AGI_PORT 4573
1401
1402 /*! Special return code for "asyncagi break" command. */
1403 #define ASYNC_AGI_BREAK 3
1404
1405 enum agi_result {
1406         AGI_RESULT_FAILURE = -1,
1407         AGI_RESULT_SUCCESS,
1408         AGI_RESULT_SUCCESS_FAST,
1409         AGI_RESULT_SUCCESS_ASYNC,
1410         AGI_RESULT_NOTFOUND,
1411         AGI_RESULT_HANGUP,
1412 };
1413
1414 static struct ast_manager_event_blob *agi_channel_to_ami(const char *type, struct stasis_message *message)
1415 {
1416         struct ast_channel_blob *obj = stasis_message_data(message);
1417         RAII_VAR(struct ast_str *, channel_string, NULL, ast_free);
1418         RAII_VAR(struct ast_str *, event_string, NULL, ast_free);
1419
1420         channel_string = ast_manager_build_channel_state_string(obj->snapshot);
1421         event_string = ast_manager_str_from_json_object(obj->blob, NULL);
1422         if (!channel_string || !event_string) {
1423                 return NULL;
1424         }
1425
1426         return ast_manager_event_blob_create(EVENT_FLAG_AGI, type,
1427                 "%s"
1428                 "%s",
1429                 ast_str_buffer(channel_string),
1430                 ast_str_buffer(event_string));
1431 }
1432
1433 static struct ast_manager_event_blob *agi_exec_start_to_ami(struct stasis_message *message)
1434 {
1435         return agi_channel_to_ami("AGIExecStart", message);
1436 }
1437
1438 static struct ast_manager_event_blob *agi_exec_end_to_ami(struct stasis_message *message)
1439 {
1440         return agi_channel_to_ami("AGIExecEnd", message);
1441 }
1442
1443 static struct ast_manager_event_blob *agi_async_start_to_ami(struct stasis_message *message)
1444 {
1445         return agi_channel_to_ami("AsyncAGIStart", message);
1446 }
1447
1448 static struct ast_manager_event_blob *agi_async_exec_to_ami(struct stasis_message *message)
1449 {
1450         return agi_channel_to_ami("AsyncAGIExec", message);
1451 }
1452
1453 static struct ast_manager_event_blob *agi_async_end_to_ami(struct stasis_message *message)
1454 {
1455         return agi_channel_to_ami("AsyncAGIEnd", message);
1456 }
1457
1458 STASIS_MESSAGE_TYPE_DEFN_LOCAL(agi_exec_start_type,
1459         .to_ami = agi_exec_start_to_ami,
1460         );
1461 STASIS_MESSAGE_TYPE_DEFN_LOCAL(agi_exec_end_type,
1462         .to_ami = agi_exec_end_to_ami,
1463         );
1464 STASIS_MESSAGE_TYPE_DEFN_LOCAL(agi_async_start_type,
1465         .to_ami = agi_async_start_to_ami,
1466         );
1467 STASIS_MESSAGE_TYPE_DEFN_LOCAL(agi_async_exec_type,
1468         .to_ami = agi_async_exec_to_ami,
1469         );
1470 STASIS_MESSAGE_TYPE_DEFN_LOCAL(agi_async_end_type,
1471         .to_ami = agi_async_end_to_ami,
1472         );
1473
1474 static agi_command *find_command(const char * const cmds[], int exact);
1475
1476 AST_THREADSTORAGE(agi_buf);
1477 #define AGI_BUF_INITSIZE 256
1478
1479 int AST_OPTIONAL_API_NAME(ast_agi_send)(int fd, struct ast_channel *chan, char *fmt, ...)
1480 {
1481         int res = 0;
1482         va_list ap;
1483         struct ast_str *buf;
1484
1485         if (!(buf = ast_str_thread_get(&agi_buf, AGI_BUF_INITSIZE)))
1486                 return -1;
1487
1488         va_start(ap, fmt);
1489         res = ast_str_set_va(&buf, 0, fmt, ap);
1490         va_end(ap);
1491
1492         if (res == -1) {
1493                 ast_log(LOG_ERROR, "Out of memory\n");
1494                 return -1;
1495         }
1496
1497         if (agidebug) {
1498                 if (chan) {
1499                         ast_verbose("<%s>AGI Tx >> %s", ast_channel_name(chan), ast_str_buffer(buf));
1500                 } else {
1501                         ast_verbose("AGI Tx >> %s", ast_str_buffer(buf));
1502                 }
1503         }
1504
1505         return ast_carefulwrite(fd, ast_str_buffer(buf), ast_str_strlen(buf), 100);
1506 }
1507
1508 /* linked list of AGI commands ready to be executed by Async AGI */
1509 struct agi_cmd {
1510         char *cmd_buffer;
1511         char *cmd_id;
1512         AST_LIST_ENTRY(agi_cmd) entry;
1513 };
1514
1515 static void free_agi_cmd(struct agi_cmd *cmd)
1516 {
1517         ast_free(cmd->cmd_buffer);
1518         ast_free(cmd->cmd_id);
1519         ast_free(cmd);
1520 }
1521
1522 /* AGI datastore destructor */
1523 static void agi_destroy_commands_cb(void *data)
1524 {
1525         struct agi_cmd *cmd;
1526         AST_LIST_HEAD(, agi_cmd) *chan_cmds = data;
1527         AST_LIST_LOCK(chan_cmds);
1528         while ( (cmd = AST_LIST_REMOVE_HEAD(chan_cmds, entry)) ) {
1529                 free_agi_cmd(cmd);
1530         }
1531         AST_LIST_UNLOCK(chan_cmds);
1532         AST_LIST_HEAD_DESTROY(chan_cmds);
1533         ast_free(chan_cmds);
1534 }
1535
1536 /* channel datastore to keep the queue of AGI commands in the channel */
1537 static const struct ast_datastore_info agi_commands_datastore_info = {
1538         .type = "AsyncAGI",
1539         .destroy = agi_destroy_commands_cb
1540 };
1541
1542 /*!
1543  * \brief Retrieve the list head to the requested channel's AGI datastore
1544  * \param chan Channel datastore is requested for
1545  * \param cmd Pointer to the struct pointer which will reference the head of the agi command list.
1546  *
1547  * \retval 0 if the datastore was valid and the list head was retrieved appropriately (even if it's
1548  *           NULL and the list is empty)
1549  * \retval -1 if the datastore could not be retrieved causing an error
1550 */
1551 static int get_agi_cmd(struct ast_channel *chan, struct agi_cmd **cmd)
1552 {
1553         struct ast_datastore *store;
1554         AST_LIST_HEAD(, agi_cmd) *agi_commands;
1555
1556         ast_channel_lock(chan);
1557         store = ast_channel_datastore_find(chan, &agi_commands_datastore_info, NULL);
1558         ast_channel_unlock(chan);
1559         if (!store) {
1560                 ast_log(LOG_ERROR, "Huh? Async AGI datastore disappeared on Channel %s!\n",
1561                         ast_channel_name(chan));
1562                 *cmd = NULL;
1563                 return -1;
1564         }
1565         agi_commands = store->data;
1566         AST_LIST_LOCK(agi_commands);
1567         *cmd = AST_LIST_REMOVE_HEAD(agi_commands, entry);
1568         AST_LIST_UNLOCK(agi_commands);
1569         return 0;
1570 }
1571
1572 /* channel is locked when calling this one either from the CLI or manager thread */
1573 static int add_agi_cmd(struct ast_channel *chan, const char *cmd_buff, const char *cmd_id)
1574 {
1575         struct ast_datastore *store;
1576         struct agi_cmd *cmd;
1577         AST_LIST_HEAD(, agi_cmd) *agi_commands;
1578
1579         store = ast_channel_datastore_find(chan, &agi_commands_datastore_info, NULL);
1580         if (!store) {
1581                 ast_log(LOG_WARNING, "Channel %s is not setup for Async AGI.\n", ast_channel_name(chan));
1582                 return -1;
1583         }
1584         agi_commands = store->data;
1585         cmd = ast_calloc(1, sizeof(*cmd));
1586         if (!cmd) {
1587                 return -1;
1588         }
1589         cmd->cmd_buffer = ast_strdup(cmd_buff);
1590         if (!cmd->cmd_buffer) {
1591                 ast_free(cmd);
1592                 return -1;
1593         }
1594         cmd->cmd_id = ast_strdup(cmd_id);
1595         if (!cmd->cmd_id) {
1596                 ast_free(cmd->cmd_buffer);
1597                 ast_free(cmd);
1598                 return -1;
1599         }
1600         AST_LIST_LOCK(agi_commands);
1601         AST_LIST_INSERT_TAIL(agi_commands, cmd, entry);
1602         AST_LIST_UNLOCK(agi_commands);
1603         return 0;
1604 }
1605
1606 static int add_to_agi(struct ast_channel *chan)
1607 {
1608         struct ast_datastore *datastore;
1609         AST_LIST_HEAD(, agi_cmd) *agi_cmds_list;
1610
1611         /* check if already on AGI */
1612         ast_channel_lock(chan);
1613         datastore = ast_channel_datastore_find(chan, &agi_commands_datastore_info, NULL);
1614         ast_channel_unlock(chan);
1615         if (datastore) {
1616                 /* we already have an AGI datastore, let's just
1617                    return success */
1618                 return 0;
1619         }
1620
1621         /* the channel has never been on Async AGI,
1622            let's allocate it's datastore */
1623         datastore = ast_datastore_alloc(&agi_commands_datastore_info, "AGI");
1624         if (!datastore) {
1625                 return -1;
1626         }
1627         agi_cmds_list = ast_calloc(1, sizeof(*agi_cmds_list));
1628         if (!agi_cmds_list) {
1629                 ast_log(LOG_ERROR, "Unable to allocate Async AGI commands list.\n");
1630                 ast_datastore_free(datastore);
1631                 return -1;
1632         }
1633         datastore->data = agi_cmds_list;
1634         AST_LIST_HEAD_INIT(agi_cmds_list);
1635         ast_channel_lock(chan);
1636         ast_channel_datastore_add(chan, datastore);
1637         ast_channel_unlock(chan);
1638         return 0;
1639 }
1640
1641 /*!
1642  * \brief CLI command to add applications to execute in Async AGI
1643  * \param e
1644  * \param cmd
1645  * \param a
1646  *
1647  * \retval CLI_SUCCESS on success
1648  * \retval NULL when init or tab completion is used
1649 */
1650 static char *handle_cli_agi_add_cmd(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
1651 {
1652         struct ast_channel *chan;
1653         switch (cmd) {
1654         case CLI_INIT:
1655                 e->command = "agi exec";
1656                 e->usage = "Usage: agi exec <channel name> <app and arguments> [id]\n"
1657                            "       Add AGI command to the execute queue of the specified channel in Async AGI\n";
1658                 return NULL;
1659         case CLI_GENERATE:
1660                 if (a->pos == 2)
1661                         return ast_complete_channels(a->line, a->word, a->pos, a->n, 2);
1662                 return NULL;
1663         }
1664
1665         if (a->argc < 4) {
1666                 return CLI_SHOWUSAGE;
1667         }
1668
1669         if (!(chan = ast_channel_get_by_name(a->argv[2]))) {
1670                 ast_cli(a->fd, "Channel %s does not exist.\n", a->argv[2]);
1671                 return CLI_FAILURE;
1672         }
1673
1674         ast_channel_lock(chan);
1675
1676         if (add_agi_cmd(chan, a->argv[3], (a->argc > 4 ? a->argv[4] : ""))) {
1677                 ast_cli(a->fd, "Failed to add AGI command to queue of channel %s\n", ast_channel_name(chan));
1678                 ast_channel_unlock(chan);
1679                 chan = ast_channel_unref(chan);
1680                 return CLI_FAILURE;
1681         }
1682
1683         ast_debug(1, "Added AGI command to channel %s queue\n", ast_channel_name(chan));
1684
1685         ast_channel_unlock(chan);
1686         chan = ast_channel_unref(chan);
1687
1688         return CLI_SUCCESS;
1689 }
1690
1691 /*!
1692  * \brief Add a new command to execute by the Async AGI application
1693  * \param s
1694  * \param m
1695  *
1696  * It will append the application to the specified channel's queue
1697  * if the channel is not inside Async AGI application it will return an error
1698  * \retval 0 on success or incorrect use
1699  * \retval 1 on failure to add the command ( most likely because the channel
1700  * is not in Async AGI loop )
1701 */
1702 static int action_add_agi_cmd(struct mansession *s, const struct message *m)
1703 {
1704         const char *channel = astman_get_header(m, "Channel");
1705         const char *cmdbuff = astman_get_header(m, "Command");
1706         const char *cmdid   = astman_get_header(m, "CommandID");
1707         struct ast_channel *chan;
1708         char buf[256];
1709
1710         if (ast_strlen_zero(channel) || ast_strlen_zero(cmdbuff)) {
1711                 astman_send_error(s, m, "Both, Channel and Command are *required*");
1712                 return 0;
1713         }
1714
1715         if (!(chan = ast_channel_get_by_name(channel))) {
1716                 snprintf(buf, sizeof(buf), "Channel %s does not exist.", channel);
1717                 astman_send_error(s, m, buf);
1718                 return 0;
1719         }
1720
1721         ast_channel_lock(chan);
1722
1723         if (add_agi_cmd(chan, cmdbuff, cmdid)) {
1724                 snprintf(buf, sizeof(buf), "Failed to add AGI command to channel %s queue", ast_channel_name(chan));
1725                 astman_send_error(s, m, buf);
1726                 ast_channel_unlock(chan);
1727                 chan = ast_channel_unref(chan);
1728                 return 0;
1729         }
1730
1731         ast_channel_unlock(chan);
1732         chan = ast_channel_unref(chan);
1733
1734         astman_send_ack(s, m, "Added AGI command to queue");
1735
1736         return 0;
1737 }
1738
1739 static enum agi_result agi_handle_command(struct ast_channel *chan, AGI *agi, char *buf, int dead);
1740 static void setup_env(struct ast_channel *chan, char *request, int fd, int enhanced, int argc, char *argv[]);
1741
1742 /*!
1743  * \internal
1744  * \brief Read and handle a channel frame for Async AGI.
1745  *
1746  * \param chan Channel to read a frame from.
1747  *
1748  * \retval AGI_RESULT_SUCCESS on success.
1749  * \retval AGI_RESULT_HANGUP on hangup.
1750  * \retval AGI_RESULT_FAILURE on error.
1751  */
1752 static enum agi_result async_agi_read_frame(struct ast_channel *chan)
1753 {
1754         struct ast_frame *f;
1755
1756         f = ast_read(chan);
1757         if (!f) {
1758                 ast_debug(3, "No frame read on channel %s, going out ...\n", ast_channel_name(chan));
1759                 return AGI_RESULT_HANGUP;
1760         }
1761         if (f->frametype == AST_FRAME_CONTROL) {
1762                 /*
1763                  * Is there any other frame we should care about besides
1764                  * AST_CONTROL_HANGUP?
1765                  */
1766                 switch (f->subclass.integer) {
1767                 case AST_CONTROL_HANGUP:
1768                         ast_debug(3, "Got HANGUP frame on channel %s, going out ...\n", ast_channel_name(chan));
1769                         ast_frfree(f);
1770                         return AGI_RESULT_HANGUP;
1771                 default:
1772                         break;
1773                 }
1774         }
1775         ast_frfree(f);
1776
1777         return AGI_RESULT_SUCCESS;
1778 }
1779
1780 static enum agi_result launch_asyncagi(struct ast_channel *chan, int argc, char *argv[], int *efd)
1781 {
1782 /* This buffer sizes might cause truncation if the AGI command writes more data
1783    than AGI_BUF_SIZE as result. But let's be serious, is there an AGI command
1784    that writes a response larger than 1024 bytes?, I don't think so, most of
1785    them are just result=blah stuff. However probably if GET VARIABLE is called
1786    and the variable has large amount of data, that could be a problem. We could
1787    make this buffers dynamic, but let's leave that as a second step.
1788
1789    AMI_BUF_SIZE is twice AGI_BUF_SIZE just for the sake of choosing a safe
1790    number. Some characters of AGI buf will be url encoded to be sent to manager
1791    clients.  An URL encoded character will take 3 bytes, but again, to cause
1792    truncation more than about 70% of the AGI buffer should be URL encoded for
1793    that to happen.  Not likely at all.
1794
1795    On the other hand. I wonder if read() could eventually return less data than
1796    the amount already available in the pipe? If so, how to deal with that?
1797    So far, my tests on Linux have not had any problems.
1798  */
1799 #define AGI_BUF_SIZE 1024
1800 #define AMI_BUF_SIZE 2048
1801         enum agi_result cmd_status;
1802         struct agi_cmd *cmd;
1803         int res;
1804         int fds[2];
1805         int hungup;
1806         int timeout = 100;
1807         char agi_buffer[AGI_BUF_SIZE + 1];
1808         char ami_buffer[AMI_BUF_SIZE];
1809         enum agi_result returnstatus = AGI_RESULT_SUCCESS;
1810         AGI async_agi;
1811         RAII_VAR(struct ast_json *, startblob, NULL, ast_json_unref);
1812
1813         if (efd) {
1814                 ast_log(LOG_WARNING, "Async AGI does not support Enhanced AGI yet\n");
1815                 return AGI_RESULT_FAILURE;
1816         }
1817
1818         /* add AsyncAGI datastore to the channel */
1819         if (add_to_agi(chan)) {
1820                 ast_log(LOG_ERROR, "Failed to start Async AGI on channel %s\n", ast_channel_name(chan));
1821                 return AGI_RESULT_FAILURE;
1822         }
1823
1824         /* this pipe allows us to create a "fake" AGI struct to use
1825            the AGI commands */
1826         res = pipe(fds);
1827         if (res) {
1828                 ast_log(LOG_ERROR, "Failed to create Async AGI pipe\n");
1829                 /*
1830                  * Intentionally do not remove the datastore added with
1831                  * add_to_agi() the from channel.  It will be removed when the
1832                  * channel is hung up anyway.
1833                  */
1834                 return AGI_RESULT_FAILURE;
1835         }
1836
1837         /* handlers will get the pipe write fd and we read the AGI responses
1838            from the pipe read fd */
1839         async_agi.fd = fds[1];
1840         async_agi.ctrl = fds[1];
1841         async_agi.audio = -1; /* no audio support */
1842         async_agi.fast = 0;
1843         async_agi.speech = NULL;
1844
1845         /* notify possible manager users of a new channel ready to
1846            receive commands */
1847         setup_env(chan, "async", fds[1], 0, argc, argv);
1848         /* read the environment */
1849         res = read(fds[0], agi_buffer, AGI_BUF_SIZE);
1850         if (res <= 0) {
1851                 ast_log(LOG_ERROR, "Failed to read from Async AGI pipe on channel %s: %s\n",
1852                                 ast_channel_name(chan), res < 0 ? strerror(errno) : "EOF");
1853                 returnstatus = AGI_RESULT_FAILURE;
1854                 goto async_agi_abort;
1855         }
1856         agi_buffer[res] = '\0';
1857         /* encode it and send it thru the manager so whoever is going to take
1858            care of AGI commands on this channel can decide which AGI commands
1859            to execute based on the setup info */
1860         ast_uri_encode(agi_buffer, ami_buffer, AMI_BUF_SIZE, ast_uri_http);
1861         startblob = ast_json_pack("{s: s}", "Env", ami_buffer);
1862
1863         ast_channel_publish_cached_blob(chan, agi_async_start_type(), startblob);
1864
1865         hungup = ast_check_hangup_locked(chan);
1866
1867         for (;;) {
1868                 /*
1869                  * Process as many commands as we can.  Commands are added via
1870                  * the manager or the cli threads.
1871                  */
1872                 while (!hungup) {
1873                         RAII_VAR(struct ast_json *, execblob, NULL, ast_json_unref);
1874                         res = get_agi_cmd(chan, &cmd);
1875
1876                         if (res) {
1877                                 returnstatus = AGI_RESULT_FAILURE;
1878                                 goto async_agi_done;
1879                         } else if (!cmd) {
1880                                 break;
1881                         }
1882
1883                         /* OK, we have a command, let's call the command handler. */
1884                         cmd_status = agi_handle_command(chan, &async_agi, cmd->cmd_buffer, 0);
1885
1886                         /*
1887                          * The command handler must have written to our fake AGI struct
1888                          * fd (the pipe), let's read the response.
1889                          */
1890                         res = read(fds[0], agi_buffer, AGI_BUF_SIZE);
1891                         if (res <= 0) {
1892                                 ast_log(LOG_ERROR, "Failed to read from Async AGI pipe on channel %s: %s\n",
1893                                         ast_channel_name(chan), res < 0 ? strerror(errno) : "EOF");
1894                                 free_agi_cmd(cmd);
1895                                 returnstatus = AGI_RESULT_FAILURE;
1896                                 goto async_agi_done;
1897                         }
1898                         /*
1899                          * We have a response, let's send the response thru the manager.
1900                          * Include the CommandID if it was specified when the command
1901                          * was added.
1902                          */
1903                         agi_buffer[res] = '\0';
1904                         ast_uri_encode(agi_buffer, ami_buffer, AMI_BUF_SIZE, ast_uri_http);
1905
1906                         execblob = ast_json_pack("{s: s}", "Result", ami_buffer);
1907                         if (execblob && !ast_strlen_zero(cmd->cmd_id)) {
1908                                 ast_json_object_set(execblob, "CommandId", ast_json_string_create(cmd->cmd_id));
1909                         }
1910                         ast_channel_publish_cached_blob(chan, agi_async_exec_type(), execblob);
1911
1912                         free_agi_cmd(cmd);
1913
1914                         /*
1915                          * Check the command status to determine if we should continue
1916                          * executing more commands.
1917                          */
1918                         hungup = ast_check_hangup(chan);
1919                         switch (cmd_status) {
1920                         case AGI_RESULT_FAILURE:
1921                                 if (!hungup) {
1922                                         /* The failure was not because of a hangup. */
1923                                         returnstatus = AGI_RESULT_FAILURE;
1924                                         goto async_agi_done;
1925                                 }
1926                                 break;
1927                         case AGI_RESULT_SUCCESS_ASYNC:
1928                                 /* Only the "asyncagi break" command does this. */
1929                                 returnstatus = AGI_RESULT_SUCCESS_ASYNC;
1930                                 goto async_agi_done;
1931                         default:
1932                                 break;
1933                         }
1934                 }
1935
1936                 if (!hungup) {
1937                         /* Wait a bit for a frame to read or to poll for a new command. */
1938                         res = ast_waitfor(chan, timeout);
1939                         if (res < 0) {
1940                                 ast_debug(1, "ast_waitfor returned <= 0 on chan %s\n", ast_channel_name(chan));
1941                                 returnstatus = AGI_RESULT_FAILURE;
1942                                 break;
1943                         }
1944                 } else {
1945                         /*
1946                          * Read the channel control queue until it is dry so we can
1947                          * quit.
1948                          */
1949                         res = 1;
1950                 }
1951                 if (0 < res) {
1952                         do {
1953                                 cmd_status = async_agi_read_frame(chan);
1954                                 if (cmd_status != AGI_RESULT_SUCCESS) {
1955                                         returnstatus = cmd_status;
1956                                         goto async_agi_done;
1957                                 }
1958                                 hungup = ast_check_hangup(chan);
1959                         } while (hungup);
1960                 } else {
1961                         hungup = ast_check_hangup(chan);
1962                 }
1963         }
1964 async_agi_done:
1965
1966         if (async_agi.speech) {
1967                 ast_speech_destroy(async_agi.speech);
1968         }
1969         /* notify manager users this channel cannot be controlled anymore by Async AGI */
1970         ast_channel_publish_cached_blob(chan, agi_async_end_type(), NULL);
1971
1972 async_agi_abort:
1973         /* close the pipe */
1974         close(fds[0]);
1975         close(fds[1]);
1976
1977         /*
1978          * Intentionally do not remove the datastore added with
1979          * add_to_agi() the from channel.  There might be commands still
1980          * in the queue or in-flight to us and AsyncAGI may get called
1981          * again.  The datastore destructor will be called on channel
1982          * destruction anyway.
1983          */
1984
1985         if (returnstatus == AGI_RESULT_SUCCESS) {
1986                 returnstatus = AGI_RESULT_SUCCESS_ASYNC;
1987         }
1988         return returnstatus;
1989
1990 #undef AGI_BUF_SIZE
1991 #undef AMI_BUF_SIZE
1992 }
1993
1994 /*!
1995  * \internal
1996  * \brief Handle the connection that was started by launch_netscript.
1997  *
1998  * \param agiurl Url that we are trying to connect to.
1999  * \param addr Address that host was resolved to.
2000  * \param netsockfd File descriptor of socket.
2001  *
2002  * \retval 0 when connection is succesful.
2003  * \retval 1 when there is an error.
2004  */
2005 static int handle_connection(const char *agiurl, const struct ast_sockaddr addr, const int netsockfd)
2006 {
2007         struct pollfd pfds[1];
2008         int res, conresult;
2009         socklen_t reslen;
2010
2011         reslen = sizeof(conresult);
2012
2013         pfds[0].fd = netsockfd;
2014         pfds[0].events = POLLOUT;
2015
2016         while ((res = ast_poll(pfds, 1, MAX_AGI_CONNECT)) != 1) {
2017                 if (errno != EINTR) {
2018                         if (!res) {
2019                                 ast_log(LOG_WARNING, "FastAGI connection to '%s' timed out after MAX_AGI_CONNECT (%d) milliseconds.\n",
2020                                         agiurl, MAX_AGI_CONNECT);
2021                         } else {
2022                                 ast_log(LOG_WARNING, "Connect to '%s' failed: %s\n", agiurl, strerror(errno));
2023                         }
2024
2025                         return 1;
2026                 }
2027         }
2028
2029         if (getsockopt(pfds[0].fd, SOL_SOCKET, SO_ERROR, &conresult, &reslen) < 0) {
2030                 ast_log(LOG_WARNING, "Connection to %s failed with error: %s\n",
2031                         ast_sockaddr_stringify(&addr), strerror(errno));
2032                 return 1;
2033         }
2034
2035         if (conresult) {
2036                 ast_log(LOG_WARNING, "Connecting to '%s' failed for url '%s': %s\n",
2037                         ast_sockaddr_stringify(&addr), agiurl, strerror(conresult));
2038                 return 1;
2039         }
2040
2041         return 0;
2042 }
2043
2044 /* launch_netscript: The fastagi handler.
2045         FastAGI defaults to port 4573 */
2046 static enum agi_result launch_netscript(char *agiurl, char *argv[], int *fds)
2047 {
2048         int s = 0, flags;
2049         char *host, *script;
2050         int num_addrs = 0, i = 0;
2051         struct ast_sockaddr *addrs;
2052
2053         /* agiurl is "agi://host.domain[:port][/script/name]" */
2054         host = ast_strdupa(agiurl + 6); /* Remove agi:// */
2055
2056         /* Strip off any script name */
2057         if ((script = strchr(host, '/'))) {
2058                 *script++ = '\0';
2059         } else {
2060                 script = "";
2061         }
2062
2063         if (!(num_addrs = ast_sockaddr_resolve(&addrs, host, 0, AST_AF_UNSPEC))) {
2064                 ast_log(LOG_WARNING, "Unable to locate host '%s'\n", host);
2065                 return AGI_RESULT_FAILURE;
2066         }
2067
2068         for (i = 0; i < num_addrs; i++) {
2069                 if (!ast_sockaddr_port(&addrs[i])) {
2070                         ast_sockaddr_set_port(&addrs[i], AGI_PORT);
2071                 }
2072
2073                 if ((s = socket(addrs[i].ss.ss_family, SOCK_STREAM, IPPROTO_TCP)) < 0) {
2074                         ast_log(LOG_WARNING, "Unable to create socket: %s\n", strerror(errno));
2075                         continue;
2076                 }
2077
2078                 if ((flags = fcntl(s, F_GETFL)) < 0) {
2079                         ast_log(LOG_WARNING, "fcntl(F_GETFL) failed: %s\n", strerror(errno));
2080                         close(s);
2081                         continue;
2082                 }
2083
2084                 if (fcntl(s, F_SETFL, flags | O_NONBLOCK) < 0) {
2085                         ast_log(LOG_WARNING, "fnctl(F_SETFL) failed: %s\n", strerror(errno));
2086                         close(s);
2087                         continue;
2088                 }
2089
2090                 if (ast_connect(s, &addrs[i]) && errno == EINPROGRESS) {
2091
2092                         if (handle_connection(agiurl, addrs[i], s)) {
2093                                 close(s);
2094                                 continue;
2095                         }
2096
2097                 } else {
2098                         ast_log(LOG_WARNING, "Connection to %s failed with unexpected error: %s\n",
2099                         ast_sockaddr_stringify(&addrs[i]), strerror(errno));
2100                 }
2101
2102                 break;
2103         }
2104
2105         ast_free(addrs);
2106
2107         if (i == num_addrs) {
2108                 ast_log(LOG_WARNING, "Couldn't connect to any host.  FastAGI failed.\n");
2109                 return AGI_RESULT_FAILURE;
2110         }
2111
2112         if (ast_agi_send(s, NULL, "agi_network: yes\n") < 0) {
2113                 if (errno != EINTR) {
2114                         ast_log(LOG_WARNING, "Connect to '%s' failed: %s\n", agiurl, strerror(errno));
2115                         close(s);
2116                         return AGI_RESULT_FAILURE;
2117                 }
2118         }
2119
2120         /* If we have a script parameter, relay it to the fastagi server */
2121         /* Script parameters take the form of: AGI(agi://my.example.com/?extension=${EXTEN}) */
2122         if (!ast_strlen_zero(script)) {
2123                 ast_agi_send(s, NULL, "agi_network_script: %s\n", script);
2124         }
2125
2126         ast_debug(4, "Wow, connected!\n");
2127         fds[0] = s;
2128         fds[1] = s;
2129         return AGI_RESULT_SUCCESS_FAST;
2130 }
2131
2132 /*!
2133  * \internal
2134  * \brief The HA fastagi handler.
2135  * \param agiurl The request URL as passed to Agi() in the dial plan
2136  * \param argv The parameters after the URL passed to Agi() in the dial plan
2137  * \param fds Input/output file descriptors
2138  *
2139  * Uses SRV lookups to try to connect to a list of FastAGI servers. The hostname in
2140  * the URI is prefixed with _agi._tcp. prior to the DNS resolution. For
2141  * example, if you specify the URI \a hagi://agi.example.com/foo.agi the DNS
2142  * query would be for \a _agi._tcp.agi.example.com and you'll need to make sure
2143  * this resolves.
2144  *
2145  * This function parses the URI, resolves the SRV service name, forms new URIs
2146  * with the results of the DNS lookup, and then calls launch_netscript on the
2147  * new URIs until one succeeds.
2148  *
2149  * \return the result of the AGI operation.
2150  */
2151 static enum agi_result launch_ha_netscript(char *agiurl, char *argv[], int *fds)
2152 {
2153         char *host, *script;
2154         enum agi_result result;
2155         struct srv_context *context = NULL;
2156         int srv_ret;
2157         char service[256];
2158         char resolved_uri[1024];
2159         const char *srvhost;
2160         unsigned short srvport;
2161
2162         /* format of agiurl is "hagi://host.domain[:port][/script/name]" */
2163         if (strlen(agiurl) < 7) { /* Remove hagi:// */
2164                 ast_log(LOG_WARNING, "An error occurred parsing the AGI URI: %s", agiurl);
2165                 return AGI_RESULT_FAILURE;
2166         }
2167         host = ast_strdupa(agiurl + 7);
2168
2169         /* Strip off any script name */
2170         if ((script = strchr(host, '/'))) {
2171                 *script++ = '\0';
2172         } else {
2173                 script = "";
2174         }
2175
2176         if (strchr(host, ':')) {
2177                 ast_log(LOG_WARNING, "Specifying a port number disables SRV lookups: %s\n", agiurl);
2178                 return launch_netscript(agiurl + 1, argv, fds); /* +1 to strip off leading h from hagi:// */
2179         }
2180
2181         snprintf(service, sizeof(service), "%s%s", SRV_PREFIX, host);
2182
2183         while (!(srv_ret = ast_srv_lookup(&context, service, &srvhost, &srvport))) {
2184                 snprintf(resolved_uri, sizeof(resolved_uri), "agi://%s:%d/%s", srvhost, srvport, script);
2185                 result = launch_netscript(resolved_uri, argv, fds);
2186                 if (result == AGI_RESULT_FAILURE || result == AGI_RESULT_NOTFOUND) {
2187                         ast_log(LOG_WARNING, "AGI request failed for host '%s' (%s:%d)\n", host, srvhost, srvport);
2188                 } else {
2189                         /* The script launched so we must cleanup the context. */
2190                         ast_srv_cleanup(&context);
2191                         return result;
2192                 }
2193         }
2194         /*
2195          * The DNS SRV lookup failed or we ran out of servers to check.
2196          * ast_srv_lookup() has already cleaned up the context for us.
2197          */
2198         if (srv_ret < 0) {
2199                 ast_log(LOG_WARNING, "SRV lookup failed for %s\n", agiurl);
2200         }
2201
2202         return AGI_RESULT_FAILURE;
2203 }
2204
2205 static enum agi_result launch_script(struct ast_channel *chan, char *script, int argc, char *argv[], int *fds, int *efd, int *opid)
2206 {
2207         char tmp[256];
2208         int pid, toast[2], fromast[2], audio[2], res;
2209         struct stat st;
2210
2211         if (!strncasecmp(script, "agi://", 6)) {
2212                 return (efd == NULL) ? launch_netscript(script, argv, fds) : AGI_RESULT_FAILURE;
2213         }
2214         if (!strncasecmp(script, "hagi://", 7)) {
2215                 return (efd == NULL) ? launch_ha_netscript(script, argv, fds) : AGI_RESULT_FAILURE;
2216         }
2217         if (!strncasecmp(script, "agi:async", sizeof("agi:async") - 1)) {
2218                 return launch_asyncagi(chan, argc, argv, efd);
2219         }
2220
2221         if (script[0] != '/') {
2222                 snprintf(tmp, sizeof(tmp), "%s/%s", ast_config_AST_AGI_DIR, script);
2223                 script = tmp;
2224         }
2225
2226         /* Before even trying let's see if the file actually exists */
2227         if (stat(script, &st)) {
2228                 ast_log(LOG_WARNING, "Failed to execute '%s': File does not exist.\n", script);
2229                 return AGI_RESULT_NOTFOUND;
2230         }
2231
2232         if (pipe(toast)) {
2233                 ast_log(LOG_WARNING, "Unable to create toast pipe: %s\n",strerror(errno));
2234                 return AGI_RESULT_FAILURE;
2235         }
2236         if (pipe(fromast)) {
2237                 ast_log(LOG_WARNING, "unable to create fromast pipe: %s\n", strerror(errno));
2238                 close(toast[0]);
2239                 close(toast[1]);
2240                 return AGI_RESULT_FAILURE;
2241         }
2242         if (efd) {
2243                 if (pipe(audio)) {
2244                         ast_log(LOG_WARNING, "unable to create audio pipe: %s\n", strerror(errno));
2245                         close(fromast[0]);
2246                         close(fromast[1]);
2247                         close(toast[0]);
2248                         close(toast[1]);
2249                         return AGI_RESULT_FAILURE;
2250                 }
2251                 res = fcntl(audio[1], F_GETFL);
2252                 if (res > -1)
2253                         res = fcntl(audio[1], F_SETFL, res | O_NONBLOCK);
2254                 if (res < 0) {
2255                         ast_log(LOG_WARNING, "unable to set audio pipe parameters: %s\n", strerror(errno));
2256                         close(fromast[0]);
2257                         close(fromast[1]);
2258                         close(toast[0]);
2259                         close(toast[1]);
2260                         close(audio[0]);
2261                         close(audio[1]);
2262                         return AGI_RESULT_FAILURE;
2263                 }
2264         }
2265
2266         if ((pid = ast_safe_fork(1)) < 0) {
2267                 ast_log(LOG_WARNING, "Failed to fork(): %s\n", strerror(errno));
2268                 return AGI_RESULT_FAILURE;
2269         }
2270         if (!pid) {
2271                 /* Pass paths to AGI via environmental variables */
2272                 setenv("AST_CONFIG_DIR", ast_config_AST_CONFIG_DIR, 1);
2273                 setenv("AST_CONFIG_FILE", ast_config_AST_CONFIG_FILE, 1);
2274                 setenv("AST_MODULE_DIR", ast_config_AST_MODULE_DIR, 1);
2275                 setenv("AST_SPOOL_DIR", ast_config_AST_SPOOL_DIR, 1);
2276                 setenv("AST_MONITOR_DIR", ast_config_AST_MONITOR_DIR, 1);
2277                 setenv("AST_VAR_DIR", ast_config_AST_VAR_DIR, 1);
2278                 setenv("AST_DATA_DIR", ast_config_AST_DATA_DIR, 1);
2279                 setenv("AST_LOG_DIR", ast_config_AST_LOG_DIR, 1);
2280                 setenv("AST_AGI_DIR", ast_config_AST_AGI_DIR, 1);
2281                 setenv("AST_KEY_DIR", ast_config_AST_KEY_DIR, 1);
2282                 setenv("AST_RUN_DIR", ast_config_AST_RUN_DIR, 1);
2283
2284                 /* Don't run AGI scripts with realtime priority -- it causes audio stutter */
2285                 ast_set_priority(0);
2286
2287                 /* Redirect stdin and out, provide enhanced audio channel if desired */
2288                 dup2(fromast[0], STDIN_FILENO);
2289                 dup2(toast[1], STDOUT_FILENO);
2290                 if (efd)
2291                         dup2(audio[0], STDERR_FILENO + 1);
2292                 else
2293                         close(STDERR_FILENO + 1);
2294
2295                 /* Close everything but stdin/out/error */
2296                 ast_close_fds_above_n(STDERR_FILENO + 1);
2297
2298                 /* Execute script */
2299                 /* XXX argv should be deprecated in favor of passing agi_argX paramaters */
2300                 execv(script, argv);
2301                 /* Can't use ast_log since FD's are closed */
2302                 ast_child_verbose(1, "Failed to execute '%s': %s", script, strerror(errno));
2303                 /* Special case to set status of AGI to failure */
2304                 fprintf(stdout, "failure\n");
2305                 fflush(stdout);
2306                 _exit(1);
2307         }
2308         ast_verb(3, "Launched AGI Script %s\n", script);
2309         fds[0] = toast[0];
2310         fds[1] = fromast[1];
2311         if (efd)
2312                 *efd = audio[1];
2313         /* close what we're not using in the parent */
2314         close(toast[1]);
2315         close(fromast[0]);
2316
2317         if (efd)
2318                 close(audio[0]);
2319
2320         *opid = pid;
2321         return AGI_RESULT_SUCCESS;
2322 }
2323
2324 static void setup_env(struct ast_channel *chan, char *request, int fd, int enhanced, int argc, char *argv[])
2325 {
2326         int count;
2327
2328         /* Print initial environment, with agi_request always being the first
2329            thing */
2330         ast_agi_send(fd, chan, "agi_request: %s\n", request);
2331         ast_agi_send(fd, chan, "agi_channel: %s\n", ast_channel_name(chan));
2332         ast_agi_send(fd, chan, "agi_language: %s\n", ast_channel_language(chan));
2333         ast_agi_send(fd, chan, "agi_type: %s\n", ast_channel_tech(chan)->type);
2334         ast_agi_send(fd, chan, "agi_uniqueid: %s\n", ast_channel_uniqueid(chan));
2335         ast_agi_send(fd, chan, "agi_version: %s\n", ast_get_version());
2336
2337         /* ANI/DNIS */
2338         ast_agi_send(fd, chan, "agi_callerid: %s\n",
2339                 S_COR(ast_channel_caller(chan)->id.number.valid, ast_channel_caller(chan)->id.number.str, "unknown"));
2340         ast_agi_send(fd, chan, "agi_calleridname: %s\n",
2341                 S_COR(ast_channel_caller(chan)->id.name.valid, ast_channel_caller(chan)->id.name.str, "unknown"));
2342         ast_agi_send(fd, chan, "agi_callingpres: %d\n",
2343                 ast_party_id_presentation(&ast_channel_caller(chan)->id));
2344         ast_agi_send(fd, chan, "agi_callingani2: %d\n", ast_channel_caller(chan)->ani2);
2345         ast_agi_send(fd, chan, "agi_callington: %d\n", ast_channel_caller(chan)->id.number.plan);
2346         ast_agi_send(fd, chan, "agi_callingtns: %d\n", ast_channel_dialed(chan)->transit_network_select);
2347         ast_agi_send(fd, chan, "agi_dnid: %s\n", S_OR(ast_channel_dialed(chan)->number.str, "unknown"));
2348         ast_agi_send(fd, chan, "agi_rdnis: %s\n",
2349                 S_COR(ast_channel_redirecting(chan)->from.number.valid, ast_channel_redirecting(chan)->from.number.str, "unknown"));
2350
2351         /* Context information */
2352         ast_agi_send(fd, chan, "agi_context: %s\n", ast_channel_context(chan));
2353         ast_agi_send(fd, chan, "agi_extension: %s\n", ast_channel_exten(chan));
2354         ast_agi_send(fd, chan, "agi_priority: %d\n", ast_channel_priority(chan));
2355         ast_agi_send(fd, chan, "agi_enhanced: %s\n", enhanced ? "1.0" : "0.0");
2356
2357         /* User information */
2358         ast_agi_send(fd, chan, "agi_accountcode: %s\n", ast_channel_accountcode(chan) ? ast_channel_accountcode(chan) : "");
2359         ast_agi_send(fd, chan, "agi_threadid: %ld\n", (long)pthread_self());
2360
2361         /* Send any parameters to the fastagi server that have been passed via the agi application */
2362         /* Agi application paramaters take the form of: AGI(/path/to/example/script|${EXTEN}) */
2363         for(count = 1; count < argc; count++)
2364                 ast_agi_send(fd, chan, "agi_arg_%d: %s\n", count, argv[count]);
2365
2366         /* End with empty return */
2367         ast_agi_send(fd, chan, "\n");
2368 }
2369
2370 static int handle_answer(struct ast_channel *chan, AGI *agi, int argc, const char * const argv[])
2371 {
2372         int res = 0;
2373
2374         /* Answer the channel */
2375         if (ast_channel_state(chan) != AST_STATE_UP)
2376                 res = ast_answer(chan);
2377
2378         ast_agi_send(agi->fd, chan, "200 result=%d\n", res);
2379         return (res >= 0) ? RESULT_SUCCESS : RESULT_FAILURE;
2380 }
2381
2382 static int handle_asyncagi_break(struct ast_channel *chan, AGI *agi, int argc, const char * const argv[])
2383 {
2384         ast_agi_send(agi->fd, chan, "200 result=0\n");
2385         return ASYNC_AGI_BREAK;
2386 }
2387
2388 static int handle_waitfordigit(struct ast_channel *chan, AGI *agi, int argc, const char * const argv[])
2389 {
2390         int res, to;
2391
2392         if (argc != 4)
2393                 return RESULT_SHOWUSAGE;
2394         if (sscanf(argv[3], "%30d", &to) != 1)
2395                 return RESULT_SHOWUSAGE;
2396         res = ast_waitfordigit_full(chan, to, agi->audio, agi->ctrl);
2397         ast_agi_send(agi->fd, chan, "200 result=%d\n", res);
2398         return (res >= 0) ? RESULT_SUCCESS : RESULT_FAILURE;
2399 }
2400
2401 static int handle_sendtext(struct ast_channel *chan, AGI *agi, int argc, const char * const argv[])
2402 {
2403         int res;
2404
2405         if (argc != 3)
2406                 return RESULT_SHOWUSAGE;
2407
2408         /* At the moment, the parser (perhaps broken) returns with
2409            the last argument PLUS the newline at the end of the input
2410            buffer. This probably needs to be fixed, but I wont do that
2411            because other stuff may break as a result. The right way
2412            would probably be to strip off the trailing newline before
2413            parsing, then here, add a newline at the end of the string
2414            before sending it to ast_sendtext --DUDE */
2415         res = ast_sendtext(chan, argv[2]);
2416         ast_agi_send(agi->fd, chan, "200 result=%d\n", res);
2417         return (res >= 0) ? RESULT_SUCCESS : RESULT_FAILURE;
2418 }
2419
2420 static int handle_recvchar(struct ast_channel *chan, AGI *agi, int argc, const char * const argv[])
2421 {
2422         int res;
2423
2424         if (argc != 3)
2425                 return RESULT_SHOWUSAGE;
2426
2427         res = ast_recvchar(chan,atoi(argv[2]));
2428         if (res == 0) {
2429                 ast_agi_send(agi->fd, chan, "200 result=%d (timeout)\n", res);
2430                 return RESULT_SUCCESS;
2431         }
2432         if (res > 0) {
2433                 ast_agi_send(agi->fd, chan, "200 result=%d\n", res);
2434                 return RESULT_SUCCESS;
2435         }
2436         ast_agi_send(agi->fd, chan, "200 result=%d (hangup)\n", res);
2437         return RESULT_FAILURE;
2438 }
2439
2440 static int handle_recvtext(struct ast_channel *chan, AGI *agi, int argc, const char * const argv[])
2441 {
2442         char *buf;
2443
2444         if (argc != 3)
2445                 return RESULT_SHOWUSAGE;
2446
2447         buf = ast_recvtext(chan, atoi(argv[2]));
2448         if (buf) {
2449                 ast_agi_send(agi->fd, chan, "200 result=1 (%s)\n", buf);
2450                 ast_free(buf);
2451         } else {
2452                 ast_agi_send(agi->fd, chan, "200 result=-1\n");
2453         }
2454         return RESULT_SUCCESS;
2455 }
2456
2457 static int handle_tddmode(struct ast_channel *chan, AGI *agi, int argc, const char * const argv[])
2458 {
2459         int res, x;
2460
2461         if (argc != 3)
2462                 return RESULT_SHOWUSAGE;
2463
2464         if (!strncasecmp(argv[2],"on",2)) {
2465                 x = 1;
2466         } else  {
2467                 x = 0;
2468         }
2469         if (!strncasecmp(argv[2],"mate",4))  {
2470                 x = 2;
2471         }
2472         if (!strncasecmp(argv[2],"tdd",3)) {
2473                 x = 1;
2474         }
2475         res = ast_channel_setoption(chan, AST_OPTION_TDD, &x, sizeof(char), 0);
2476         if (res) {
2477                 /* Set channel option failed */
2478                 ast_agi_send(agi->fd, chan, "200 result=0\n");
2479         } else {
2480                 ast_agi_send(agi->fd, chan, "200 result=1\n");
2481         }
2482         return RESULT_SUCCESS;
2483 }
2484
2485 static int handle_sendimage(struct ast_channel *chan, AGI *agi, int argc, const char * const argv[])
2486 {
2487         int res;
2488
2489         if (argc != 3) {
2490                 return RESULT_SHOWUSAGE;
2491         }
2492
2493         res = ast_send_image(chan, argv[2]);
2494         if (!ast_check_hangup(chan)) {
2495                 res = 0;
2496         }
2497         ast_agi_send(agi->fd, chan, "200 result=%d\n", res);
2498         return (res >= 0) ? RESULT_SUCCESS : RESULT_FAILURE;
2499 }
2500
2501 static int handle_controlstreamfile(struct ast_channel *chan, AGI *agi, int argc, const char * const argv[])
2502 {
2503         int res = 0, skipms = 3000;
2504         const char *fwd = "#", *rev = "*", *suspend = NULL, *stop = NULL;       /* Default values */
2505         char stopkeybuf[2];
2506         long offsetms = 0;
2507         char offsetbuf[20];
2508
2509         if (argc < 5 || argc > 10) {
2510                 return RESULT_SHOWUSAGE;
2511         }
2512
2513         if (!ast_strlen_zero(argv[4])) {
2514                 stop = argv[4];
2515         }
2516
2517         if ((argc > 5) && (sscanf(argv[5], "%30d", &skipms) != 1)) {
2518                 return RESULT_SHOWUSAGE;
2519         }
2520
2521         if (argc > 6 && !ast_strlen_zero(argv[6])) {
2522                 fwd = argv[6];
2523         }
2524
2525         if (argc > 7 && !ast_strlen_zero(argv[7])) {
2526                 rev = argv[7];
2527         }
2528
2529         if (argc > 8 && !ast_strlen_zero(argv[8])) {
2530                 suspend = argv[8];
2531         }
2532
2533         if (argc > 9 && (sscanf(argv[9], "%30ld", &offsetms) != 1)) {
2534                 return RESULT_SHOWUSAGE;
2535         }
2536
2537         res = ast_control_streamfile(chan, argv[3], fwd, rev, stop, suspend, NULL, skipms, &offsetms);
2538
2539         /* If we stopped on one of our stop keys, return 0  */
2540         if (res > 0 && stop && strchr(stop, res)) {
2541                 pbx_builtin_setvar_helper(chan, "CPLAYBACKSTATUS", "USERSTOPPED");
2542                 snprintf(stopkeybuf, sizeof(stopkeybuf), "%c", res);
2543                 pbx_builtin_setvar_helper(chan, "CPLAYBACKSTOPKEY", stopkeybuf);
2544         } else if (res > 0 && res == AST_CONTROL_STREAM_STOP) {
2545                 pbx_builtin_setvar_helper(chan, "CPLAYBACKSTATUS", "REMOTESTOPPED");
2546                 res = 0;
2547         } else {
2548                 if (res < 0) {
2549                         pbx_builtin_setvar_helper(chan, "CPLAYBACKSTATUS", "ERROR");
2550                 } else {
2551                         pbx_builtin_setvar_helper(chan, "CPLAYBACKSTATUS", "SUCCESS");
2552                 }
2553         }
2554
2555         snprintf(offsetbuf, sizeof(offsetbuf), "%ld", offsetms);
2556         pbx_builtin_setvar_helper(chan, "CPLAYBACKOFFSET", offsetbuf);
2557
2558         ast_agi_send(agi->fd, chan, "200 result=%d endpos=%ld\n", res, offsetms);
2559
2560         return (res >= 0) ? RESULT_SUCCESS : RESULT_FAILURE;
2561 }
2562
2563 static int handle_streamfile(struct ast_channel *chan, AGI *agi, int argc, const char * const argv[])
2564 {
2565         int res;
2566         struct ast_filestream *fs, *vfs;
2567         long sample_offset = 0, max_length;
2568         const char *edigits = "";
2569
2570         if (argc < 4 || argc > 5) {
2571                 return RESULT_SHOWUSAGE;
2572         }
2573
2574         if (argv[3]) {
2575                 edigits = argv[3];
2576         }
2577
2578         if ((argc > 4) && (sscanf(argv[4], "%30ld", &sample_offset) != 1)) {
2579                 return RESULT_SHOWUSAGE;
2580         }
2581
2582         if (!(fs = ast_openstream(chan, argv[2], ast_channel_language(chan)))) {
2583                 ast_agi_send(agi->fd, chan, "200 result=-1 endpos=%ld\n", sample_offset);
2584                 return RESULT_FAILURE;
2585         }
2586
2587         if ((vfs = ast_openvstream(chan, argv[2], ast_channel_language(chan)))) {
2588                 ast_debug(1, "Ooh, found a video stream, too\n");
2589         }
2590         ast_verb(3, "<%s> Playing '%s.%s' (escape_digits=%s) (sample_offset %ld) (language '%s')\n",
2591                 ast_channel_name(chan), argv[2], ast_format_get_name(ast_channel_writeformat(chan)),
2592                 edigits, sample_offset, S_OR(ast_channel_language(chan), "default"));
2593
2594         ast_seekstream(fs, 0, SEEK_END);
2595         max_length = ast_tellstream(fs);
2596         ast_seekstream(fs, sample_offset, SEEK_SET);
2597         res = ast_applystream(chan, fs);
2598         if (vfs) {
2599                 ast_applystream(chan, vfs);
2600         }
2601         ast_playstream(fs);
2602         if (vfs) {
2603                 ast_playstream(vfs);
2604         }
2605
2606         res = ast_waitstream_full(chan, argv[3], agi->audio, agi->ctrl);
2607         /* this is to check for if ast_waitstream closed the stream, we probably are at
2608          * the end of the stream, return that amount, else check for the amount */
2609         sample_offset = (ast_channel_stream(chan)) ? ast_tellstream(fs) : max_length;
2610         ast_stopstream(chan);
2611         if (res == 1) {
2612                 /* Stop this command, don't print a result line, as there is a new command */
2613                 return RESULT_SUCCESS;
2614         }
2615         ast_agi_send(agi->fd, chan, "200 result=%d endpos=%ld\n", res, sample_offset);
2616         pbx_builtin_setvar_helper(chan, "PLAYBACKSTATUS", res ? "FAILED" : "SUCCESS");
2617
2618         return (res >= 0) ? RESULT_SUCCESS : RESULT_FAILURE;
2619 }
2620
2621 /*! \brief get option - really similar to the handle_streamfile, but with a timeout */
2622 static int handle_getoption(struct ast_channel *chan, AGI *agi, int argc, const char * const argv[])
2623 {
2624         int res;
2625         struct ast_filestream *fs, *vfs;
2626         long sample_offset = 0, max_length;
2627         int timeout = 0;
2628         const char *edigits = "";
2629
2630         if ( argc < 4 || argc > 5 )
2631                 return RESULT_SHOWUSAGE;
2632
2633         if ( argv[3] )
2634                 edigits = argv[3];
2635
2636         if ( argc == 5 )
2637                 timeout = atoi(argv[4]);
2638         else if (ast_channel_pbx(chan)->dtimeoutms) {
2639                 /* by default dtimeout is set to 5sec */
2640                 timeout = ast_channel_pbx(chan)->dtimeoutms; /* in msec */
2641         }
2642
2643         if (!(fs = ast_openstream(chan, argv[2], ast_channel_language(chan)))) {
2644                 ast_agi_send(agi->fd, chan, "200 result=-1 endpos=%ld\n", sample_offset);
2645                 ast_log(LOG_WARNING, "Unable to open %s\n", argv[2]);
2646                 return RESULT_FAILURE;
2647         }
2648
2649         if ((vfs = ast_openvstream(chan, argv[2], ast_channel_language(chan))))
2650                 ast_debug(1, "Ooh, found a video stream, too\n");
2651
2652         ast_verb(3, "Playing '%s' (escape_digits=%s) (timeout %d)\n", argv[2], edigits, timeout);
2653
2654         ast_seekstream(fs, 0, SEEK_END);
2655         max_length = ast_tellstream(fs);
2656         ast_seekstream(fs, sample_offset, SEEK_SET);
2657         res = ast_applystream(chan, fs);
2658         if (vfs)
2659                 ast_applystream(chan, vfs);
2660         ast_playstream(fs);
2661         if (vfs)
2662                 ast_playstream(vfs);
2663
2664         res = ast_waitstream_full(chan, argv[3], agi->audio, agi->ctrl);
2665         /* this is to check for if ast_waitstream closed the stream, we probably are at
2666          * the end of the stream, return that amount, else check for the amount */
2667         sample_offset = (ast_channel_stream(chan))?ast_tellstream(fs):max_length;
2668         ast_stopstream(chan);
2669         if (res == 1) {
2670                 /* Stop this command, don't print a result line, as there is a new command */
2671                 return RESULT_SUCCESS;
2672         }
2673
2674         /* If the user didnt press a key, wait for digitTimeout*/
2675         if (res == 0 ) {
2676                 res = ast_waitfordigit_full(chan, timeout, agi->audio, agi->ctrl);
2677                 /* Make sure the new result is in the escape digits of the GET OPTION */
2678                 if ( !strchr(edigits,res) )
2679                         res=0;
2680         }
2681
2682         ast_agi_send(agi->fd, chan, "200 result=%d endpos=%ld\n", res, sample_offset);
2683         return (res >= 0) ? RESULT_SUCCESS : RESULT_FAILURE;
2684 }
2685
2686
2687
2688
2689 /*! \brief Say number in various language syntaxes */
2690 /* While waiting, we're sending a NULL.  */
2691 static int handle_saynumber(struct ast_channel *chan, AGI *agi, int argc, const char * const argv[])
2692 {
2693         int res, num;
2694
2695         if (argc < 4 || argc > 5)
2696                 return RESULT_SHOWUSAGE;
2697         if (sscanf(argv[2], "%30d", &num) != 1)
2698                 return RESULT_SHOWUSAGE;
2699         res = ast_say_number_full(chan, num, argv[3], ast_channel_language(chan), argc > 4 ? argv[4] : NULL, agi->audio, agi->ctrl);
2700         if (res == 1)
2701                 return RESULT_SUCCESS;
2702         ast_agi_send(agi->fd, chan, "200 result=%d\n", res);
2703         return (res >= 0) ? RESULT_SUCCESS : RESULT_FAILURE;
2704 }
2705
2706 static int handle_saydigits(struct ast_channel *chan, AGI *agi, int argc, const char * const argv[])
2707 {
2708         int res, num;
2709
2710         if (argc != 4)
2711                 return RESULT_SHOWUSAGE;
2712         if (sscanf(argv[2], "%30d", &num) != 1)
2713                 return RESULT_SHOWUSAGE;
2714
2715         res = ast_say_digit_str_full(chan, argv[2], argv[3], ast_channel_language(chan), agi->audio, agi->ctrl);
2716         if (res == 1) /* New command */
2717                 return RESULT_SUCCESS;
2718         ast_agi_send(agi->fd, chan, "200 result=%d\n", res);
2719         return (res >= 0) ? RESULT_SUCCESS : RESULT_FAILURE;
2720 }
2721
2722 static int handle_sayalpha(struct ast_channel *chan, AGI *agi, int argc, const char * const argv[])
2723 {
2724         int res;
2725         int sensitivity = AST_SAY_CASE_NONE;
2726
2727         if (argc < 4 || argc > 5) {
2728                 return RESULT_SHOWUSAGE;
2729         }
2730
2731         if (argc > 4) {
2732                 switch (argv[4][0]) {
2733                 case 'a':
2734                 case 'A':
2735                         sensitivity = AST_SAY_CASE_ALL;
2736                         break;
2737                 case 'l':
2738                 case 'L':
2739                         sensitivity = AST_SAY_CASE_LOWER;
2740                         break;
2741                 case 'n':
2742                 case 'N':
2743                         sensitivity = AST_SAY_CASE_NONE;
2744                         break;
2745                 case 'u':
2746                 case 'U':
2747                         sensitivity = AST_SAY_CASE_UPPER;
2748                         break;
2749                 case '\0':
2750                         break;
2751                 default:
2752                         return RESULT_SHOWUSAGE;
2753                 }
2754         }
2755         res = ast_say_character_str_full(chan, argv[2], argv[3], ast_channel_language(chan), sensitivity, agi->audio, agi->ctrl);
2756         if (res == 1) /* New command */
2757                 return RESULT_SUCCESS;
2758         ast_agi_send(agi->fd, chan, "200 result=%d\n", res);
2759         return (res >= 0) ? RESULT_SUCCESS : RESULT_FAILURE;
2760 }
2761
2762 static int handle_saydate(struct ast_channel *chan, AGI *agi, int argc, const char * const argv[])
2763 {
2764         int res, num;
2765
2766         if (argc != 4)
2767                 return RESULT_SHOWUSAGE;
2768         if (sscanf(argv[2], "%30d", &num) != 1)
2769                 return RESULT_SHOWUSAGE;
2770         res = ast_say_date(chan, num, argv[3], ast_channel_language(chan));
2771         if (res == 1)
2772                 return RESULT_SUCCESS;
2773         ast_agi_send(agi->fd, chan, "200 result=%d\n", res);
2774         return (res >= 0) ? RESULT_SUCCESS : RESULT_FAILURE;
2775 }
2776
2777 static int handle_saytime(struct ast_channel *chan, AGI *agi, int argc, const char * const argv[])
2778 {
2779         int res, num;
2780
2781         if (argc != 4)
2782                 return RESULT_SHOWUSAGE;
2783         if (sscanf(argv[2], "%30d", &num) != 1)
2784                 return RESULT_SHOWUSAGE;
2785         res = ast_say_time(chan, num, argv[3], ast_channel_language(chan));
2786         if (res == 1)
2787                 return RESULT_SUCCESS;
2788         ast_agi_send(agi->fd, chan, "200 result=%d\n", res);
2789         return (res >= 0) ? RESULT_SUCCESS : RESULT_FAILURE;
2790 }
2791
2792 static int handle_saydatetime(struct ast_channel *chan, AGI *agi, int argc, const char * const argv[])
2793 {
2794         int res = 0;
2795         time_t unixtime;
2796         const char *format, *zone = NULL;
2797
2798         if (argc < 4)
2799                 return RESULT_SHOWUSAGE;
2800
2801         if (argc > 4) {
2802                 format = argv[4];
2803         } else {
2804                 /* XXX this doesn't belong here, but in the 'say' module */
2805                 if (!strcasecmp(ast_channel_language(chan), "de")) {
2806                         format = "A dBY HMS";
2807                 } else {
2808                         format = "ABdY 'digits/at' IMp";
2809                 }
2810         }
2811
2812         if (argc > 5 && !ast_strlen_zero(argv[5]))
2813                 zone = argv[5];
2814
2815         if (ast_get_time_t(argv[2], &unixtime, 0, NULL))
2816                 return RESULT_SHOWUSAGE;
2817
2818         res = ast_say_date_with_format(chan, unixtime, argv[3], ast_channel_language(chan), format, zone);
2819         if (res == 1)
2820                 return RESULT_SUCCESS;
2821
2822         ast_agi_send(agi->fd, chan, "200 result=%d\n", res);
2823         return (res >= 0) ? RESULT_SUCCESS : RESULT_FAILURE;
2824 }
2825
2826 static int handle_sayphonetic(struct ast_channel *chan, AGI *agi, int argc, const char * const argv[])
2827 {
2828         int res;
2829
2830         if (argc != 4)
2831                 return RESULT_SHOWUSAGE;
2832
2833         res = ast_say_phonetic_str_full(chan, argv[2], argv[3], ast_channel_language(chan), agi->audio, agi->ctrl);
2834         if (res == 1) /* New command */
2835                 return RESULT_SUCCESS;
2836         ast_agi_send(agi->fd, chan, "200 result=%d\n", res);
2837         return (res >= 0) ? RESULT_SUCCESS : RESULT_FAILURE;
2838 }
2839
2840 static int handle_getdata(struct ast_channel *chan, AGI *agi, int argc, const char * const argv[])
2841 {
2842         int res, max, timeout;
2843         char data[1024];
2844
2845         if (argc < 3)
2846                 return RESULT_SHOWUSAGE;
2847         if (argc >= 4)
2848                 timeout = atoi(argv[3]);
2849         else
2850                 timeout = 0;
2851         if (argc >= 5)
2852                 max = atoi(argv[4]);
2853         else
2854                 max = 1024;
2855         res = ast_app_getdata_full(chan, argv[2], data, max, timeout, agi->audio, agi->ctrl);
2856         if (res == 2)                   /* New command */
2857                 return RESULT_SUCCESS;
2858         else if (res == 1)
2859                 ast_agi_send(agi->fd, chan, "200 result=%s (timeout)\n", data);
2860         else if (res < 0 )
2861                 ast_agi_send(agi->fd, chan, "200 result=-1\n");
2862         else
2863                 ast_agi_send(agi->fd, chan, "200 result=%s\n", data);
2864         return RESULT_SUCCESS;
2865 }
2866
2867 static int handle_setcontext(struct ast_channel *chan, AGI *agi, int argc, const char * const argv[])
2868 {
2869
2870         if (argc != 3)
2871                 return RESULT_SHOWUSAGE;
2872         ast_channel_context_set(chan, argv[2]);
2873         ast_agi_send(agi->fd, chan, "200 result=0\n");
2874         return RESULT_SUCCESS;
2875 }
2876
2877 static int handle_setextension(struct ast_channel *chan, AGI *agi, int argc, const char * const argv[])
2878 {
2879         if (argc != 3)
2880                 return RESULT_SHOWUSAGE;
2881         ast_channel_exten_set(chan, argv[2]);
2882         ast_agi_send(agi->fd, chan, "200 result=0\n");
2883         return RESULT_SUCCESS;
2884 }
2885
2886 static int handle_setpriority(struct ast_channel *chan, AGI *agi, int argc, const char * const argv[])
2887 {
2888         int pri;
2889
2890         if (argc != 3)
2891                 return RESULT_SHOWUSAGE;
2892
2893         if (sscanf(argv[2], "%30d", &pri) != 1) {
2894                 pri = ast_findlabel_extension(chan, ast_channel_context(chan), ast_channel_exten(chan), argv[2],
2895                         S_COR(ast_channel_caller(chan)->id.number.valid, ast_channel_caller(chan)->id.number.str, NULL));
2896                 if (pri < 1)
2897                         return RESULT_SHOWUSAGE;
2898         }
2899
2900         ast_explicit_goto(chan, NULL, NULL, pri);
2901         ast_agi_send(agi->fd, chan, "200 result=0\n");
2902         return RESULT_SUCCESS;
2903 }
2904
2905 static int handle_recordfile(struct ast_channel *chan, AGI *agi, int argc, const char * const argv[])
2906 {
2907         struct ast_filestream *fs;
2908         struct ast_frame *f;
2909         struct timeval start;
2910         long sample_offset = 0;
2911         int res = 0;
2912         int ms;
2913
2914         struct ast_dsp *sildet=NULL;         /* silence detector dsp */
2915         int totalsilence = 0;
2916         int dspsilence = 0;
2917         int silence = 0;                /* amount of silence to allow */
2918         int gotsilence = 0;             /* did we timeout for silence? */
2919         char *silencestr = NULL;
2920         RAII_VAR(struct ast_format *, rfmt, NULL, ao2_cleanup);
2921
2922         /* XXX EAGI FIXME XXX */
2923
2924         if (argc < 6)
2925                 return RESULT_SHOWUSAGE;
2926         if (sscanf(argv[5], "%30d", &ms) != 1)
2927                 return RESULT_SHOWUSAGE;
2928
2929         if (argc > 6)
2930                 silencestr = strchr(argv[6],'s');
2931         if ((argc > 7) && (!silencestr))
2932                 silencestr = strchr(argv[7],'s');
2933         if ((argc > 8) && (!silencestr))
2934                 silencestr = strchr(argv[8],'s');
2935
2936         if (silencestr) {
2937                 if (strlen(silencestr) > 2) {
2938                         if ((silencestr[0] == 's') && (silencestr[1] == '=')) {
2939                                 silencestr++;
2940                                 silencestr++;
2941                                 if (silencestr)
2942                                         silence = atoi(silencestr);
2943                                 if (silence > 0)
2944                                         silence *= 1000;
2945                         }
2946                 }
2947         }
2948
2949         if (silence > 0) {
2950                 rfmt = ao2_bump(ast_channel_readformat(chan));
2951                 res = ast_set_read_format(chan, ast_format_slin);
2952                 if (res < 0) {
2953                         ast_log(LOG_WARNING, "Unable to set to linear mode, giving up\n");
2954                         ast_agi_send(agi->fd, chan, "200 result=%d\n", res);
2955                         return RESULT_FAILURE;
2956                 }
2957                 sildet = ast_dsp_new();
2958                 if (!sildet) {
2959                         ast_log(LOG_WARNING, "Unable to create silence detector :(\n");
2960                         ast_agi_send(agi->fd, chan, "200 result=-1\n");
2961                         return RESULT_FAILURE;
2962                 }