(Page 5 of 5 in this chapter)

7.4 Using Asynchronous Digit Collection Functions

AG Access 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 AG Access digit queue). Digits are appended to the user-specified buffer until a terminating event occurs. Figure 27 illustrates the asynchronous digit collection process.
Note: Because they perform read/write operations on the internal digit queue, an application cannot call adiGetDigit and adiFlushDigitQueue while actively collecting digits. AG Access will return an error if an application attempts to modify the internal digit queue while digit collection is active.

7.4.1 Digit Collection Parameters

You can modify the collection operation's default behavior by re-defining the parameters in ADI_COLLECT_PARMS when invoking adiCollectDigits. The digit collection parameters are:

validDTMFs-This is an acceptable digit list which acts 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-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.

firsttimeout-This is 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-This is the time allowed to elapse between the entry of digits before collection terminates.

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.

Figure 27. Asynchronous Digit Collection

7.4.2 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, AG Access 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 AG Access 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 AG Access' internal digit queue when adiCollectDigits is invoked, AG Access processes the digits individually from the front of the AG Access 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 terminators fields in the ADI_COLLECT_PARMS structure. Invalid digits are discarded. Terminating digits cause the digit collection operation 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.

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.

(Page 5 of 5 in this chapter)

tech_support@nmss.com