• 2.3.1. Device Management Functions
• 2.3.2. Configuration Functions
• 2.3.3. I/O Functions
• 2.3.4. Play and Record Functions
• 2.3.5. Convenience Functions
• 2.3.6. Call Status Transition Event Functions
• 2.3.7. SCbus Routing Functions
• 2.3.8. Global Tone Detection Functions
• 2.3.9. Global Tone Generation Functions
• 2.3.10. R2MF Convenience Functions
• 2.3.11. Speed and Volume Functions
• 2.3.12. Speed and Volume Convenience Functions
• 2.3.13. PerfectCall Call Analysis Functions
• 2.3.14. Caller ID Functions
• 2.3.15. Structure Clearance Functions
• 2.3.16. Extended Attribute Functions
• 2.3.17. File Manipulation Functions
• 2.3.18. Echo Cancellation Resource Functions
• 2.3.19. Resource Sharing Functions

2.3. Voice Functions

In the Function Reference chapter, each function is described in detail, and the function header includes the category to which the function belongs.

2.3.1. Device Management Functions

dx_close( )	close a board or channel
dx_open( )	open a board or channel

The Device Management functions open and close devices (boards and channels). For SCbus configurations using a D/240SC-T1 or D/300SC-E1 board, each board comprises a digital interface device with independent channels/time slots (dtiBxTx) and a voice device with independent channels (dxxxBxCx); where B is followed by the unique board number, C is followed by the number of the voice device channel (1 to 4) and T is followed by the number of the digital interface device time slot (digital channel)(1 to 24 for T-1; 1 to 30 for E-1).

Before you can use any of the other library functions on a device, that device must be opened. When the device is opened using dx_open( ) the function returns a unique Dialogic device handle. The handle is the only way the device can be identified once it has been opened. The dx_close( ) function closes a device via its handle.

Device Management functions do not cause a device to be busy. In addition, the Device Management functions will work on a device whether the device is busy or idle.

NOTES:

1. Issuing a dt_open( ), dx_open( ), dt_close( ) or dx_close( ) while the device is being used by another process will not affect the current operation of the device.
2. The device handle which is returned is Dialogic defined. The device handle is not a standard Windows file descriptor. Any attempts to use operating system commands such as read( ), write( ), or ioctl( ) will produce unexpected results.
3. By default, the maximum number of times you can simultaneously open the same channel in your application is set to 30 in the Windows Registry.
4. In an application that starts a process, the device handle is not inheritable by the child process. Devices must be opened in the child process.

2.3.2. Configuration Functions

dx_clrdigbuf( )	clear the firmware digit buffer
dx_getparm( )	get a board/channel device parameter
dx_setdigtyp( )	set digit collection type
dx_sethook( )	set hookswitch state
dx_setparm( )	set device parameters
dx_wtring( )	wait for number of rings

Configuration functions allow you to alter, examine, and control the physical configuration of an open device. The configuration functions operate on a device only if the device is idle. All configuration functions cause a device to be busy and return the device to an idle state when the configuration is complete. See Section 3.1.3. Busy and Idle States for information about busy and idle states.

NOTE:

The dx_sethook( ) function can also be classified as an I/O function and can be run asynchronously or synchronously.

2.3.3. I/O Functions

dx_dial( )	(enable/disable call analysis) dial an ASCIIZ string of digits
dx_getdig( )	get digits from channel digit buffer
dx_gtsernum( )	retrieve serial number and silicon serial number from Dialogic hardware
dx_mreciottdata( )	records voice data from two channels to a single file, device or memory, supporting transaction record
dx_play( )	play voice data from one or more sources
dx_playiottdata( )	play voice data from multiple sources
dx_rec( )	record voice data to one or more destinations
dx_reciottdata( )	record voice data to multiple destinations
dx_RxIottData( )	receive data on a specified channel
dx_setdigbuf( )	set digit buffering mode
dx_stopch( )	stop current I/O
dx_TxIottData( )	transmit data on a specified channel
dx_TxRxIottData( )	start a transmit-initiated reception of data
dx_wink( )	wink a channel
NOTES: 1. dx_playtone( ), which is grouped with the Global Tone Generation functions, is also an I/O function and all I/O characteristics apply. 2. dx_sethook( ), which is grouped with the Configuration functions, is also an I/O function and all I/O characteristics apply. 3. dx_wink( ), cannot be called for a digital T-1 configuration that includes a D/240SC-T1 board. Transparent signaling for SCbus digital interface devices is not supported.

The purpose of an I/O function is to transfer data to and from an open idle channel. All I/O functions cause a channel to be busy while data transfer is taking place and return the channel to an idle state when data transfer is complete. The dx_stopch( ) function stops any other I/O function, except dx_dial( ).

I/O functions can be run synchronously or asynchronously. When running synchronously, they return after completing successfully or after an error. When running asynchronously they will return immediately to indicate successful initiation (or an error), and continue processing until a termination condition is satisfied. The Voice Software Reference: Standard Runtime Library contains a full discussion of asynchronous and synchronous operation.

A set of termination conditions can be specified for I/O functions (except dx_stopch( ) and dx_wink( )). These conditions dictate what events will cause an I/O function to terminate. The termination conditions are specified just before the I/O function call is made. Obtain termination reasons for I/O functions by calling the Extended Attribute function ATDX_TERMMSK( ). See Section 3.1.4. I/O Terminations for information on I/O terminations.

NOTE:

The dx_stopch( ) function will not stop all I/O functions. Do not use this function to stop dx_wink( ) or dx_dial( )(without Call Analysis enabled).

2.3.4. Play and Record Functions

Play and record functions included in the Voice Library are listed below:

dx_play( )	plays recorded voice data
dx_playf( )	plays recorded voice data from a single file
dx_playiottdata( )	plays voice data from multiple sources
dx_playvox( )	plays a single vox file
dx_playwav( )	plays a single wave file
dx_mreciottdata( )	records voice data from two channels to a single file, device or memory. The dx_mreciottdata( ) function supports the Transaction Record feature.
dx_rec( )	records voice data to one or more destinations
dx_recf( )	records voice data to a single file
dx_reciottdata( )	records voice data to multiple destinations
dx_recvox( )	records voice data to a single vox file
dx_recwav( )	records voice data to a single wave file

2.3.5. Convenience Functions

dx_playf( )	play voice data from a single file
dx_playvox( )	play a VOX file
dx_playwav( )	play a WAVE file
dx_recf( )	record voice data to a single file
dx_recvox( )	record voice data to a single VOX file
dx_recwav( )	record voice data to a single WAVE file

These functions simplify synchronous play and record.

dx_playf( ) performs a playback from a single file by specifying the filename. The same operation can be done by using dx_play( ) and supplying 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. dx_playvox( ), dx_playwav( ), dx_recvox( ), dx_recwav( ), and dx_recf( ) provide the same single-file convenience for the dx_playiottdata( ), dx_reciottdata( ), and dx_rec( ) function.

NOTE:

dx_playf( ), dx_playvox( ), dx_playwav( ), dx_recf( ), dx_recvox( ) and dx_recwav( ) run synchronously only.

2.3.6. Call Status Transition Event Functions

dx_getevt( )	get call status transition event
dx_setevtmsk( )	set call status transition event notification

Call Status Transition (CST) Event functions set and monitor Call Status Transition events that can occur on a device. Call Status Transition events indicate changes in the status of the call. For example, if rings were detected, if the line went onhook or offhook, or if a tone was detected. The full list of Call Status Transition events is provided in the Call Status Transition structure (DX_CST) in the chapter on Data Structures.

dx_setevtmsk( ) enables detection of CST event(s).

dx_getevt( ) retrieves events in a synchronous environment. To retrieve CST events in an asynchronous environment, use the Standard Run-time Library's Event Management functions.

2.3.7. SCbus Routing Functions

See the SCbus Routing Software Reference for function descriptions and the nomenclature used to identify devices, channels and time slots in an SCbus configuration. The SCbus routing functions can only be used in SCbus configurations.

nr_scroute( )	makes a half or full duplex connection between two SCbus devices
nr_scunroute( )	breaks a half or full duplex connection between two SCbus devices

NOTE:

The Voice Library does not include these Convenience functions. Code for these functions is provided in a separate C source file, sctools.c, which is located in the sctools subdirectory under the Dialogic home directory.

2.3.8. Global Tone Detection Functions

dx_addtone( )	add a user-defined tone
dx_blddt( )	build a dual frequency tone description
dx_blddtcad( )	build a dual freqency tone cadence description
dx_bldst( )	build a single frequency tone description
dx_bldstcad( )	build a single frequency tone cadence description
dx_deltones( )	delete user-defined tones
dx_enbtone( )	enable detection of user-defined tones
dx_distone( )	disable detection of user-defined tones
dx_setgtdamp( )	sets amplitudes used by Global Tone Detection (GTD)

Use the Global Tone Detection (GTD) functions to define and enable detection of single and dual frequency tones that fall outside those automatically provided with the Voice Driver. This includes tones outside the standard DTMF range of 0-9, a-d, * and #.

The GTD dx_blddt( ), dx_blddtcad( ), dx_bldst( ), and dx_bldstcad( ) functions define tones which can then be added to the channel using dx_addtone( ). This enables detection of the tone on that channel.

See the Voice Software Reference: Voice Features Guide for a full description of Global Tone Detection.

2.3.9. Global Tone Generation Functions

dx_bldtngen( )	build a user-defined tone generation template
dx_playtone( )	play a user-defined tone
dx_playtoneEx( )	plays the cadenced tone defined by TN_GENCAD

Use Global Tone Generation functions to define and play single and dual tones other than those automatically provided with the Voice driver.

dx_bldtngen( ) defines a tone template structure, TN_GEN. dx_playtone( ) can then be used to generate the tone.

2.3.10. R2MF Convenience Functions

r2_creatfsig( )	create R2MF forward signal tone
r2_playbsig( )	play R2MF backward signal tone

These are convenience functions which enable detection of R2MF forward signals on a channel, and play R2MF backward signals in response. For more information about Voice Support for R2MF, see the Voice Software Reference: Voice Features Guide.

2.3.11. Speed and Volume Functions

dx_adjsv( )	adjust speed or volume
dx_clrsvcond( )	clear speed or volume digit adjustment conditions
dx_setsvcond( )	set speed or volume digit adjustment conditions
dx_getcursv( )	get current speed and volume settings
dx_getsvmt( )	get Speed/Volume Modification Table
dx_setsvmt( )	set Speed/Volume Modification Table

Use these functions to adjust the speed and volume of the play. A 21-entry Speed Modification Table and Volume Modification Table is associated with each channel. This table can be used for increasing or decreasing the speed or volume. This table has default values which can be changed using the dx_setsvmt( ) function.

dx_adjsv( ) and dx_setsvcond( ) both use the Modification Table to adjust speed or volume; dx_adjsv( ) adjusts speed or volume immediately, and dx_setsvcond( ) sets conditions (such as a digit) for speed or volume adjustment. dx_clrsvcond( ) to clear the speed or volume conditions.

dx_getcursv( ) retrieves the current speed or volume settings. dx_getsvmt( ) retrieves the settings of the current Speed or Volume Adjustment Table.

See the Voice Software Reference: Voice Features Guide for more information about voice software support for speed and volume.

2.3.12. Speed and Volume Convenience Functions

dx_addspddig( )	add speed adjustment digit
dx_addvoldig( )	add volume adjustment digit

dx_addspdig( ) and dx_addvoldig( ) are convenience functions that specify a digit and an adjustment to occur on that digit, without having to set any data structures. These functions use the default settings of the Speed/Volume Modification Tables.

2.3.13. PerfectCall Call Analysis Functions

dx_chgdur( )	change PerfectCall Call Analysis signal duration
dx_chgfreq( )	change PerfectCall Call Analysis signal frequency
dx_chgrepcnt( )	change PerfectCall Call Analysis signal repetition count
dx_initcallp( )	initialize PerfectCall Call Analysis on a channel
dx_chg( )	functions can be used to change the definition of default PerfectCall Call Analysis tones.

2.3.14. Caller ID Functions

dx_gtcallid( )	Returns the calling line Directory Number
dx_gtextcallid( )	Returns the requested Caller ID message
dx_wtcallid( )	Waits for rings and reports Caller ID

2.3.15. Structure Clearance Functions

dx_clrcap( )	clear DX_CAP structure
dx_clrtpt( )	clear DV_TPT structure

These functions do not affect a device. The dx_clrcap( ) and dx_clrtpt( ) functions provide a convenient method for clearing the DX_CAP and DV_TPT Voice Library data structures.

2.3.16. Extended Attribute Functions

Call Analysis
ATDX_BDNAMEP( )	Returns pointer to the device name string
ATDX_BDTYPE( )	Returns board type
ATDX_BUFDIGS( )	Returns number of digits in firmware since last dx_getdig( ) for a given channel
ATDX_CHNAMES( )	Returns pointer to array of channel name strings
ATDX_CHNUM( )	Returns channel number on board associated with the channel device handle
ATDX_CONNTYPE( )	Returns connection type for a call
ATDX_DEVTYPE( )	Returns device type
ATDX_FRQDUR( )	Returns duration of first frequency
ATDX_FRQDUR2( )	Returns duration of 2nd SIT tone frequency
ATDX_FRQDUR3( )	Returns duration of 3rd SIT tone frequency
ATDX_FRQHZ( )	Returns frequency of first detected tone
ATDX_FRQHZ2( )	Returns frequency of second detected SIT tone
ATDX_FRQHZ3( )	Returns frequency of third detected SIT tone
ATDX_FRQOUT( )	Returns % of frequency out of bounds detected during Call Analysis
ATDX_FWVER( )	Returns firmware version
ATDX_LINEST( )	Returns current line status
ATDX_LONGLOW( )	Returns duration of longer silence detected during Call Analysis
ATDX_PHYADDR( )	Returns physical address of board
ATDX_SHORTLOW( )	Returns duration of shorter silence detected during Call Analysis
ATDX_SIZEHI( )	Returns duration of non-silence detected during Call Analysis
ATDX_STATE( )	Returns current state of the device
ATDX_TERMMSK( )	Returns termination bitmap
ATDX_TRCOUNT( )	Returns last record or play transfer count
PerfectCall Call Analysis uses:
ATDX_ANSRSIZ( )	Returns duration of answer detected during
ATDX_CPERROR( )	Returns call analysis error
ATDX_CPTERM( )	Returns last call analysis termination
ATDX_CRTNID( )	Returns the identifier of the tone that causedthe most recent Call Analysis termination
ATDX_DTNFAIL( )	Returns the dial tone character that indicates which dial tone Call Analysis failed to detect
The Call Status Transition event detection uses:
ATDX_HOOKST( )	Returns current hook status
Global Tone Detection uses:
ATDX_TONEID( )	Returns the tone ID

Voice Library Extended Attribute functions return information specific to the Voice device indicated in the function call.

2.3.17. File Manipulation Functions

These file manipulation functions map to C run-time functions, and can only be used if the file is opened with the dx_fileopen( ) function. The arguments for these Dialogic functions are identical to the equivalent Microsoft Visual C++ run-time functions.

dx_fileclose( )	closes the file associated with the handle
dx_fileerrno( )	obtains the system error value
dx_fileopen( )	opens the file specified by filep
dx_fileread( )	reads data from file associated with handle
dx_fileseek( )	moves file pointer associated with handle
dx_filewrite( )	writes data from buffer into file associated with handle

2.3.18. Echo Cancellation Resource Functions

Use the following functions to configure a voice channel as an echo cancellation device. For more information on echo cancellation resource (ECR), see the Voice Software Reference: Voice Features Guide.

dx_getxmitslotecr( )	provides the SCbus transmit time-slot number of the specified voice channel device when in ECR mode
dx_listenecr( )	enables echo cancellation on a specified voice channel and connects the voice channel to the echo-referenced signal on the specified SCbus time slot (ECR mode)
dx_listenecrex( )	performs identically to dx_listenecr( ) and also provides the ability to modify the characteristics of the echo canceller
dx_unlistenecr( )	disables echo cancellation on a specified voice channel and disconnects the voice channel from the echo-referenced signal (SVP mode)

2.3.19. Resource Sharing Functions

The resource sharing functions apply to DSP resource features that can be shared, such as DSP Fax resources.

dx_GetRscStatus( )

returns assignment status of the shared resource for the specified channel

Click here to contact Dialogic Customer Engineering