adiGetDigit

Retrieves a digit from the front of the ADI service internal digit queue.

Supported board types

Prototype

DWORD adiGetDigit ( CTAHD ctahd, char *digit)

Argument	Description
ctahd	Context handle returned by ctaCreateContext or ctaAttachContext.
digit	Pointer to a character to store the digit copied from the digit queue. Valid digit values are the ASCII characters 0 through 9, # (number sign), and * (asterisk), as well as A, B, C, and D. If the digit queue is empty, *digit receives a value of 0 (zero).

Return values

Return value	Description
SUCCESS
CTAERR_BAD_ARGUMENT	digit is a NULL pointer.
CTAERR_FUNCTION_ACTIVE	Digit collection function is already active.
CTAERR_INVALID_CTAHD	Context handle is invalid.
CTAERR_INVALID_STATE	Function not valid in the current port state.
CTAERR_SVR_COMM	Server communication error.

Details

Use adiGetDigit to retrieve a single DTMF digit character from the front of the ADI service internal digit queue. The oldest digit is removed from the queue and copied to the address pointed to by digit. If the digit queue is empty, the value copied is 0 (zero).

The application must also be using ctaWaitEvent for digits to accumulate in the ADI service internal digit queue.

This function cannot be invoked if the application is actively collecting digits using adiCollectDigits.

To read the first digit without removing it from the collection queue, use adiPeekDigit.

If there is a digit in the internal digit queue that is configured in the abort_mask of a play or record operation to terminate the operation, the operation terminates immediately. Use adiGetDigit to remove the digit from the queue.

For more information, refer to Collecting digits.

Example

/* Remove and display digits in the digit queue */
void getandshowdigits( CTAHD ctahd )
{
   for (;;)
   {
       char digit;

       adiGetDigit( ctahd, &digit );
       if( digit == '\0' )
           break;
       putchar( digit );
   }
   putchar( '\n' );
}