dx_playtoneEx( )

Description | Cautions | Example | Errors | See Also

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

Description

The dx_playtoneEx( ) function plays the cadenced tone defined by TN_GENCAD, which describes a signal by specifying the repeating elements of the signal (the cycle) and the number of desired repetitions. The cycle can contain up to 4 segments, each with its own tone definition and on/off duration, which creates the signal pattern or cadence. Each segment consists of a TN_GEN single- or dual-tone definition (frequency, amplitude and duration) followed by a corresponding off-time (silence duration) that is optional. The dx_bldtngen( ) function can be used to set up the TN_GEN components of the TN_GENCAD structure. The segments are seamlessly concatenated in ascending order to generate the signal cycle.

This function returns the same errors, return codes, and termination events as the dx_playtone( ) function. Also, the TN_GEN array in the TN_GENCAD data structure has the same requirements as the TN_GEN used by the dx_playtone( ) function.

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

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

Synchronous Operation: By default, or by setting the mode field to EV_SYNC, this function will run synchronously, and will return a 0 to indicate successful termination of synchronous play.

For signals that specify an infinite repetition of the signal cycle (cycles = 255) or an infinite duration of a tone (tg_dur = -1), you must specify the appropriate termination conditions in the DV_TPT structure used by dx_playtoneEx( ).

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

Parameter	Description
chdev	specifies the valid channel device handle obtained when the channel was opened using dx_open( ).
tngencadp	points to a TN_GENCAD structure (which defines a signal by specifying a cycle and its number of repetitions), or specifies one of the following predefined, standard, PBX call progress signals:
	CP_DIAL		Dial Tone
	CP_REORDER		Reorder Tone (Paths-Busy, All-Trunks-Busy, Fast Busy)
	CP_BUSY		Busy Tone (Slow Busy)
	CP_RINGBACK1		Audible Ring Tone 1 (Ringback Tone)
	CP_RINGBACK2		Audible Ring Tone 2 (Slow Ringback Tone)
	CP_RINGBACK1_ CALLWAIT		Special Audible Ring Tone 1
	CP_RINGBACK2_ CALLWAIT		Special Audible Ring Tone 2
	CP_RECALL_DIAL		Recall Dial Tone
	CP_INTERCEPT		Intercept Tone
	CP_CALLWAIT1		Call Waiting Tone 1
	CP_CALLWAIT2		Call Waiting Tone 2
	CP_BUSY_VERIFY_A		Busy Verification Tone (Part A)
	CP_BUSY_VERIFY_B		Busy Verification Tone (Part B)
	CP_EXEC_OVERRIDE		Executive Override Tone
	CP_FEATURE_ CONFIRM		Confirmation Tone
	CP_STUTTER_DIAL		Stutter Dial Tone (same as Message Waiting Dial Tone)
	CP_MSG_WAIT_DIAL		Message Waiting Dial Tone (same as Stutter Dial Tone)
tptp	points to the DV_TPT data structure, which specifies one or more 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 the function asynchronously.
	EV_SYNC	Run the function synchronously (default).

Cautions

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

Example

/*$ dx_playtoneEx( ) example $*/



#include <stdio.h>

#include <windows.h>

#include <srllib.h>

#include <dxxxlib.h>



main()

{

   TN_GEN       tngen;

   TN_GENCAD    tngencad;

   DV_TPT       tpt[ 2 ];

   int          dxxxdev;

   long         term;



   /*

    * Open the Voice Channel Device and Enable a Handler

    */

   if ( ( dxxxdev = dx_open( "dxxxB1C1", 0 ) ) == -1 ) {

      perror( "dxxxB1C1" );

      exit( 1 );

   }



   /*

    * Set up the Terminating Conditions. 

    * (Play until a digit is pressed or until time-out at 45 seconds.)

    */



   tpt[0].tp_type = IO_CONT;

   tpt[0].tp_termno = DX_MAXDTMF;

   tpt[0].tp_length = 1;

   tpt[0].tp_flags = TF_MAXDTMF;



   tpt[1].tp_type = IO_EOT;

   tpt[1].tp_termno = DX_MAXTIME;

   tpt[1].tp_length = 450;

   tpt[1].tp_flags = TF_MAXTIME;



   /*

    * Build a custom cadence dial tone to indicate that a priority message is waiting.

    * Signal cycle has 4 segments & repeats forever (cycles=255) until tpt termination:

    * 1) 350 + 440 Hz at -17dB ON for 125 * 10 ms and OFF for 10 *10 ms.

    * 2) 350 + 440 Hz at -17dB ON for 10 * 10 ms and OFF for 10 *10 ms.

    * 3) 350 + 440 Hz at -17dB ON for 10 * 10 ms and OFF for 10 *10 ms.

    * 4) 350 + 440 Hz at -17dB ON for 10 * 10 ms and OFF for 10 *10 ms.

    */

   tngencad.cycles = 255;

   tngencad.numsegs = 4;

   tngencad.offtime[0] = 10;

   tngencad.offtime[1] = 10;

   tngencad.offtime[2] = 10;

   tngencad.offtime[3] = 10;

   

   dx_bldtngen( &tngencad.tone[0], 350, 440, -17, -17, 125 );

   dx_bldtngen( &tngencad.tone[1], 350, 440, -17, -17, 10 );

   dx_bldtngen( &tngencad.tone[2], 350, 440, -17, -17, 10 );

   dx_bldtngen( &tngencad.tone[3], 350, 440, -17, -17, 10 );



   /*

    * Play the custom dial tone.

    */

   if (dx_playtoneEx( dxxxdev, &tngencad, tpt, EV_SYNC ) == -1 ) {

      printf( "Unable to Play the Cadenced Tone\n" );

      printf( "Lasterror = %d  Err Msg = %s\n",

      ATDV_LASTERR( dxxxdev ), ATDV_ERRMSGP( dxxxdev ) );

      dx_close( dxxxdev );

      exit( 1 );

   }



   /*

   /* Examine termination reason in bitmap. 

   /* If time-out caused termination, play reorder tone.

    */

   if((term = ATDX_TERMMSK(dxxxdev)) == AT_FAILURE) {

     /* Process error */

   }



   if(term & TM_MAXTIME) {

      /*

       * Play the standard Reorder Tone (fast busy) using the predefined tone 

       * from the set of standard call progress signals.

       */

       if (dx_playtoneEx( dxxxdev, CP_REORDER, tpt, EV_SYNC ) == -1 ) {

         printf( "Unable to Play the Cadenced Tone\n" );

         printf( "Lasterror = %d  Err Msg = %s\n",

         ATDV_LASTERR( dxxxdev ), ATDV_ERRMSGP( dxxxdev ) );

         dx_close( dxxxdev );

         exit( 1 );

       }

   }



   /* Terminate the Program */

   dx_close( dxxxdev );

   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 tg_dflag field in TN_GEN structure
EDX_SYSTEM	Error from operating system; use dx_fileerrno( ) to obtain error value

See Also

• dx_playtone( )
• dx_bldtngen( )
• TN_GEN data structure
• TN_GENCAD data structure

Click here to contact Dialogic Customer Engineering