diff options
Diffstat (limited to 'trunk/doc/externalivr.txt')
| -rw-r--r-- | trunk/doc/externalivr.txt | 117 |
1 files changed, 0 insertions, 117 deletions
diff --git a/trunk/doc/externalivr.txt b/trunk/doc/externalivr.txt deleted file mode 100644 index 73fb5820f..000000000 --- a/trunk/doc/externalivr.txt +++ /dev/null @@ -1,117 +0,0 @@ -Asterisk External IVR Interface -------------------------------- - -If you load app_externalivr.so in your Asterisk instance, you will -have an ExternalIVR() application available in your dialplan. This -application implements a simple protocol for bidirectional -communication with an external process, while simultaneous playing -audio files to the connected channel (without interruption or -blocking). - -The arguments to ExternalIVR() consist of the command to execute and -any arguments to pass to it, the same as the System() application -accepts. The external command will be executed in a child process, -with its standard file handles connected to the Asterisk process as -follows: - -stdin (0) - DTMF and hangup events will be received on this handle -stdout (1) - Playback and hangup commands can be sent on this handle -stderr (2) - Error messages can be sent on this handle - -The application will also create an audio generator to play audio to -the channel, and will start playing silence. When your application -wants to send audio to the channel, it can send a command (see below) -to add file(s) to the generator's playlist. The generator will then -work its way through the list, playing each file in turn until it -either runs out of files to play, the channel is hung up, or a command -is received to clear the list and start with a new file. At any time, -more files can be added to the list and the generator will play them -in sequence. - -While the generator is playing audio (or silence), any DTMF events -received on the channel will be sent to the child process (see -below). Note that this can happen at any time, since the generator, -the child process and the channel thread are all executing -independently. It is very important that your external application be -ready to receive events from Asterisk at all times (without blocking), -or you could cause the channel to become non-responsive. - -If the child process dies, ExternalIVR() will notice this and hang up -the channel immediately (and also send a message to the log). - -DTMF (and other) events ------------------------ - -All events will be newline-terminated strings. - -Events send to the child's stdin will be in the following format: - -tag,timestamp[,data] - -The tag can be one of the following characters: - -0-9: DTMF event for keys 0 through 9 -A-D: DTMF event for keys A through D -*: DTMF event for key * -#: DTMF event for key # -H: the channel was hung up by the connected party -E: the script requested an exit -Z: the previous command was unable to be executed (file does not -exist, etc.) -T: the play list was interrupted (see below) -D: a file was dropped from the play list due to interruption (the -data element will be the dropped file name) -F: a file has finished playing (the data element will be the file -name) - -The timestamp will be 10 digits long, and will be a decimal -representation of a standard Unix epoch-based timestamp. - -Commands --------- - -All commands must be newline-terminated strings. - -The child process can send commands on stdout in the following formats: - -S,filename -A,filename -H,message -E,message -O,option -V,name=value - -The 'S' command checks to see if there is a playable audio file with -the specified name, and if so, clear's the generator's playlist and -places the file onto the list. Note that the playability check does -not take into account transcoding requirements, so it is possible for -the file to not be played even though it was found. If the file cannot -be found, a 'Z' event (see above) will be sent to the child. If the -generator is not currently playing silence, then T and D events will -be sent to the child to signal the playlist interruption and notify -it of the files that will not be played. - -The 'A' command checks to see if there is a playable audio file with -the specified name, and if so, adds it to the generator's -playlist. The same playability and exception rules apply as for the -'S' command. - -The 'E' command stops the generator and continues execution in the dialplan, -and logs the supplied message to the Asterisk log. - -The 'H' command stops the generator and hangs up the channel, and logs -the supplied message to the Asterisk log. - -The 'O' command allows the child to set/clear options in the -ExternalIVR() application. The supported options are: - autoclear/noautoclear: - Automatically interrupt and clear the playlist upon reception - of DTMF input. - -The 'V' command sets the specified channel variable to the specified value. - -Errors ------- - -Any newline-terminated output generated by the child process on its -stderr handle will be copied into the Asterisk log. |