Starts the detection of a precise tone.

DWORD adiStartToneDetector( CTAHD ctahd,
unsigned toneid,
unsigned freq1,
unsigned bandw1,
unsigned freq2,
unsigned bandw2,
ADI_TONEDETECT_PARMS *parms )

ctahd Context handle returned by adiOpenPort.

toneid ID or instance of the detector. The range is from 1 to 3. If the current protocol is providing "cleardown" detection, toneid=1 is not available.

freq1 First (or only) frequency to detect (in Hz).

bandw1 Bandwidth of the first frequency (in Hz)

freq2 The second frequency (in Hz) if the tone contains two frequencies, otherwise zero.

bandw2 Bandwidth of the second frequency.

parms Pointer to tone detection parameters, as shown (NULL designates default values):

typedef struct
{
 DWORD size;    /* size of this structure                */
 INT32 qualampl;    /* broadband qual level (in dBm)         */
 DWORD qualtime;    /* qualification time (in ms)            */
 DWORD reflevel;    /* qual thresh,output of filter (IDUs)   */
 DWORD reserved;    /* reserved, must be 0                   */
} ADI_TONEDETECT_PARMS;

See Appendix D for default values and a more detailed explanation of the fields in this structure.

• SUCCESS
• CTAERR_BAD_ARGUMENT
• ADIERR_INVALID_CALL_STATE
• CTAERR_FUNCTION_ACTIVE
• CTAERR_FUNCTION_NOT_AVAIL
• CTAERR_INVALID_CTAHD
• CTAERR_INVALID_STATE

• ADIEVN_TONE_1_BEGIN
• ADIEVN_TONE_1_END
• ADIEVN_TONE_2_BEGIN
• ADIEVN_TONE_2_END
• ADIEVN_TONE_3_BEGIN
• ADIEVN_TONE_3_END
• ADIEVN_TONE_1_DETECT_DONE
• ADIEVN_TONE_2_DETECT_DONE
• ADIEVN_TONE_3_DETECT_DONE

This function may require one of the following DSP files to be loaded by agmon depending on toneid specified:

DSP File	Description
dtmf.dsp/dtmfe.dsp	For toneid 1
callp.dsp	For toneid 2 or 3

This function starts the detection of a precise tone, which consists of one or two frequencies. The precise tone is defined in terms of center frequency and bandwidth pairs, specified in Hz. Bandwidth is the total band around the center frequency (e.g., +/- bandwidth/2).

Once the detector is started, if the specified tone is detected, AG Access generates a BEGIN event. If the tone stops, AG Access generates an END event. The detector continues until it is stopped by adiStopToneDetector, which will be followed by a DONE event.

By default, you will probably not need to change ADI_TONEDETECT_PARMS structure. In some cases you may need to change the minimum qualification time, specified by qualtime.

To set a time limit on the detection, you can use adiStartTimer to generate a timeout event. You would have to call adiStopToneDetector if a timeout occurred.

adiStopToneDetector

int myDetectDialtone( CTAHD ctahd )
{
    ADI_EVENT event;
    unsigned toneid = 2;
    unsigned frequency1 = 350;
    unsigned bandwidth1 =  50;
    unsigned frequency2 = 440;
    unsigned bandwidth2 =  50;

    if( adiStartToneDetector( ctahd, toneid, frequency1, bandwidth1,
                              frequency2, bandwidth2, NULL ) != SUCCESS )
        return MYFAILURE;

    while( 1 )
    {
        myGetEvent( &event );           /* see adiFetchAndProcess example */

        switch( event.id )
        {
            case ADIEVN_TONE_2_BEGIN:
                adiStopToneDetector( ctahd, toneid );
                break;                      /* on TONE_DETECT_DONE, will return */
            case ADIEVN_TONE_2_DETECT_DONE:
                if( event.value == CTA_REASON_RELEASED )
                    return MYDISCONNECT;    /* call has been terminated */
                else if( IS_ADI_ERROR( event.value ) )
                    return MYFAILURE;       /* API error */
                else
                    return SUCCESS;         /* stopped normally */
                break;
    
            /* might include cases to handle disconnect, DTMFs, etc. */
        }
    }
}