dx_playtone( )

Description | Cautions | Example | Errors | See Also

Name:	int dx_playtone(chdev,tngenp,tptp,mode)
Inputs:	int chdev	valid Dialogic channel device handle
	TN_GEN *tngenp	pointer to the TN_GEN structure
	DV_TPT *tptp	pointer to the DV_TPT structure
	int mode	asynchronous/synchronous
Returns:	0 if success
	-1 if failurewhat error
Includes:	srllib.h
	dxxxlib.h
Category:	Global Tone Generation
Mode:	asynchronous/synchronous

Description

The dx_playtone( ) function plays tone defined by TN_GEN template, which defines the frequency amplitude and duration of a single or dual frequency tone to be played.

NOTE:

The dx_playtone( ) function is necessary for supporting the R2MF protocol in an application. See r2_playbsig( ) for information.

Asynchronous Operation

To run this function asynchronously set the mode field to EV_ASYNC. When running asynchronously, this function will return 0 to indicate it has initiated successfully, and will generate a TDX_PLAYTONE termination event to indicate completion.

Set termination conditions using the DV_TPT structure. This structure is pointed to by the tptp parameter described below.

Termination of this function is indicated by a TDX_PLAYTONE event.

After dx_playtone( ) terminates, use the ATDX_TERMMSK( ) function to determine the reason for termination.

Synchronous Operation

By default, this function runs synchronously, and will return a 0 to indicate that it has completed successfully.

Set termination conditions using the DV_TPT structure. This structure is pointed to by the tptp parameter described below.

Termination of synchronous play is indicated by a return value of 0.

After dx_playtone( ) terminates, use the ATDX_TERMMSK( ) function to determine the reason for termination.

Parameter	Description
chdev	specifies the valid channel device handle obtained when the channel was opened using dx_open( ).
tngenp	points to the TN_GEN template structure, which defines the frequency, amplitude and duration of a single or dual frequency tone. See the chapter on Data Structures for a full description of this template. dx_bldtngen( ) can be used to set up the structure.
tptp	points to the DV_TPT data structure, which specifies one of the following terminating conditions for this function:
	DX_DIGTYPE		Digit termination for user-defined tone
	DX_MAXDTMF		Maximum number of digits received
	DX_MAXSIL		Maximum silence
	DX_MAXNOSIL		Maximum non-silence
	DX_LCOFF		Loop current off
	DX_IDDTIME		Inter-digit delay
	DX_MAXTIME		Function time
	DX_DIGMASK		Digit mask termination
	DX_PMOFF		Pattern match silence off
	DX_PMON		Pattern match silence on
	DX_TONE		Tone-off or Tone-on detection
mode	specifies whether to run this function asynchronously or synchronously. Set to one of the following:
	EV_ASYNC:	Run dx_playtone( ) asynchronously.
	EV_SYNC:	Run dx_playtone( ) synchronously (default).

Cautions

1. The channel must be idle when calling this function.
2. If the tone generation template contains an invalid tg_dflag, or the specified amplitude or frequency is outside the valid range, dx_playtone( ) will generate a TDX_ERROR event if asynchronous, or
   -1 if synchronous.

Example

#include <stdio.h>  
#include <srllib.h>  
#include <dxxxlib.h>  
#include <windows.h>  
   
#define TID_1   101  
   
main()  
{  
   TN_GEN     tngen;  
   DV_TPT     tpt[ 5 ];  
   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 );  
   }  
   
   /*  
    * Build a Tone Generation Template.  
    * This template has Frequency1 = 1140,  
    * Frequency2 = 1020, amplitute at -10dB for  
    * both frequencies and duration of 100 * 10 msecs.  
    */  
   dx_bldtngen( &tngen, 1140, 1020, -10, -10, 100 );  
   
   /*  
    * Set up the Terminating Conditions  
    */  
   tpt[0].tp_type = IO_CONT;  
   tpt[0].tp_termno = DX_TONE;  
   tpt[0].tp_length = TID_1;  
   tpt[0].tp_flags = TF_TONE;  
   tpt[0].tp_data = DX_TONEON;  
   
   tpt[1].tp_type = IO_CONT;  
   tpt[1].tp_termno = DX_TONE;  
   tpt[1].tp_length = TID_1;  
   tpt[1].tp_flags = TF_TONE;  
   tpt[1].tp_data = DX_TONEOFF;  
   
   tpt[2].tp_type = IO_EOT;  
   tpt[2].tp_termno = DX_MAXTIME;  
   tpt[2].tp_length = 6000;  
   tpt[2].tp_flags = TF_MAXTIME;  
   
   if (dx_playtone( dxxxdev, &tngen, tpt, EV_SYNC ) == -1 ){  
      printf( "Unable to Play the Tone\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_BADTPT	Invalid DV_TPT entry
EDX_BUSY	Busy executing I/O function
EDX_AMPLGEN	Invalid amplitude value in TN_GEN structure
EDX_FREQGEN	Invalid frequency component in TN_GEN structure
EDX_FLAGGEN	Invalid tn_dflag field in TN_GEN structure
EDX_SYSTEM	Error from operating system; use dx_fileerrno( ) to obtain error value

See Also

Related to Tone Generation:

• dx_bldtngen( )
• TN_GEN structure
• Global Tone Generation (Voice Software Reference: Voice Features Guide)

R2MF functions:

• r2_creatfsig( )
• r2_playbsig( )

Handling and Retrieving dx_playtone( ) Termination Events:

• Event Management functions in the Voice Software Reference: Standard Runtime Library
• DV_TPT
• ATDX_TERMMSK( )

Click here to contact Dialogic Customer Engineering