adiStartDTMFDetector

Starts DTMF detection.

Supported board types

Prototype

DWORD adiStartDTMFDetector ( CTAHD ctahd, ADI_DTMFDETECT_PARMS *parms)

Argument

Description

ctahd

Context handle returned by ctaCreateContext or ctaAttachContext.

parms

Pointer to DTMF detection parameters according to the following structure (NULL value uses the default values):

typedef struct
{
  DWORD size;          /* size of this structure           */
  DWORD columnfour;    /* 1=detect DTMFs A,B,C,D; 0=don't */
  INT32 onqualampl;    /* min input lev to qual tone (dBm) */
  DWORD onthreshold;   /* reserved                         */
  DWORD onqualtime;    /* qualify time of DTMF (ms)        */
  INT32 offqualampl;   /* min input lev of valid DTMF (dBm)*/
  DWORD offthreshold; /* reserved                         */
  DWORD offqualtime;   /* disqualify time for tone (ms)    */
} ADI_DTMFDETECT_PARMS;

Refer to ADI_DTMFDETECT_PARMS for field descriptions.

Return values

Return value	Description
SUCCESS
ADIERR_INVALID_CALL_STATE	Function not valid in the current call state.
CTAERR_FUNCTION_ACTIVE	Function already started.
CTAERR_INVALID_CTAHD	Context handle is invalid.
CTAERR_INVALID_STATE	Function not valid in the current port state.
CTAERR_SVR_COMM	Server communication error.

Events

Event	Description
ADIEVN_DIGIT_BEGIN	Raw DTMF digit detected on.
ADIEVN_DIGIT_END	Raw DTMF digit detected off.
ADIEVN_DTMF_DETECT_DONE	DTMF detector no longer running. The event value field contains one of the following: CTA_REASON_RELEASED Call terminated. CTAERR_xxx or ADIERR_xxx DTMF detector failed. CTA_REASON_STOPPED Function stopped with adiStopDTMFDetector.

Details

The following DSP file must be loaded to the board before running adiStartDTMFDetector:

For these boards...	Load this DSP file...
AG	dtmf.m54 or dtmfe.m54
CG	dtmf.f54 or dtmfe.f54

See DSP file summary for DSP file descriptions. Refer to the board installation and developer's manual for a table of MIPS usage for all functions.

Use this function to enable detection of DTMFs. By default, the DTMF detector is active after the NOCC protocol is started, or when the context enters the call control connected state. Therefore, this function is needed only to restart the DTMF detector if it was stopped using adiStopDTMFDetector or to modify the DTMF detector parameters.

An ADIEVN_DIGIT_BEGIN event and an ADIEVN_DIGIT_END event are generated for every digit detected. Each event contains the ASCII representation (character) of the digit: 0 through 9, A through D, * (asterisk), or # (number sign) in the event value field.

The DTMF detector must be enabled for the digit collection functions (for example, adiCollectDigits or adiGetDigit).