[Asterisk-cvs] asterisk/doc README.externalivr,NONE,1.1

[kpfleming]

Update of /usr/cvsroot/asterisk/doc
In directory mongoose.digium.com:/tmp/cvs-serv23123/doc

Added Files:
	README.externalivr 
Log Message:
add ExternalIVR() application


--- NEW FILE: README.externalivr ---
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

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
Z: the previous command was unable to be executed (file does not
exist, etc.)

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

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.

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 'H' command stops the generator and hangs up the channel, and logs
the supplied message to the Asterisk log.

Errors
------

Any newline-terminated output generated by the child process on its
stderr handle will be copied into the Asterisk log.