readme.shell

multi-line Adjunct Communication Server

Telephony Gateway Interface Draft Specification 1.0

The ACS shell command is now compliant with the draft 1.0 specification
for "Telephony Gateway Interface".  TGI specifies how a telephony server
such as ACS can securely invoke external programs and scripts written in
other languages.  TGI uses environment space to pass command line 
arguments to TGI applications so that these arguments cannot be observed
through a "ps" command.  TGI also uses a control fifo as the TGI programs
"stdout" to enable external programs to directly issue commands and set
variables back inside the telephony server.

While TGI has been developed specifically for ACS, the specification
should allow TGI to be implimented for any telephony server with a need to
securely invoke external images.

All TGI applications and external scripting languages are invoked from an
executable found in "libexec/tgi" (examples: /usr/libexec/tgi,
/opt/ACS/libexec/tgi).  This default directory assures that no arbitrary
images are invoked outside of the telephony server from the search path.

All TGI applications are assumed to return an "exit" code when they
terminate.  This exit code can then be passed into the telephony server.

All TGI applications receives a number of system configuration variables
in environment space.  These symbols include:

SERVER_VERSION	(1.0)

	Version of TGI protocol this server impliments.

SERVER_PLATFORM	(pika)

	Base hardware platform this server has been built for.

SERVER_SOFTWARE	(ACS)

	Telephony server software being used.

SERVER_RUNTIME (/var/ACS)

	Working directory for telephony server runtime databases.

SERVER_PROMPTS (/usr/share/aaprompts)

	Directory where primary telephony server audio prompts are stored.

SERVER_LIBEXEC (/usr/libexec/tgi)

	Path where all TGI applications are presumed to be stored.

In addition, since a TGI program is invoked to provide external processing
for a specific telephone line, a number of "transient" or session specific
variables are also passed through environment space.  Many of these
variables are optional.  The only required environment variable that must
be specified is "PORT_NUMBER".

PORT_NUMBER	(1-x)

	The telephony port this script or image is being invoked for.
	Most servers will number telephony ports starting from "1".  This
	port is required when using stdout to send commands back into the
	server.

PORT_QUERY	(-a&-c)

	This symbol holds any command line arguments that would normally
	have been passed to the external program.  Using environment space
	assures that any key data (for example, a credit card number) can
	not be viewed through a simple "ps" by any arbitrary user on the
	machine.  The "&" is used to seperate command line arguments, as
	in CGI "QUERY_STRING".

PORT_DIGITS

	If there are DTMF digits pending in the telephony servers buffer
	for the specified port, those digits are passed here as a string.

PORT_DNID

	This would hold a DNIS or DID number when such information exists
	for the specified port.

PORT_ANI

	This would hold the calling parties telephone number if the server
	has such information.  ANI also represents the "telephone number"
	portion of caller id systems, or calling party from SMDI.

PORT_CID

	This represents the "raw" caller ID string if one was retrieved
	from a CO for the current line.  Caller ID strings may hold ascii
	data and other information beyond simple telephone numbers, and so
	is considered seperate from PORT_ANI.

Finally, as noted, TGI applications should be able to send values back into
the telephony server using stdout.  The exact implimentation of stdout may
vary from one server to another, but the critical subset of commands that
should be issued with an ACS server may include:

SET port sym  value

Sets a symbol for the specified "port".  The "port" value used should be the
same as the "PORT_NUMBER" passed in the environment space.  In ACS "sym" can
be var0 .. var9, temp0 .. temp3, or "digits".  If "digits" is used, then the
current content of the DTMF input buffer is replaced with the value passed.
Any value that represents an unknown symbol will be given a symbol in the
ACS process environment space that can be retrieved by the referencing
port through it's "^sym" name.

PUT sym value

This may be used to set a global symbol in the ACS envornment space which
may be retreived by it's "@sym" name.

IDLE port

Forces specified port to disconnect the caller.  The "port" value used
should be the same as the "PORT_NUMBER" passed in the environment space.

While any command found under umdctrl(8) can be issued by a TGI application,
the above represents the most appropriate subset to use.