add ExternalIVR() application

git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@6317 65c4cc65-6c06-0410-ace0-fbb531ad65f3

doc/README.externalivr

@@ -0,0 +1,96 @@
+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.
+
+