cc_ToneRedefine( )

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

Name:	int cc_ToneRedefine(devHdl, sigType, pToneParm, mode)
Inputs:	LINEDEV devHdl	line device handle
	unsigned char sigType	Tone Signal Type
	toneParm *pToneParm	pointer to Tone Parameter structure
	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_ToneRedefine( ) function redefines a call progress tone's attributes in the tone template table. The tone template table resides in the firmware and is used during call establishment. The template contains common call progress tone types and is preset to default values at initialization (see Table 29. Tone Template Table). The current template has a total of eight entries, of which only four are defined. The other four are reserved for future use.

The cc_ToneRedefine( ) function allows the existing tone template to be redefined, but not the functional meanings of the call progress tones.

Parameter	Description
devHdl:	Specifies the valid channel device handle obtained when the channel was opened using cc_Open( ). Each channel has an internal tone template.
sigType:	Indicates the type of call progress tone, such as dial tone, busy tone, ringback, etc. Note that each sigType has its own meaning and cannot be changed, for example, sigType 0x01 always means a dial tone.
pToneParm:	Pointer to the tone parameter structure. For a description of the toneParm data structure, see Section 6.14. ToneParm.
mode:	Specifies whether to run this function asynchronously or synchronously. Set to either EV_ASYNC or EV_SYNC.

The following table shows the tone template table that resides in the firmware.

Table 29. Tone Template Table

Sig Type

Mean-ing

Default values (in ms)

		dura-tion	freq1	amp1	freq2	amp2	toneOn1	toneOff1	no use	no use
0x01	Dial tone	-1	350	-14	440	-14	-1	0	n/a	n/a
0x02	Busy tone	-1	480	-14	620	-14	500	500	n/a	n/a
0x03	Re-order	-1	480	-14	620	-14	300	200	n/a	n/a
0x04	Ring-back	-1	440	-14	480	-14	2000	4000	n/a	n/a
0x05	future use
0x06	future use
0x07	future use
0x08	future use

The default call progress tones are Dial Tone and Ringback Tone; however the Busy Tone or Reorder Tone will be played instead if the application provides the CCITT compatible SIGNAL IE by sending either the SETUP_ACK or ALERTING message (see the cc_SetInfoElem( ) function description for information on setting the SIGNAL IE). The SIGNAL IE must be programmed according to the ITU specifications. The firmware will correlate the specified signal, in the SIGNAL IE, with the appropriate sigType from the template table.

Termination Events

• CCEV_TONEREDEFINE - indicates that the tone was successfully redefined
• CCEV_TONEREDEFINEFAIL - indicates that the function failed

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

Cautions

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 <cclib.h>  
#include <srllib.h>  
#include <dxxxlib.h>  
main()  
{  
    unsigned short sigType = 0x01;  
    int            devHdl;  
    toneParm       ToneParm;  
   /*  
    * 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;  
   /*  
    * Redefine a dial tone to the internal template.  
    * This template has Frequency1 = 330,  
    * Frequency2 = 460, amplitude at -10dB for  
    * both frequencies and duration of infinity   
* This is a Panasonic Local Dial Tone.  
*/  
   cc_ToneRedefine(devHdl, sigType, &ToneParm, EV_SYNC );  
   /*  
    * 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 );  
}

The following example illustrates how to override the default tone that is played with an outgoing message. The example shows how the application uses the ALERTING message to direct the firmware to play the Busy tone instead of the default Ringback tone.

#include <windows.h>   /* For Windows applications only */  
#include <stdio.h>  
#include <errno.h>  
#include <cclib.h>  
#include <srllib.h>  
#include <dxxxlib.h>  
main()  
{  
    LINEDEV      boardDevHdl, tsDevHdl;  
    DCHAN_CFG    dchan_cfg;  
    IE_BLK       ie_buf;  
   /*  
    * Open the BRI Station Device  
    */  
   if ( ( cc_Open(&boardDevHdl, "briS1", 0) ) < 0 ) {  
      printf( "Error opening board device : errno < %d\n", errno );  
      exit( 1 );  
   }  
   /*  
    * Open the BRI Channel Device  
    */  
   if ( ( cc_Open(&tsDevHdl, "briS1T1", 0) ) < 0 ) {  
      printf("Error opening timeslot device : errno < %d\n",errno);  
      exit( 1 );  
   }  
   /*  
    * Configure the BRI station.  
    */  
   dchan_cfg.layer2_access       = FULL_ISDN_STACK;  
   dchan_cfg.switch_type         = ISDN_BRI_NI1;  
   dchan_cfg.switch_side         = NETWORK_SIDE;  
   dchan_cfg.number_of_endpoints = 1;  
   dchan_cfg.feature_controlA = DEFAULT_PCM_TONE |   
                                /* Want firmware to apply tones */  
                                HOST_CONTROLLED_RELEASE;  
             /* App. controls when B channel is fully released. */  
   /*  
    * Continue Processing  
    *   .  
    *   .  
    */  
   /*   
    * Use cc_SetInfoElem() to specify the SIGNAL IE,   
    * that is to be sent with the   
    * Alerting message. Firmware will provide the tone,   
    * corresponding to what is in the  
    * SIGNAL IE, providing it is available in the tone template   
    * table.  
    */  
   ie_buf.length = 3;  
   ie_buf.data[0] = 0x34;    /* Signal IE ID */  
   ie_buf.data[1] = 0x01;    /* Length of data in Signal IE */  
   ie_buf.data[2] = 0x04;    /* Q.931 definition for Busy Tone On   
                                signal value */  
   if (cc_SetInfoElem( tsDevHdl, &ie_buf) < 0) {  
      printf( "Error setting IE data : errno < %d\n", errno );  
      exit( 1 );  
   }  
   if (cc_AcceptCall( tsDevHdl, 0, EV_ASYNC) < 0) {  
      printf( "Error sending Alerting message : errno < %d\n",    
              errno );  
      exit( 1 );  
   }  
   /* Alerting message will generate a Busy tone, rather than a   
      Ringback tone. */  
   /*  
    * Continue Processing  
    *   .  
    *   .  
    */  
   /*  
    * Close the opened timeslot Device  
    */  
   if ( cc_Close( tsDevhdl ) != 0 ) {  
      printf( "Error closing devicd, errno= %d\n", errno );  
   }  
   /*  
    * Close the opened board Device  
    */  
   if ( cc_Close( boardDevhdl ) != 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_ToneRedefine( ) function include the following:

Error Code	Description
ERR_TONEINVALIDMSG	Invalid message type
ERR_TONESIGNALTYPE	Invalid signal type
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_DURATION	Invalid value specified in parameter duration

See Also

• cc_PlayTone( )

Click here to contact Dialogic Customer Engineering