dx_enbtone( )

Description | Example | Cautions | Errors | See Also

Name:	int dx_enbtone(chdev,toneid,evt_mask)
Inputs:	int chdev	valid Dialogic channel device handle
	int toneid	tone template identification
	int evt_mask	event mask
Returns:	0:	Success
	-1	Error return code
Category:	Global Tone Detection

Description

The dx_enbtone( ) function enables detection of of a user-defined tone on a channel, including the TONE ON and/or TONE OFF for that tone. Detection capability for tones is enabled on a channel by default when dx_addtone( ) is called.

The description of dx_addtone( ) explains how to synchronously and asynchronously retrieve CST tone on and tone off events.

Use this function to enable a tone that has been disabled using dx_distone( ).

Parameter	Description
chdev:	specifies the valid channel device handle obtained when the channel was opened using dx_open( ).
toneid:	specifies the user-defined tone identifier for which detection is being enabled.
	To enable detection of all user-defined tones on the channel, set toneid to TONEALL.
evt_mask:	specifies whether to enable detection of the user-defined tone going on or going off. Set to one or both of the following using a bitwise -OR (|) operator. DM_TONEON disable TONE ON detection DM_TONEOFF disable TONE OFF detection
	evt_mask affects the enabled/disabled status of the tone template and will remain in effect until dx_enbtone( ) or dx_distone( ) is called again to reset it.

Example

#include <stdio.h>  
#include <srllib.h>  
#include <dxxxlib.h>  
#include <windows.h>  
   
#define TID_1   101  
   
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 );  
   }  
   
/*  
    * Enable Detection of ToneId TID_1  
    */  
   if ( dx_enbtone( dxxxdev, TID_1, DM_TONEON | DM_TONEOFF ) == -1 ) {  
      printf( "Unable to Enable Detection of Tone %d\n", TID_1 );  
      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 );  
}

Cautions

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.

Errors

If the function returns -1 to indicate failure, call ATDX_LASTERR( ) and ATDV_ERRMSGP( ) to return one of the following errors:

EDX_BADPARM	Invalid Parameter
EDX_BADPROD	Function not supported on this board
EDX_SYSTEM	Error from operating system; use dx_fileerrno( ) to obtain error value
EDX_TONEID	Bad tone ID
EDX_TNMSGSTATUS	Invalid message status setting

See Also

Global Tone Detection:

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

Event Retrieval:

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

Click here to contact Dialogic Customer Engineering