cc_PlayTone( )

Description | Termination Events | Cautions | Example | Errors | See Also

Name:	int cc_PlayTone(devHdl, pToneParm, tptp, mode)
Inputs:	int devHdl	channel device handle
	toneParm *pToneParm	pointer to the toneParm structure
	DV_TPT *tptp	pointer to the DV_TPT structure
	int mode	asynchronous/synchronous
Returns:	0 on success <0 on failure
Includes:	cclib.h
Category:	Global Tone Generation
Mode:	asynchronous or synchronous
Technology:	BRI/SC

Description

The cc_PlayTone( ) function allows the application to play a user-defined tone. The tone's attributes are defined in the structure toneParm, which is pointed to by the parameter pToneParm.

Parameter	Description
devHdl:	The channel device handle of the channel on which the tone is to be played.
pToneParm:	The pointer to the tone parameter structure. See Section 6.14. ToneParm for a description of the toneParm structure.
tptp:	Points to the DV_TPT data structure, which specifies the terminating condition (DX_MAXTIME) for the function. DX_MAXTIME is the only allowed terminating condition; no other termination conditions are supported. See the Voice Software Reference -- Features Guide for the appropriate operating system for a description of the DV_TPT data structure.
mode:	Specifies whether to run the function asynchronously (EV_ASYNC) or synchronously (EV_SYNC).

Termination Events

• CCEV_PLAYTONE - indicates that the tone was successfully played.
• CCEV_PLAYTONEFAIL - indicates that the request to play a tone failed.

Use the SRL Event Management functions to handle the termination event.

Cautions

• The channel must be in the Idle state when calling the cc_PlayTone( ) function.
• The cc_PlayTone( ) command is a host tone command that allows the application to play a user-defined tone. This command cannot be used to set or play the firmware-applied call progress tones. The call progress tones and user-defined tones operate independently, except that when the firmware is playing a tone, the application may not play a tone on the same channel at the same time. For information on changing the firmware-applied call progress tones, see the cc_ToneRedefine( ) function description.
• This function is not supported for the BRI/2 board or for PRI protocols.

Example

#include <windows.h>   /* For Windows applications only */  
#include <stdio.h>  
#include <errno.h>  
#include <srllib.h>  
#include <cclib.h>  
#include <dxxxlib.h>  
#define TID_1   101  
main()  
{  
   toneParm     ToneParm;  
   DV_TPT       tpt;  
   int          devHdl;  
/*  
    * Open the Voice Channel Device and Enable a Handler  
    */  
   if ( ( cc_Open(&devHdl, "briS1T1", 0) ) < 0 ) {  
      printf( "Error opening device : errno < %d\n", errno );  
      exit( 1 );  
   }  
    ToneParm.freq1 = 330;  
    ToneParm.freq2 = 460;  
    ToneParm.amp1 = -10;  
    ToneParm.amp2 = -10;  
    ToneParm.toneOn1 = 400;  
    ToneParm.toneOff1 = 0;  
    ToneParm.duration = -1;  
tpt.tp_type = IO_EOT;  
tpt.tp_termno = DX_MAXTIME;  
tpt.tp_length = 6000;  
tpt.tp_flags = TF_MAXTIME;  
   /*  
    * Play a Tone with its  
    * Frequency1 = 330, Frequency2 = 460  
    * amplitude at -10dB for both  
    * frequencies and duration of infinity   
 * This is a Panasonic Local Dial Tone.  
    *   
    */  
    if (cc_PlayTone( devHdl, &ToneParm, &tpt, EV_SYNC ) == -1 ){  
      printf( "Unable to Play the Tone\n" );  
      printf( "Lasterror = %d  Err Msg = %s\n",  
      cc_CauseValue( devHdl ), cc_ResultMsg( devHdl ) );  
      cc_close( devHdl);  
      exit( 1 );  
   }  
   /*  
    * Continue Processing  
    *   .  
    *   .  
    *   .  
    */  
   /*  
    * Close the opened Voice Channel Device  
    */  
   if ( cc_Close( devHdl ) != 0 ) {  
      printf( "Error closing devicd, errno= %d\n", errno );  
   }  
   /* Terminate the Program */  
   exit( 0 );  
}

Errors

If the function returns < 0 to indicate failure, use the cc_CauseValue( ) function to retrieve the reason code for the failure. The cc_ResultMsg( ) function can be used to interpret the reason code. Error codes are defined in the files ccerr.h, isdnerr.h, and isdncmd.h.

Error codes from the cc_PlayTone( ) function include the following:

Error Code	Description
ERR_TONEINVALIDMSG	Invalid message type
ERR_TONEBUSY	Busy executing previous command
ERR_TONECP	System error with CP
ERR_TONEDSP	System error with DSP
ERR_TONEFREQ1	Invalid value specified in parameter freq 1
ERR_TONEFREQ2	Invalid value specified in parameter freq 2
ERR_TONEAMP1	Invalid value specified in parameter amp1
ERR_TONEAMP2	Invalid value specified in parameter amp2
ERR_TONEON1	Invalid value specified in parameter toneOn1
ERR_TONEOFF1	Invalid value specified in parameter toneOff1
ERR_TONEDURATION	Invalid value specified in parameter duration
ERR_TONECHANNELID	Invalid channel ID

See Also

• cc_ToneRedefine( )
• cc_StopTone( )

Click here to contact Dialogic Customer Engineering