7.1 Introduction

7.2 Digit (DTMF) Collection

7.2.1 ADI Service Digit Queue

7.2.2 Synchronous Digit Collection

7.2.3 Asynchronous Digit Collection

7.2.4 Digit Collection Parameters

7.2.5 Terminating Asynchronous Digit Collection

7.3 DTMF Detector

7.3.1 DTMF Detection Parameters

7.3.2 Terminating DTMF Detection

7.3.3 Improving DTMF Using Echo Cancellation

7.1 Introduction

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. To capture DTMF digits, the application must leave the DTMF detector enabled. Because it is unusual to disable the detector, this discussion assumes it is always enabled.

Note: When using the Natural Call Control service with CT Access, the references (in this chapter) to start parameters and adiStartProtocol should be adjusted to refer to NCC parameters and nccStartProtocol.

In general, digit collection operates as follows:

• When a caller depresses a digit on the handset, the AG board sends an ADIEVN_DIGIT_BEGIN event to the application, and the digit becomes available.

• When the caller releases the key, the AG board sends an ADIEVN_DIGIT_END event to the application.

• Each event's value field contains an ASCII value indicating which key was pressed or released. The valid values are 0 through 9, *, #, and A through D.

If you want to...	Then use...
Retrieve (remove) a digit from the ADI service internal digit queue	adiGetDigit
Read (non-destructively) the first digit in the ADI service internal digit queue	adiPeekDigit
Start collecting digits from the digit queue	adiCollectDigits
Discard all digits in the ADI service internal digit queue	adiFlushDigitQueue
Stop adiCollectDigits	adiStopCollection
Enable the detection of DTMFs	adiStartDTMFDetector
Stop the DTMF detector	adiStopDTMFDetector
Enable the detection of MFs	adiStartMFDetector
Stop the MF detector	adiStopMFDetector

7.2 Digit (DTMF) Collection

This section describes digit collection for the ADI service. The subsections that follow describe the digit queue, synchronous and asynchronous digit collection, and digit collection parameters, respectively.

7.2.1 ADI Service Digit Queue

The ADI service maintains an internal DTMF digit queue to store digits that have been entered by the remote party. If the application is not actively collecting digits via adiCollectDigits, any DTMFs entered by the remote party are appended to the queue, as illustrated in Figure 23.

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.

Figure 23. Background Digit Collection

7.2.2 Synchronous Digit Collection

The ADI service provides three synchronous functions that access the internal ADI service digit queue:

Function	Description
adiGetDigit	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.
adiPeekDigit	Retrieves the oldest digit from the ADI service internal digit queue, without removing the digit from the queue.
adiFlushDigitQueue	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.

7.2.3 Asynchronous Digit Collection

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.

Figure 24 illustrates asynchronous digit collection:

Figure 24. Asynchronous Digit Collection

Note: 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.

7.2.4 Digit Collection Parameters

You can modify the collection function's default behavior by re-defining the parameters in ADI_COLLECT_PARMS when invoking adiCollectDigits. The ADI_COLLECT_PARMS structure is defined in the ADI Service Function Reference Manual.

The fields in ADI_COLLECT_PARMS include:

Parameter	Description
validDTMFs	A list of digits which act as a pass filter. Digits arriving from the AG board are written to the user buffer only if they are in the acceptable digit list. Digits received that are not in this list are discarded.
terminators	A list of digits whose arrival will terminate collection. Typically, these digits are analogous to the Enter key or Escape key on a computer keyboard. A digit may be in both the acceptable digit list and the terminating digit list.
firsttimeout	The time allowed for the caller to enter the first digit of a sequence. If the caller fails to enter the first acceptable digit in this period, collection terminates.
intertimeout	The time allowed to elapse between the entry of digits before collection terminates.
waitendtone	Dictates when a collection DONE event is generated after the final digit is received. It can end on either an ADIEVN_DIGIT_BEGIN event or ADIEVN_DIGIT_END event from the AG board. Triggering on the ADIEVN_DIGIT_BEGIN event is an optimization that accelerates processing of the caller's command.

7.2.5 Terminating Asynchronous Digit Collection

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 an ADIEVN_COLLECTION_DONE event to the application, which indicates that collection has finished. The value field contains the termination reason. These reasons are defined in the ADI Service Function Reference Manual.

An argument to adiCollectDigits, maxdigits, specifies the maximum number of digits to collect. Only digits written to the user buffer are counted (i.e., 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 already 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, the ADIEVN_COLLECTION_DONE event is delivered to the application.

Digit collection can also terminate when the interdigit timeout value in ADI_COLLECT_PARMS is exceeded.

When the ADIEVN_COLLECTION_DONE event is delivered to the application, one of the following reasons is in its value field:

Reason	Description
CTA_REASON_FINISHED	The number of digits requested was received.
CTA_REASON_STOPPED	The application invoked adiStopCollection.
CTA_REASON_TIMEOUT	Timeout occurred waiting for a digit.
CTA_REASON_DIGIT	A terminating digit was received.
CTA_REASON_RELEASED	The call was released.

7.3 DTMF Detector

AG boards and QX boards are capable of detecting DTMF digits. Section 7.2 discussed an interface for collecting digits (DTMFs) in your application. Digit collection assumes that DTMF detection is enabled.

All protocols (including NOCC) default to running the DTMF detector when a call is in the Connected state. Detection parameters are loaded when the protocol is started.

7.3.1 DTMF Detection Parameters

The DTMF detector parameter information is stored in the ADI_DTMFDETECT_PARMS structure. For more information about these parameters, refer to the ADI Service Function Reference Manual. Refer to Figure 25 for an illustration of these parameters.

You can modify the DTMF detector's default behavior by specifying the following parameters when invoking adiStartProtocol or adiStartDTMFDetector:

Parameter	Description
columnfour	A flag indicating that the fourth column of DTMFs, listed as 'A', 'B', 'C', and 'D', should be detected.
onqualtime	The minimum duration, in milliseconds, of a recognized DTMF signal before a DTMF-begin event is sent.
onqualampl	The minimum signal level in dBm, recognized as a DTMF signal.
offqualtime	The minimum duration, in milliseconds, of absence of a recognized DTMF signal before a DTMF-end event will be sent.
offqualampl	The minimum signal level in dBm to maintain recognition of a DTMF signal once recognition has started.

Figure 25. DTMF Detection Parameters

Do not modify the remaining parameters in the structure (specifically, onthreshold and offthreshold). They are parameters for the DSP algorithms and are included in the structure for diagnostic purposes when working with NMS Technical Services.

7.3.2 Terminating DTMF Detection

adiStopDTMFDetector immediately terminates DTMF detection. The ADI service generates an ADIEVN_DTMFDETECT_DONE event with the value set to CTA_REASON_STOPPED.

The ADI service may also generate the ADIEVN_DTMFDETECT_DONE event with an error code, ADIERR_xxx or CTAERR_xxx, if the function is started incorrectly.

7.3.3 Improving DTMF Using Echo Cancellation

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).

For boards except the QX 2000, the ADI service includes an alternate DSP file used specifically with echo cancellation.

To load this alternate DSP file:

1. Locate the reference to dtmf.xxx in the ag.cfg file (agmon users) or in the DSP.C5x.DSPFiles[x] keyword (OAM users). (Where xxx is either .dsp, .m54, or .f54. It is also possible that there is no file extension at all.)

2. Change dtmf to dtmfe.

3. Save your changes and re-initialize the board.

In general, echo cancellers of moderate length and adaptation time typically provide improvement of 10 - 15 dB in DTMF cut-through performance.