Updated ExternalIVR documentation

Rewrote a large portion of the existing documentation
and added information about the TCP/IP socket interface


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

doc/externalivr.txt

@@ -8,52 +8,75 @@ 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
+There are two ways to use ExternalIVR(); you can execute an
-any arguments to pass to it, the same as the System() application
+application on the local system or you can establish a socket
-accepts. The external command can be executed in a child process,
+connection to a TCP/IP socket server.
-with its standard file handles connected to the Asterisk process as
-follows:
 
-stdin (0) - DTMF and hangup events will be received on this handle
+To execute a local application use the form:
-stdout (1) - Playback and hangup commands can be sent on this handle
+ExternalIVR(/full/path/to/applcation[(arguments)],options)
-stderr (2) - Error messages can be sent on this handle
 
-The application will also create an audio generator to play audio to
+The arguments are optional, however if they exist they must be
-the channel, and will start playing silence. When your application
+enclosed in parentheses. The external application will be executed
-wants to send audio to the channel, it can send a command (see below)
+in a child process, with its standard file handles connected to the
-to add a file to the generator's playlist. The generator will then
+Asterisk process as follows:
-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
+stdin (0)  - events will be received on this handle
-is received to clear the list and start with a new file. At any time,
+stdout (1) - commands can be sent on this handle
-more files can be added to the list and the generator will play them
+stderr (2) - messages can be sent on this handle
-in sequence.
+* Use of stderr for message communication is discouraged because
+it is not supported by a socket connection.
+
+To create a socket connection use the form:
+ExternalIVR(ivr://host[:port][(arguments)],options)
+
+The host can be a fqdn or an ip address. The port is optional, if
+not specified the default of 2949 will be used. The arguments are
+optional however if they exist they must be enclosed in parentheses.
+TheExternalIVR application will connect to the specified socket
+server and establish a bi-directional socket connection, where
+events will be sent to the TCP/IP server and commands received
+from it.
+
+The specific ExternalIVR options, events and commands are detailed
+below.
+
+Upon execution, if not specifically prevented by an option, the
+ExternalIVR application will answer the channel (if it's not
+already answered), create an audio generator, and start playing
+silence. When your application wants to send audio to the channel,
+it can send a command (see below) to add a file 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
+independently. It is very important that your external application
-ready to receive events from Asterisk at all times (without blocking),
+be ready to receive events from Asterisk at all times (without
-or you could cause the channel to become non-responsive.
+blocking), or you could cause the channel to become non-responsive.
 
-If the child process dies, ExternalIVR() will notice this and hang up
+If the child process dies, or the remote server disconnects,
-the channel immediately (and also send a message to the log).
+ExternalIVR() will notice this and hang up the channel
+immediately (and also send a message to the log).
 
 ExternalIVR() Options
-----------------------
+---------------------
 n: 'n'oanswer, don't answer an otherwise unanswered channel.
 i: 'i'gnore_hangup, instead of sending an 'H' event and exiting
-ExternalIVR() upon channel hangup, it instead sends an 'I' event
+   ExternalIVR() upon channel hangup, it instead sends an 'I'
-and expects the external application to exit the process.
+   event and expects the external application to exit the process.
 d: 'd'ead, allows the operation of ExternalIVR() on channels that
-have already been hung up.
+   have already been hung up.
 
-DTMF (and other) events
+Events
------------------------
+------
 
-All events will be newline-terminated strings.
+All events are be newline-terminated strings and are sent in the
-
+following format:
-Events sent to the child's stdin will be in the following format:
 
 tag,timestamp[,data]
 
@@ -65,18 +88,20 @@ A-D: DTMF event for keys A through D
 #: 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
+Z: the previous command was unable to be executed. There may be a
+   data element if appropriate, see specific commands below for
+   details
 T: the play list was interrupted (see S command below)
 D: a file was dropped from the play list due to interruption (the
-data element will be the dropped file name) NOTE: this tag conflicts
+   data element will be the dropped file name) NOTE: this tag
-with the D DTMF event tag. The existence of the data element is used
+   conflicts with the D DTMF event tag. The existence of the data
-to differentiate between the two cases
+   element is used to differentiate between the two cases
 F: a file has finished playing (the data element will be the file
-name)
+   name)
 P: a response to the 'P' command (see below)
 G: a response to the 'G' command (see below)
 I: a Inform message, meant to "inform" the client that something
-has occured.  (see Inform Messages below)
+   has occurred.  (see Inform Messages below)
 
 The timestamp will be 10 digits long, and will be a decimal
 representation of a standard Unix epoch-based timestamp.
@@ -84,9 +109,9 @@ representation of a standard Unix epoch-based timestamp.
 Commands
 --------
 
-All commands must be newline-terminated strings.
+All commands are newline-terminated strings.
 
-The child process can send commands on stdout in the following formats:
+The child process can send one of the following commands:
 
 S,filename
 A,filename
@@ -106,27 +131,29 @@ 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 does
 not exist it sends a Z response with the data element set to the file
 requested. If the generator is not currently playing silence, then T
-and D events will be sent to the child to signal the playlist
+and D events will be sent to signal the playlist interruption and
-interruption and notify it of the files that will not be played.
+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
+the specified name, and if so, appends it to the generator's playlist.
-playlist. The same playability and exception rules apply as for the
+The same playability and exception rules apply as for the 'S' command.
-'S' command.
 
-The 'E' command stops the generator and continues execution in the dialplan,
+The 'E' command logs the supplied message to the Asterisk log, stops
-and logs the supplied message to the Asterisk log.
+the generator and terminates the ExternalIVR application, but continues
+execution in the dialplan.
 
-The 'H' command stops the generator and hangs up the channel, and logs
+The 'H' command logs the supplied message to the Asterisk log, stops
-the supplied message to the Asterisk log.
+the generator, hangs up the channel and terminates the ExternalIVR
+application.
 
 The 'O' command allows the child to set/clear options in the
-ExternalIVR() application. The supported options are:
+ExternalIVR() application.
-	autoclear/noautoclear:
-	Automatically interrupt and clear the playlist upon reception
-	of DTMF input.
 
-The 'T' command will answer and unanswered channel.  If it fails either
+The supported options are:
+(no)autoclear: Automatically interrupt and clear the playlist
+               upon reception of DTMF input.
+
+The 'T' command will answer an unanswered channel. If it fails either
 answering the channel or starting the generator it sends a Z response
 of "Z,TIMESTAMP,ANSWER_FAILED" or "Z,TIMESTAMP,GENERATOR_FAILED"
 respectively.
@@ -139,12 +166,23 @@ variables are separated by commas.  Response is in name=value format.
 
 The 'P' command gets the parameters passed into ExternalIVR() minus
 the options to ExternalIVR() itself:
-	If ExternalIVR() is executed as:
+        If ExternalIVR() is executed as:
-		ExternalIVR(/usr/bin/foo(arg1,arg2),n)
+                ExternalIVR(/usr/bin/foo(arg1,arg2),n)
-	The response to the 'P' command would be:
+        The response to the 'P' command would be:
-		P,TIMESTAMP,/usr/bin/foo|arg1|arg2
+                P,TIMESTAMP,/usr/bin/foo,arg1,arg2
+NOTE: This is the only way for a TCP/IP server to be able to get retrieve
+the arguments.
 
-The 'L' command puts a message into the Asterisk log.
+The 'L' command puts a message into the Asterisk log. NOTE: This is
+prefered to using stderr and is the only way for a TCP/IP server to
+log a message.
+
+Inform Messages
+---------------
+
+The only inform message that currently exists is a HANGUP message,
+in the form I,TIMESTAMP,HANGUP and is used to inform of a hangup
+when the i option is specified.
 
 Errors
 ------