# adiStartToneDetector

Starts detecting a precise tone.

#### Supported board types

- AG

- CG

#### 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. */
}
}
}