2.4.2.6 Digit Gathering
Besides enabling digit monitoring and being notified of digits one at a time, the TAPI DLL can also request that multiple digits be collected in a buffer. Only when the buffer is full or when some other termination condition is met is the TAPI DLL notified. Digit gathering is useful for functions such as credit card number collection. The TAPI DLL invokes TSPI_lineGatherDigits specifying a buffer to fill with digits. Digit gathering terminates when one of a number of conditions is true.
- The requested number of digits has been collected.
- One of multiple termination digits is detected. The termination digits are specified to TSPI_lineGatherDigits, and the termination digit is placed in the buffer as well.
- One of two timeouts expires. The timeouts are a first digit timeout, specifying the maximum duration before the first digit must be collected, and an inter-digit timeout, specifying the maximum duration between successive digits.
- Digit gathering is canceled explicitly by invoking TSPI_lineGatherDigits again with either another set of parameters (e.g., a new buffer) to start a new gathering request or by using a NULL digit buffer parameter to simply cancel.
When terminated for whatever reason, a LINE_GATHERDIGITS message is sent to the application that requested the digit gathering. Note that only a single digit gathering request can be outstanding on a call at any given time.
TSPI_lineGatherDigits
Performs the buffered gathering of digits on a call.
Note that digit gathering and digit monitoring may be enabled on the same call at the same time. In that case, the TAPI DLL will receive a LINE_MONITORDIGITS message for each detected digit and a separate LINE_GATHERDIGITS message when the buffer is sent back.