dx_addvoldig( )

Description | Cautions | Example | Errors | See Also

Name:	int dx_addvoldig(chdev,digit,adjval)
Inputs:	int chdev	valid Dialogic channel device handle
	char digit	DTMF digit
	short adjval	volume adjustment value
Returns:	0 if success
	-1 if failure
Includes:	srllib.h dxxxlib.h
Category:	Speed and Volume Convenience

Description

The dx_addvoldig( ) function is a convenience function that sets a DTMF digit to adjust volume by a specified amount, immediately and for all subsequent plays on the specified channel (until changed or cancelled).

NOTES:

1. Calls to this function are cumulative. To reset a digit condition, you need to clear all adjustment conditions using a dx_clrsvcond( ), and then reset the new condition.

2. Volume control is supported on D/21D, D/21E, D/41D, D/41E, D/41ESC, D/81A, D/121, D/121A, D/121B, D/160SC-LS, D/240SC, D/240SC-T1, D/300SC-E1, and D/320SC boards.

This function assumes that the Volume Modification Table has not been modified using the dx_setsvmt( ) function.

For information about the speed and volume functions and the Speed and Volume Modification Tables, see the Voice Software Reference: Voice Features Guide.

Parameter	Description
chdev	specifies the valid channel device handle obtained by a call to dx_open( ).
digit	specifies a DTMF digit (0-9, *,#) that will modify volume by the amount specified in adjval.
	To start play-volume at the origin, set digit to NULL and set adjval to SV_NORMAL.
adjval	specifies one of the following the speed adjustment values to take effect whenever the digit specified in digit occurs:
	SV_ADD2DB	Increase play-volume by 2DB
	SV_ADD4DB	Increase play-volume by 4DB
	SV_ADD6DB	Increase play-volume by 6DB
	SV_ADD8DB	Increase play-volume by 8DB
	SV_SUB2DB	Decrease play-volume by 2DB
	SV_SUB4DB	Decrease play-volume by 4DB
	SV_SUB6DB	Decrease play-volume by 6DB
	SV_SUB8DB	Decrease play-volume by 8DB
	SV_NORMAL	Set play-volume to origin when the play begins (digit must be set to NULL)

Cautions

1. This function is cumulative. To reset or remove any condition, you should clear all adjustment conditions, and reset them if required. (e.g., If DTMF digit 1 has already been set to increase play-volume by one step, a second call that attempts to redefine digit 1 to the origin (regular volume), will have no effect on the volume, but will add it to the condition array. The digit will retain its original setting).
2. The digit that causes the play adjustment will not be passed to the digit buffer, so it cannot be retrieved using dx_getdig( ) and will not be included in the result of ATDX_BUFDIGS( ) which retrieves the number of digits in the buffer.
3. Digits that are used for play adjustment will not be used as a terminating condition. If a digit is defined as both, then the play adjustment will take priority.
4. Volume control is supported on the D/21D, D/21E, D/41D, D/41E, D/41ESC, D/81A, D/121, D/121A, D/121B, D/160SC-LS, D/240SC, D/240SC-T1, D/300SC-E1, and D/320SC boards only.

Example

#include <stdio.h>  
#include <srllib.h>  
#include <dxxxlib.h>  
#include <windows.h>  
   
/*  
 * Global Variables  
 */  
main()  
{  
   int  dxxxdev;  
   
   /*  
    * Open the Voice Channel Device and Enable a Handler  
    */  
   if ( ( dxxxdev = dx_open( "dxxxB1C1", NULL) ) == -1 ) {  
      perror( "dxxxB1C1" );  
      exit( 1 );  
   }  
   
   /*  
    * Add a Speed Adjustment Condition - decrease the  
    * playback volume by 2dB whenever DTMF key 2 is pressed.     */  
   if ( dx_addvoldig( dxxxdev, '2', SV_SUB2DB ) == -1 ) {  
      printf( "Unable to Add a Volume Adjustment" );  
      printf( " Condition\n");  
      printf( "Lasterror = %d  Err Msg = %s\n",  
         ATDV_LASTERR( dxxxdev ), ATDV_ERRMSGP( dxxxdev ) );  
      dx_close( dxxxdev );  
      exit( 1 );  
   }  
   
   /*  
    * Continue Processing  
    *   .  
    *   .  
    *   .  
    */  
   
   /*  
    * Close the opened Voice Channel Device  
    */  
   if ( dx_close( dxxxdev ) != 0 ) {  
      perror( "close" );  
   }  
   
   /* Terminate the Program */  
   exit( 0 );  
}

Errors

If this function returns -1 to indicate failure, use ATDV_LASTERR( ) and ATDV_ERRMSGP( ) to retrieve one of the following error reasons:

EDX_BADPARM	Invalid Parameter
EDX_BADPROD	Function not supported on this board
EDX_SVADJBLKS	Invalid Number of Play Adjustment Blocks
EDX_SYSTEM	Error from operating system; use dx_fileerrno( ) to obtain error value

See Also

Related Speed and Volume functions:

• dx_addspddig( )
• dx_adjsv( )
• dx_clrsvcond( )
• dx_getcursv( )
• dx_getsvmt( )
• dx_setsvcond( )
• dx_setsvmt( )

Click here to contact Dialogic Customer Engineering