User's Manual

32 Voice API Programming Guide — June 2005
Application Development Guidelines
6.1.2 Setting Termination Conditions for I/O Functions
When an I/O function is issued, you must pass a set of termination conditions as one of the function
parameters. Termination conditions are events monitored during the I/O process that will cause an
I/O function to terminate. When the termination condition is met, a termination reason is returned
by ATDX_TERMMSK( ). If the I/O function is running in synchronous mode, the
ATDX_TERMMSK( ) function returns a termination reason after the I/O function has completed.
If the I/O function is running in asynchronous mode, the ATDX_TERMMSK( ) function returns a
termination reason after the function termination event has arrived. I/O functions can terminate
under several conditions as described later in this section.
You can predict events that will occur during I/O (such as a digit being received or the call being
disconnected) and set termination conditions accordingly. The flow of control in a voice
application is based on the termination condition. Setting these conditions properly allows you to
build voice applications that can anticipate a caller's actions.
To set the termination conditions, values are placed in fields of a DV_TPT structure. If you set
more than one termination condition, the first one that occurs will terminate the I/O function. The
DV_TPT structures can be configured as a linked list or array, with each DV_TPT specifying a
single terminating condition. For more information on the DV_TPT structure, which is defined in
srllib.h, see the Voice API Library Reference.
The termination conditions are described in the following paragraphs.
byte transfer count
This termination condition applies when playing or recording a file with dx_play( ) or
dx_rec( ). The maximum number of bytes is set in the DX_IOTT structure. This condition will
cause termination if the maximum number of bytes is used before one of the termination
conditions specified in the DV_TPT occurs. For information about setting the number of bytes
in the DX_IOTT, see the Voice API Library Reference.
dx_stopch( ) occurred
The dx_stopch( ) function will terminate any I/O function, except dx_dial( ) (with call
progress analysis disabled) or dx_wink( ), and stop the device. See the dx_stopch( ) function
description for more detailed information about this function.
end of file reached
This termination condition applies when playing a file. This condition will cause termination if
-1 has been specified in the io_length field of the DX_IOTT, and no other termination
condition has occurred before the end of the file is reached. For information about setting the
DX_IOTT, see the Voice API Library Reference. When this termination condition is met, a
TM_EOD termination reason is returned from ATDX_TERMMSK( ).
loop current drop (DX_LCOFF)
This termination condition is not supported on DM3 boards using the voice library; however
support is available via call control API. For more information, see the Global Call Analog
Technology User’s Guide.
In some central offices, switches, and PBXs, a drop in loop current indicates disconnect
supervision. An I/O function can terminate if the loop current drops for a specified amount of
time. The amount of time is specified in the tp_length field of a DV_TPT structure. The
amount of time can be specified in 100 msec units (default) or 10 msec units. 10 msec can be