5.4 Asynchronous Digit Collection

AG Access enables applications to collect DTMF digit strings asynchronously into their own buffers. The function adiCollectDigits initiates digit collection. Digits are appended to the user-specified buffer until a terminating event occurs. Figure 23 illustrates the asynchronous digit collection process.

The collection function has programmable termination conditions. One can also prematurely terminate the function by invoking adiStopCollection. In all cases, AG Access sends an ADIEVN_COLLECTION_DONE message to the application, signaling collection has finished. The value field contains the termination reason. These values are defined in the AG Access Function Reference Manual.

You can modify the collection function's default behavior by specifying the following parameters when invoking adiCollectDigits. This information is communicated via the ADICOLLECT parameter structure which is defined in the AG Access Function Reference Manual.

• Acceptable digit list (validDTMFs): This is 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.

• Terminating digit list (terminators): This is a list of digits whose arrival will terminate collection. Typically, these digits are analogous to the ENTER or ESCAPE keys on a computer keyboard. A digit may be in both the acceptable digit list and terminating digit list.

• Initial timeout (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.

• Interdigit timeout (intertimeout): The time a caller is allowed between digits before collection terminates.

• Wait end tone (waitendtone): This parameter dictates when a collection done event is generated after the final digit is received. It can end on either an ADIEVN_DIGIT_BEGIN 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.

The collection function 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 AG Access' internal FIFO when adiStartCollection is invoked, AG Access processes the digits individually from the front of the FIFO (refer to Figure 22 on page 79). Each digit processed is checked against the Acceptable list, Terminating list, and Maximum digits parameter processing described above. The adiGetDigit and adiFlushDigitQueue functions are disallowed while the application is actively collecting.

When collection is complete, the ADIEVN_COLLECTION_DONE event is received with one of the following reasons:

Reason	Description
ADI_REASON_FINISHED	The number of digits requested was received.
ADI_REASON_STOPPED	The programmer invoked adiStopCollection.
ADI_REASON_TIMEOUT	Time-out occurred waiting for a digit.
ADI_REASON_DIGIT	A terminating digit was received.
ADI_REASON_RELEASED	The call was released.

Copyright 1996 Natural MicroSystems, Inc. All Rights Reserved.