1.7.14. Stop Currently Playing Tone (BRI Only)

The GCIS_EXID_STOPTONE extension ID is supported when using Springware boards only. When using DM3 boards, the GCIS_EXID_STOPTONE extension ID is not supported.

The GCIS_EXID_STOPTONE extension ID 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 this 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.

This extension ID 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.

The following table provides the parameter inputs for the gc_Extension( ) function.

Parameter	Input
target_type	GCTGT_GCLIB_CHAN
target_id	line device handle of the device
ext_id	GCIS_EXID_STOPTONE
mode	EV_SYNC, EV_ASYNC

Example

int extStopTone (LINEDEV handle)
{
        GC_PARM_BLKP parm_blkp = NULL, ret_blkp = NULL;
        unsigned long mode;
        GC_INFO  t_Info;
        int indicator;
        int ret_val = 0; 
        ret_val = gc_Extension( GCTGT_GCLIB_CHAN, handle
                   GCIS_EXID_STOPTONE, parm_blkp, &ret_blkp, mode);
        if ( ret_val )
    {
        ret_val = gc_ErrorInfo(&t_Info);
        if (ret_val == GC_SUCCESS) {
               printf("gc_ErrorInfo() successfully called\n");
               PrintGC_INFO(&t_Info);
       } else {
               printf("gc_ErrorInfo() call failed\n");
       }
    }  
       	 	gc_util_delete_parm_blk( ret_blkp );
        gc_util_delete_parm_blk( parm_blkp );
        return ret_val;
} 

Termination Events

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

Notes:

1. If an I/O function terminates due to another reason before the gc_Extension(GCIS_EXID_STOPTONE) function is issued, the reason for termination will not indicate that gc_Extension(GCIS_EXID_STOPTONE) was called.
2. In asynchronous mode, if the application tries to stop a tone that is already stopped, you will receive the GCEV_EXTENSION (ext_id = GCIS_EXEV_STOPTONEFAIL) termination event. Using the gc_ResultMsg( ) function will retrieve the error code ERR_TONESTOP.
3. In synchronous mode, if the application tries to stop a tone that is already stopped, the function will fail. Using the gc_ResultMsg( ) function will retrieve the error code ERR_TONESTOP.
4. When calling the gc_Extension(GCIS_EXID_STOPTONE) function from a signal handler, the mode parameter must be set to EV_ASYNC.
5. This function is not supported for the BRI/2 board or PRI protocols.

Click here to contact Telecom Support Resources