• 3.2.1. Always Check Return Code in Voice Programming
• 3.2.2. Clearing Voice Structures
• 3.2.3. Using the Voice dx_playf( ) and dx_recf( ) Convenience Functions
• 3.2.4. Using the Voice Asynchronous Programming Model
• 3.2.5. Using Multiple Processes in Voice Synchronous Applications

3.2. Voice Programming Conventions

This chapter provides several techniques that you can use to simplify programming with the Dialogic Voice Library.

3.2.1. Always Check Return Code in Voice Programming

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.

NOTE:

Asynchronous I/O functions return immediately to indicate success or failure of the function initiating.

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

Extended Attribute functions that do not return pointers return a value of AT_FAILURE if they fail.

Non-attribute functions return a value of -1 to indicate a failure.

If a function has failed, the reason for failure can be found by calling the Standard Attribute functions ATDV_LASTERR( ) and ATDV_ERRMSGP( ). These functions are described in the Voice Software Reference: Standard Runtime Library.

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

When using the asynchronous programming model you should always install a handler to get TDX_ERROR events.

3.2.2. Clearing Voice Structures

Two library functions are provided to clear structures. dx_clrcap( ) clears DX_CAP structures and dx_clrtpt( ) clears DV_TPT structures. See the function descriptions for details.

It is good practice to clear the field values of any structure before using the structure in a function call. Doing so will help prevent unintentional settings or terminations.

3.2.3. Using the Voice dx_playf( ) and dx_recf( ) Convenience Functions

dx_playf( ) and dx_recf( ) are synchronous Voice Library functions provided as a convenience to the programmer. These functions are specific cases of the dx_play( ) and dx_rec( ) functions.

For example, dx_playf( ) performs a playback from a single file by specifying the filename. The same operation can be done using dx_play( ) and specifying a DX_IOTT structure with only one entry for that file. Using dx_playf( ) is more convenient for a single file playback, because you do not have to set up a DX_IOTT structure for the one file and the application does not need to open the file. The dx_recf( ) provides the same single file convenience for the dx_rec( ) function.

3.2.4. Using the Voice Asynchronous Programming Model

Asynchronous programming allows you to have multiple threads of control within the one process. Each of the I/O functions can operate synchronously or asynchronously. See the Voice Software Reference: Standard Runtime Library for information about asynchronous programming models.

3.2.5. Using Multiple Processes in Voice Synchronous Applications

When writing multiple processes for synchronous applications, you should use the following model: Create a master control process and spawn of a child process for each channel. Each child process is responsible for:

• opening and closing the channel
• adjusting the channel parameters
• performing channel-specific operations
• monitoring events that occur on the channel

NOTE:

In an application that spawns a child process from a parent process, a device handle is not inheritable by the child process. Devices must be opened in the child process.

Click here to contact Dialogic Customer Engineering