cc_StopTone( )

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

Name:	int cc_StopTone(devHdl, mode)
Inputs:	int devHdl	channel device handle
	int mode	asynchronous/synchronous
Returns:	0 on success <0 on failure
Includes:	cclib.h
Category:	Global Tone Generation
Mode:	asynchronous/synchronous
Technology:	BRI/SC

Description

The cc_StopTone( ) function forces the termination of a tone that is currently playing on a channel. The function forces a channel that is in the playing state to become idle. Running the cc_StopTone( ) function asynchronously initiates the function without affecting processes on other channels. Running this function synchronously within a process does not block other processing, allowing other processes to continue to be serviced.

The cc_StopTone( ) function allows the application to stop the playing of user-defined tones only. This command cannot be used to stop the playing of the firmware-applied call progress tones. The firmware-applied call progress tones and user-defined tones operate independently, except that when the firmware is playing a call progress tone, the application may not play a user-defined tone on the same channel at the same time.

Parameter	Description
devHdl:	Specifies the channel device handle that was obtained when the channel was opened using cc_Open( ).
mode:	Specifies whether to run the function asynchronously (EV_ASYNC) or synchronously (EV_SYNC).

Termination Events

• CCEV_STOPTONE - indicates that the tone was successfully stopped and the channel was returned to the idle state.
• CCEV_STOPTONEFAIL - indicates that the request to stop a tone and return the channel to the idle state failed.

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

Cautions

• If an I/O function terminates due to another reason before the cc_StopTone( ) function is issued, the reason for termination will not indicate that cc_StopTone( ) was called.
• In asynchronous mode, if the application tries to stop a tone that is already stopped, the CCEV_STOPTONEFAIL termination event will be received. Using the cc_ResultMsg( ) function will retrieve the error code ERR_TONESTOP.
• In synchronous mode, if the application tries to stop a tone that is already stopped, the function will fail. Using the cc_ResultMsg( ) function will retrieve the error code ERR_TONESTOP.
• When calling cc_StopTone( ) from a signal handler, the mode parameter must be set to EV_ASYNC.
• This function is not supported for the BRI/2 board or PRI protocols.

Example

#include <windows.h>   /* For Windows applications only */  
#include <srllib.h>  
#include <dxxxlib.h>  
#include <cclib.h>  
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  
    * 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 );  
   }  
       .  
       .  
       .  
       .  
    
   /* Force the channel idle.  The I/O function that the channel is  
    * executing will be terminated.  
    * In the asynchronous mode, cc_StopTone() returns immediately,  
    * without waiting for the channel to go idle.  
    */  
   if ( cc_StopTone(devHdl, EV_ASYNC) == -1) {  
      /* process error */  
   }  
}

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_StopTone( ) 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_TONECHANNELID	Invalid channel ID
ERR_TONESTOP	Tone has already stopped playing on this channel

See Also

• cc_PlayTone( )
• cc_ToneRedefine( )

Click here to contact Dialogic Customer Engineering