adiStartToneDetector

Starts detecting a precise tone.

Supported board types

Prototype

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

Argument

Description

ctahd

Context handle returned by ctaCreateContext or ctaAttachContext.

toneid

ID or instance of the detector. The range is 1 through 6. 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;

Refer to ADI_TONEDETECT_PARMS for field descriptions.

Return values

Return value

Description

SUCCESS

 

ADIERR_INVALID_CALL_STATE

Function not available in the current call state.

CTAERR_BAD_ARGUMENT

Function argument had an invalid value, or a required pointer argument was NULL.

CTAERR_FUNCTION_ACTIVE

Function already active.

CTAERR_FUNCTION_NOT_AVAIL

Necessary .dsp file was not downloaded to the board.

CTAERR_INVALID_CTAHD

Context handle is invalid.

CTAERR_INVALID_STATE

Function not available in the current port state.

CTAERR_SVR_COMM

Server communication error.

Events

Event

Description

ADIEVN_TONE_1_BEGIN

Precise tone 1 detected on.

ADIEVN_CP_CED

Call progress analysis detected modem tone.

ADIEVN_CP_DIALTONE

Call progress analysis detected dial tone.

ADIEVN_CP_DONE

Call progress analysis complete.

ADIEVN_TONE_1_END

Precise tone 1 detected off.

ADIEVN_TONE_2_BEGIN

Precise tone 2 detected on.

ADIEVN_TONE_2_END

Precise tone 2 detected off.

ADIEVN_TONE_3_BEGIN

Precise tone 3 detected on.

ADIEVN_TONE_3_END

Precise tone 3 detected off.

ADIEVN_TONE_4_BEGIN

Precise tone 4 detected on.

ADIEVN_TONE_4_END

Precise tone 4 detected off.

ADIEVN_TONE_5_BEGIN

Precise tone 5 detected on.

ADIEVN_TONE_5_END

Precise tone 5 detected off.

ADIEVN_TONE_6_BEGIN

Precise tone 6 detected on.

ADIEVN_TONE_6_END

Precise tone 6 detected off.

ADIEVN_TONE_1_DETECT_DONE

Precise tone detector 1 terminated.

ADIEVN_TONE_2_DETECT_DONE

Precise tone detector 2 terminated.

ADIEVN_TONE_3_DETECT_DONE

Precise tone detector 3 terminated.

ADIEVN_TONE_4_DETECT_DONE

Precise tone detector 4 terminated.

ADIEVN_TONE_5_DETECT_DONE

Precise tone detector 5 terminated.

ADIEVN_TONE_6_DETECT_DONE

Precise tone detector 6 terminated.

Details

For AG and CG boards, adiStartToneDetector requires one of the following DSP files to be specified in the board keyword file, depending on the toneid specified:

CG boards

AG boards

Description

dtmf.f54

dtmfe.f54

ptf.m54

For toneid 1.

ptf.f54

ptf.m54

For toneid 2 through 6. The CG board uses dtmf/dtmfe for toneid 2 when detecting a single tone.

Use this function to start detecting 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 (for example, +/- bandwidth/2).

After the detector is started, if the specified tone is detected, the ADI service generates a BEGIN event. If the tone stops, the ADI service generates an END event. The detector continues until it is stopped by adiStopToneDetector, which is followed by a DONE event.

You can change the minimum qualification time specified by qualtime in the ADI_TONEDETECT_PARMS structure.

To set a time limit on the detection, use adiStartTimer to generate a timeout event. Call adiStopToneDetector if a timeout occurred.

For more information, refer to Detecting tones.

Example

int myDetectDialtone( CTAHD ctahd )
{
    CTA_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 ctaWaitEvent 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( CTA_IS_ERROR( event.value ) )
                     return MYFAILURE;                       /* API error */
                 else
                     return SUCCESS;                  /* stopped normally */
                 break;

                 /* might include cases to handle disconnect, DTMFs, etc. */
        }
    }
}