dx_addtone( )

Description | Detection Notification | Cautions | Example | Errors | See Also

Name:	int dx_addtone(chdev,digit,digtype)
Inputs:	int chdev	valid Dialogic channel device handle
	unsigned char digit	optional digit associated with the bound tone
	unsigned char digtype	digit type
Returns:	0 if success
	-1 if failure
Includes:	srllib.h dxxxlib.h
Category:	Global Tone Detection

Description

The dx_addtone( ) function adds a user-defined tone that was defined by the most recent dx_blddt( ) (or other Global Tone Detection build-tone) function call, to the specified channel. Adding a user-defined tone to a channel downloads it to the board and enables detection of tone-on and tone-off events for that tone by default.

Use dx_distone( ) to disable detection of the tone, without removing the tone from the channel. Detection can be enabled again using dx_enbtone( ). For example, if you only want to be notified of tone-on events, you should call dx_distone( ) to disable detection of tone-off events.

Detection Notification

Tone-on and tone-off events are call status transition events. Retrieval of these events is handled differently for asynchronous and synchronous applications. Table 6 outlines the different processes:

Table 6. Asynchronous/Synchronous CST Event Handling

Synchronous	Asynchronous
Call dx_addtone( ), or dx_enbtone( )	Call dx_addtone( ) or dx_enbtone( ) to enable tone-on/off detection.
Call dx_getevt( ) to wait for CST event(s). Events are returned in the DX_EBLK structure	Use SRL to asynchronously wait for TDX_CST event(s)
N/A	Use sr_getevtdatap( ) to retrieve DX_CST structure
NOTE: These procedures are the sa me as the retrieval of any other CST event, except that dx_addtone( ) or dx_enbtone( ) are used to enable event detection instead of dx_setevtmsk( ).

You can optionally specify an associated ASCII digit (and digit type) with the tone. When the digit is detected, it is placed in the digit buffer and can be used for termination.

Setting User-Defined Tones as Termination Conditions

Detection of a user-defined tone can be specified as a termination condition for I/O functions. Set the tp_termno field in the DV_TPT to DX_TONE, and specify DX_TONEON or DX_TONEOFF in the tp_data field.

The function parameters are described below.

Parameter	Description
chdev	specifies the valid channel device handle obtained when the channel was opened using dx_open( ).
digit	(optional) specifies the digit to associate with the tone. When the tone is detected, the digit will be placed in the DV_DIGIT digit buffer. These digits can be retrieved using dx_getdig( ) (i.e., they can be used in the same way as DTMF digits, for example).
	If you do not specify a digit, the tone will be indicated by a DE_TONEON event or DE_TONEOFF event.
digtype	specifies the type of digit the channel will detect. Specify one of the following values.
	DG_USER1
	DG_USER2
	DG_USER3
	DG_USER4
	DG_USER5
	Up to twenty digits can be associated with each of these digit types.
NOTE: These types can be specified in addition to the digit types already defined for the Voice Library (e.g., DTMF, MF) which are specified using dx_setdigtyp( ).

Cautions

1. Ensure that dx_blddt( ) (or another appropriate build tone function) has been called to define a tone prior to adding it to the channel using dx_addtone( ), otherwise an error will occur.
2. The dx_addtone( ) function may not be used to change a tone that has previously been added.
3. The number of tones that can be added to a channel is dependent on the type of board. See the Voice Software Reference: Voice Features Guide for details.
4. When using this function in a multi-threaded application, use critical sections or a semaphore around the function call to ensure a thread-safe application. Failure to do so will result in "Bad Tone Template ID" errors.

Example

#include <stdio.h>  
#include <srllib.h>  
#include <dxxxlib.h>  
#include <windows.h>  
   
#define TID_1   101  
#define TID_2   102  
#define TID_3   103  
#define TID_4   104  
   
main()  
{  
   int  dxxxdev;  
   
   /*  
    * Open the Voice Channel Device and Enable a Handler  
    */  
   if ( ( dxxxdev = dx_open( "dxxxB1C1", NULL) ) == -1 ) {  
      perror( "dxxxB1C1" );  
      exit( 1 );  
   }  
   
   /*  
    * Describe a Simple Dual Tone Frequency Tone of 950-  
    * 1050 Hz and 475-525 Hz using leading edge detection.  
    */  
   if ( dx_blddt( TID_1, 1000, 50, 500, 25, TN_LEADING ) == -1 ) {  
      printf( "Unable to build a Dual Tone Template\n" );  
   }  
   
   /*  
    * Bind the Tone to the Channel  
    */  
   if ( dx_addtone( dxxxdev, NULL, 0 ) == -1 ) {  
      printf( "Unable to Bind the Tone %d\n", TID_1 );  
      printf( "Lasterror = %d  Err Msg = %s\n",  
          ATDV_LASTERR( dxxxdev ), ATDV_ERRMSGP( dxxxdev ));  
      dx_close( dxxxdev );  
      exit( 1 );  
   }  
   
   /*  
    * Describe a Dual Tone Frequency Tone of 950-1050 Hz  
    * and 475-525 Hz. On between 190-210 msecs and off  
    * 990-1010 msecs and a cadence of 3.  
    */  
   if ( dx_blddtcad( TID_2, 1000, 50, 500, 25, 20, 1, 100, 1, 3 ) == -1 ) {  
      printf("Unable to build a Dual Tone Cadence Template\n" );  
   }  
   
   /*  
    * Bind the Tone to the Channel  
    */  
   if ( dx_addtone( dxxxdev, 'A', DG_USER1 ) == -1 ) {  
      printf( "Unable to Bind the Tone %d\n", TID_2 );  
      printf( "Lasterror = %d  Err Msg = %s\n",  
          ATDV_LASTERR( dxxxdev ), ATDV_ERRMSGP( dxxxdev ));  
      dx_close( dxxxdev );  
      exit( 1 );  
   }  
   
   /*  
    * Describe a Simple Single Tone Frequency Tone of  
    * 950-1050 Hz using trailing edge detection.  
    */  
   if ( dx_bldst( TID_3, 1000, 50, TN_TRAILING ) == -1 ) {  
      printf( "Unable to build a Single Tone Template\n" );  
   }  
   
   /*  
    * Bind the Tone to the Channel  
    */  
   if ( dx_addtone( dxxxdev, 'D', DG_USER2 ) == -1 ) {  
      printf( "Unable to Bind the Tone %d\n", TID_3 );  
      printf( "Lasterror = %d  Err Msg = %s\n",  
          ATDV_LASTERR( dxxxdev ), ATDV_ERRMSGP( dxxxdev ) );  
      dx_close( dxxxdev );  
      exit( 1 );  
   }  
   
   /*  
    * Describe a Single Tone Frequency Tone of 950-1050 Hz.  
    * On between 190-210 msecs and off 990-1010 msecs and  
    * a cadence of 3.  
    */  
   if ( dx_bldstcad( TID_4, 1000, 50, 20, 1, 100, 1, 3 ) == -1 ) {  
      printf("Unable to build a Single Tone Cadence Template\n");  
   }  
   
   /*  
    * Bind the Tone to the Channel  
    */  
   if ( dx_addtone( dxxxdev, NULL, 0 ) == -1 ) {  
      printf( "Unable to Bind the Tone %d\n", TID_4 );  
      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_ASCII	Invalid ASCII value in tone template description
EDX_BADPARM	Invalid parameter
EDX_BADPROD	Function not supported on this board
EDX_CADENCE	Invalid cadence component value
EDX_DIGTYPE	Invalid Dig_Type value in tone template description
EDX_FREQDET	Invalid tone frequency
EDX_INVSUBCMD	Invalid sub-command
EDX_MAXTMPLT	Maximum number of user-defined tones for the board
EDX_SYSTEM	Error from operating system; use dx_fileerrno( ) to obtain error value
EDX_TONEID	Invalid tone template ID

See Also

Global Tone Detection functions:

• dx_blddt( ), dx_bldst( ), dx_blddtcad( ), dx_bldstcad( )
• dx_distone( )
• dx_enbtone( )
• Global Tone Detection (Voice Software Reference: Voice Features Guide)

Event Retrieval:

• dx_getevt( )
• DX_CST data structure
• sr_getevtdatap( )

Digit Retrieval:

• dx_getdig( )
• dx_setdigtyp( )
• DV_DIGIT

Click here to contact Dialogic Customer Engineering