The ADI service provides both synchronous and asynchronous digit collection functions. Call control must be in the connected state to activate the digit collection functions and the application must leave the DTMF detector enabled. DTMF detection parameters are loaded when the protocol is started.
In general, digit collection operates as follows:
When a caller depresses a digit on the handset, the board sends ADIEVN_DIGIT_BEGIN to the application, and the digit becomes available.
When the caller releases the key, the board sends ADIEVN_DIGIT_END to the application.
Each event's value field contains an ASCII value indicating the key pressed or released. The valid values are 0 through 9, * (asterisk), # (number sign), and A through D.
This topic presents:
The ADI service maintains an internal DTMF digit queue to store digits entered by the remote party. If the application is not actively collecting digits using adiCollectDigits, DTMFs entered by the remote party are appended to the queue, as shown in the following illustration.
The digit is stored in the ADI service digit queue when ADIEVN_DIGIT_BEGIN is received. If the ADI service digit queue is full when ADIEVN_DIGIT_BEGIN arrives, the oldest digit is discarded and the latest digit is queued. The ADI service digit queue can hold 64 digits.
The following illustration shows background digit collection:
The ADI service provides four synchronous functions that access the internal ADI service digit queue:
|
Function |
Description |
|---|---|
|
Retrieves a single digit from the ADI service internal digit queue, thus removing the oldest digit from the queue. If the queue is empty, a zero (0) is returned; otherwise, the ASCII value is returned. |
|
|
Inserts a digit at the end of the ADI service internal digit queue. |
|
|
Retrieves the oldest digit from the ADI service internal digit queue, without removing the digit from the queue. |
|
|
Discards all digits stored in the internal digit queue. |
None of these functions can be invoked if the application is actively collecting digits with adiCollectDigits.
The ADI service enables applications to collect DTMF digit strings asynchronously into their own buffers. adiCollectDigits initiates digit collection into a user-specified buffer rather than into the ADI service digit queue. Digits are appended to the user-specified buffer until a terminating event occurs.
The following illustration represents asynchronous digit collection:
Because they perform read and write operations on the internal digit queue, an application cannot call adiGetDigit and adiFlushDigitQueue while actively collecting digits. The ADI service returns an error if an application attempts to modify the internal digit queue while digit collection is active.
You can modify the collection function's default behavior by redefining the parameters in ADI_COLLECT_PARMS when invoking adiCollectDigits.
The collection operation has programmable termination conditions. An application can also prematurely terminate the function by invoking adiStopCollection. In all cases, the ADI service sends ADIEVN_COLLECTION_DONE to the application, which indicates that collection finished. The value field contains the termination reason.
The maxdigits argument in adiCollectDigits specifies the maximum number of digits to collect. Only digits written to the user buffer are counted. For example, digits discarded because they are not in the acceptable list are not counted. Digit collection terminates when this maximum digit count is reached.
If digits are stored in the ADI service's internal digit queue when adiCollectDigits is invoked, the ADI service processes the digits individually from the front of the ADI service digit queue. Each digit processed is checked against a list of acceptable digits, and a list of terminating digits, which are stored in the validDTMFs and terminator fields in the ADI_COLLECT_PARMS structure. Invalid digits are discarded. Terminating digits cause digit collection to terminate.
When digit collection terminates, ADIEVN_COLLECTION_DONE is delivered to the application. For information on reasons, see adiCollectDigits.
Digit collection can also terminate when the interdigit timeout value in ADI_COLLECT_PARMS is exceeded.
You can modify the DTMF detector's default behavior when invoking adiStartProtocol or adiStartDTMFDetector. The DTMF detector parameters are stored in the ADI_DTMFDETECT_PARMS structure. The following illustration shows the effect of these parameters:
Note: Do not modify onthreshold and offthreshold. These parameters apply to the DSP algorithms and are provided for diagnostic purposes when working with Dialogic Services and Support.
adiStopDTMFDetector immediately terminates DTMF detection. The ADI service generates ADIEVN_DTMFDETECT_DONE with the value set to CTA_REASON_STOPPED.
The ADI service can also generate ADIEVN_DTMFDETECT_DONE with an error code, ADIERR_xxx or CTAERR_xxx, if the function is incorrectly started.
Echo cancellation improves the ability of the DTMF detector to recognize digits during play, a capability referred to as DTMF cut-through performance.
Using echo cancellation with the DTMF detector allows the use of a more selective DTMF detector, which improves resistance to talk-off (the false detection of digits in a speaker's voice).
AG and CG boards have an alternate DSP file (dtmfe) used specifically with echo cancellation. To load dtmfe:
|
Step |
Action |
|
1 |
Locate the reference to dtmf.xxx in the DSP.C5x[x].Files[y] keyword (DSP.C5x[x].Files for CG boards), where xxx is either .dsp, .m54, or .f54. There may be no file extension. |
|
2 |
Change dtmf to dtmfe. |
|
3 |
Save the changes and re-initialize the board. |
Echo cancellers of moderate length and adaptation time typically provide improvement of 10 to 15 dB in DTMF cut-through performance.