• 3.1.1. Opening and Using Devices
• 3.1.2. Opening and Using Voice Files
• 3.1.3. Busy and Idle States
• 3.1.4. I/O Terminations
• 3.1.5. Error Handling
• 3.1.6. Voice Library Include Files
• 3.1.7. Compiling Applications
• 3.1.8. C Language Interfaces
• 3.1.9. Run-Time Linking

3. Using the Voice Software

3.1. Voice Programming Requirements

This section contains information that is required when using the Voice Library and many of its functions. The following topics are covered:

• Opening and Using Devices
• Opening and Using Voice Channels
• Busy and Idle Device States
• I/O Terminations
• Error Handling
• Voice Library Include Files
• Compiling Applications

3.1.1. Opening and Using Devices

When you open a file under Windows, it returns a unique file descriptor for that file. The following is an example of a file descriptor:

int file_descriptor;

file_descriptor = open(filename, mode);

Any subsequent action you wish to perform on that file is accomplished by identifying the file using file_descriptor. No action can be performed on the file until it is first opened.

Dialogic boards and channels work in a similar manner. You must first open a Voice device using dx_open( ) before you can perform any operation on it. When you open a channel using dx_open( ), the value returned is a unique Dialogic device handle for that particular open process on that channel. The Dialogic channel device handle is referred to as chdev, where

int chdev;

chdev = dx_open(channel_name,mode)

Any time you wish to use a Voice library function on the channel, you must identify the channel with its Dialogic channel device handle, chdev. The channel name is used only when opening a channel, and all actions after opening must use the handle chdev. Board devices are opened by following the same procedure, where bddev refers to the Dialogic board device handle.

NOTE:

As stated above, boards and channels are considered separate devices under Windows. It is possible to open and use a channel without ever opening the board it is on. There is no board-channel hierarchy imposed by the driver.

To enable users to control the boards and the channels under the Windows operating system, Dialogic provides a library of C language functions. For details on opening and closing channels and boards, see the dx_open( ) and dx_close( ) functions.

CAUTION

Dialogic devices should never be opened using the Windows open( ).

3.1.2. Opening and Using Voice Files

The Voice library provides a set of standard I/O routines. Although applications may use the routines provided with the Microsoft C Runtime Library, Dialogic recommends that the application use the Dialogic file handling routines when manipulating voice files. These routines are dx_fileopen( ) for opening voice files, dx_fileclose( ) for closing voice files, and dx_fileseek( ), dx_fileread( ), and dx_filewrite( ) for searching for, reading, or writing directly to a file. The arguments for these functions are identical to the equivalent "C" run-time functions.

3.1.3. Busy and Idle States

Some library functions are dependent on the state of the device when the function call is made. A device is in an idle state when it is not being used, and in a busy state when it is dialing, stopped, being configured, or being used for other I/O functions. Idle represents a single state; busy represents the set of states that a device may be in when it is not idle. State-dependent functions do not make a distinction between the individual states represented by the term "busy." They only distinguish between idle and busy states. The categories of functions and their state dependencies are described in the following sections.

3.1.4. I/O Terminations

Pass a set of termination conditions as one of the function parameters when an I/O function is issued. Termination conditions are events monitored during the I/O process that cause an I/O function to terminate. When the termination condition is met, ATDX_TERMMSK( ) returns the reason for termination. I/O functions can terminate under the following conditions:

• byte transfer count is satisfied
• device has stopped due to dx_stopch( )
• end of file is reached during a play
• loop current has dropped for a period of time
• maximum delay between DTMF digits is detected
• maximum number of digits has been received
• maximum period of non-silence (noise or meaningful sound) has been detected
• maximum period of silence has been detected
• pattern of silence and non-silence (noise or meaningful sound) has been detected
• specific digit has been received
• I/O function has been executing for a maximum period of time
• user-defined digit has been received
• user-defined tone-on or tone-off has been detected (GTD)

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. The DV_TPT structure, which is defined in srllib.h, is described in detail in the Voice Software Reference: Standard Runtime Library. Voice board values for the DV_TPT are contained. 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. See the DX_IOTT structure in the chapter on Data Structures for information about setting the number of bytes in the DX_IOTT.

Stop Occurred - dx_stopch( ) terminates any I/O function, except for dx_dial( ) without Call Analysis enabled, and dx_wink( ). 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 causes 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. ATDX_TERMMSK( ) returns the termination reason TM_EOD when this termination condition is met. See the DX_IOTT structure in the chapter on Data Structures for information about setting the DX_IOTT.

Loop Current Drop - In some central offices, switches, and PBX's, 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. Specify the amount of time in the tp_length field of a DV_TPT structure in 100 ms units (default) or 10 ms units. Specify 10 ms in the tp_flags field of the DV_TPT structure. ATDX_TERMMSK( ) returns the termination reason TM_LCOFF when this termination condition is met.

Maximum Delay Between Digits - This termination condition monitors the length of time between the digits being received. A specific length of time can be placed in the tp_length field of a DV_TPT. If the time between receiving digits is more than this period of time, the function terminates. Specify the amount of time in 100 ms units (default) or 10 ms units for the tp_length field or 10 ms units for the tp_flags field. ATDX_TERMMSK( ) returns the termination reason TM_IDDTIME when this termination condition is met.

Maximum Digits Received - This termination condition counts the number of digits in the channel's digit buffer. If the buffer is not empty before the I/O function is called, the condition counts the digits remaining in the buffer as well. To set the maximum number of digits received before termination, place a number from 1 to 31 in the tp_length field of a DV_TPT. ATDX_TERMMSK( ) returns the termination reason TM_MAXDTMF when this termination condition is met.

Maximum Length of Non-silence - Non-silence is the absence of silence: noise or meaningful sound, such as a person speaking. Enable this condition by setting the tp_length field of a DV_TPT to a specific period of time. When the application detects non-silence for this length of time, the I/O function terminates. This termination condition is frequently used to detect dial tone or the howler tone that is used by central offices to indicate that a phone has been off-hook for an extended period of time. Specify the amount of time in 100 ms units (default) or 10 ms units in the tp_length field or 10 ms units in the tp_flags field of the DV_TPT structure. ATDX_TERMMSK( ) returns the termination reason TM_MAXNOSIL when this termination condition is met.

Maximum Length of Silence - Enable this termination condition by setting the tp_length field of a DV_TPT. The specified value is the length of time that continuous silence will be detected before it terminates the I/O function. The amount of time can be specified in 100 ms units (default) or 10 ms units for the tp_length field or 10 ms units in the tp_flags field of the DV_TPT structure. ATDX_TERMMSK( ) returns the termination reason TM_MAXSIL when this termination condition is met.

Pattern of Silence and Non-silence - A known pattern of silence and non-silence can terminate a function. A pattern can be specified by specifying DX_PMON and DX_PMOFF in the tp_termno field in two separate DV_TPT structures, where one represents a period of silence and one represents a period of non-silence. ATDX_TERMMSK( ) returns the termination reason TM_PATTERN when this termination condition is met.

DX_PMOFF/DX_PMON termination conditions must be used together. The DX_PMON terminating condition must directly follow the DX_PMOFF terminating condition. A combination of both DV_TPT structures using these conditions is used to form a single termination condition. A detailed description of how to set these termination conditions is described in Appendix A under the topic Using DX_PMON and DX_PMOFF.

Specific Digit Received - An application collects the digits received during an I/O function in a channel's digit buffer. If the buffer is not empty before an I/O function executes, the application treats the digits in the buffer as if the digits were received during the I/O execution. Enable this termination condition by specifying a digit bit mask in the tp_length field of a DV_TPT structure. If any digit specified in the bit mask appears in the digit buffer, the I/O function will terminate. ATDX_TERMMSK( ) returns the termination reason TM_DIGIT when this termination condition is met.

Maximum Function Time - Place a time limit on the I/O function by seeting the tp_length field of a DV_TPT to a specific length of time in 100 ms units. The I/O function terminates when it executes longer than this period of time. Specify the amount of time in 100 ms units (default) or 10 ms units for the tp_length field and 10 ms units in the tp_flags field of the DV_TPT. ATDX_TERMMSK( ) returns the termination reason TM_MAXTIME when this termination condition is met.

User-Defined Digit Received - An application collects user-defined digits in a channel's digit buffer during an I/O function. If the buffer is not empty before an I/O function executes, the application treats the digits in the buffer as if received during the I/O execution. This termination condition is enabled by specifying the digit and digit type in the tp_length field of a DV_TPT structure. If any digit specified in the bit mask appears in the digit buffer, the I/O function terminates. ATDX_TERMMSK( ) returns the termination reason TM_DIGIT when this termination condition is met.

User-Defined Tone On/Off Event Detected - A user-defined tone on/off event can be used as a termination condition. Before specifying a user-defined tone as a termination condition, define the tone using one of the dx_blddt( ), dx_blddtcad( ), dx_bldst( ), or dx_bldstcad( ) Global Tone Detection functions, and enable the tone detection on the channel using the dx_addtone( ) or dx_enbtone( ) functions. To set tone on/off to be a termination condition, specify DX_TONE in the tp_termno field of the DV_TPT. You must also specify DX_TONEON or DX_TONEOFF in the tp_data field. ATDX_TERMMSK( ) returns the termination reason TM_TONE when this termination condition is met.

The application may clear the DV_TPT structure using dx_clrtpt( ) before initializing the structure and passing a pointer to it as a function parameter.

Refer to the Voice Software Reference: Standard Runtime Library for a complete discussion of the DV_TPT structure.

3.1.5. Error Handling

All the Dialogic Voice Library functions return a value to indicate success or failure of the function. All Voice Library functions indicate success by a return value of zero or a non-negative number.

Extended Attribute functions that return pointers return a pointer to the ASCIIZ string "Unknown device" if they fail.

Extended Attribute functions that don't return pointers, return a value of AT_FAILURE if they fail.

All other functions return a value of -1 to indicate a failure.

If a function fails, call the Standard Attribute functions ATDV_LASTERR( ) and ATDV_ERRMSGP( ) for the reason for failure. These functions are described in the Voice Software Reference: Standard Runtime Library.

The errors that can be returned by a Voice Library function are listed in Table 22. Voice Function Errors.

NOTES:

1. dx_open( ) and dx_close( ) are exceptions to the above error handling rules. If these functions fail, the return code is -1. This is an error from the operating system; use dx_fileerrno( ) to obtain the system error value.

2. If ATDV_LASTERR( ) returns the error EDX_SYSTEM, an error from the operating system has occurred; use dx_fileerrno( ) to obtain the system error value.

3.1.6. Voice Library Include Files

The following lines must be included in application code prior to calling Voice Library functions:

#include <srllib.h>

#include <dxxxlib.h>

#include <windows.h>

NOTE:

srllib.h must be included in code before all other Dialogic header files.

The libraries are located in the following default directories:

<install drive:>\<install directory> \dialogic\ inc




3.1.7. Compiling Applications

Application programs developed using the Voice Library should be linked with the following libraries.

Libraries for multi-threaded applications are located in the following default directories:

<install drive:>\<install directory> \dialogic\i386\lib\libdxxmt.lib - the main Voice Library

<install drive:>\<install directory> \dialogic\i386\lib\libsrlmt.lib - the Standard Run-time Library

They should be linked in the order specified above.

3.1.8. C Language Interfaces

Simple C language interfaces in source-code format are provided to each individual technology DLL (standard run-time, voice, fax, voice recognition, and network interfaces). These C language interfaces allow an application to perform run-time linking instead of compile-time linking.

NOTE:

Compile-time linking requires that all functions called in an application be contained in the DLL that resides on the system. The following libraries are provided for compile-time linking and are installed in the LIB subdirectory under the Dialogic home directory (normally \Program Files\Dialogic):

LIBSRLMT.LIB
LIBDXXMT.LIB
LIBDTIMT.LIB
LIBFAXMT.LIB




3.1.9. Run-Time Linking

Run-time linking resolves the entry points to the Dialogic DLLs when the application is loaded and executed. This allows the application to contain function calls that are not contained in the DLL that resides on the target system.

The following files are provided for run-time linking and are installed in the CLIB subdirectory under the Dialogic home directory (normally \Program Files\Dialogic):

SRLLIB.C and SRLLIB.CPP
DXXXLIB.C and DXXXLIB.CPP
FAXLIB.C and FAXLIB.CPP
DTILIB.C and DTILIB.CPP
MSILIB.C and MSILIB.CPP
CCLIB.C and CCLIB.CPP

To use run-time linking, the application must first call the technology xx_libinit( ) functions, where xx specifies the technology (sr, dx, fx, dt or vr). All other Dialogic function calls are the same as when using compile-time linking. The technology xx_libinit( ) functions provided are as follows:

dx_libinit( ) - Initializes the Voice Library DLL
fx_libinit( ) - Initializes the Fax Library DLL
sr_libinit( ) - Initializes the Standard Run-time Library DLL
dt_libinit( ) - Initializes the Network Interface Library DLL
vr_libinit( ) - Initializes the Voice Recognition Library DLL

The xx_libinit( ) function calls the LoadLibrary( ) function to load a specific Dialogic technology DLL. If the DLL does not exist, all its functions are set up as default Not Implemented Functions. If the DLL does exist, the xx_libinit( ) function performs a series of GetProcAddress( ) function calls that sets up the address pointers for the functions.

Table 1. Library Interfaces

Technology	.C and .CPP Files	Header File
Voice	DXXXLIB	DXXXLIB.H
Fax	FAXLIB	FAXLIB.H
Standard Run-time	SRLLIB	SRLLIB.H
Network Interfaces	CCLIB DTILIB MSILIB	CCLIB.H DTILIB.H MSILIB.H
Voice Recognition	VRXXXLIB	VRXXXLIB.H

The Network Interfaces include the MSI and T-1 interfaces. These interfaces are referred to as the Network DLL.

Click here to contact Dialogic Customer Engineering