Starts active collection of DTMF digits.

DWORD adiCollectDigits ( CTAHD ctahd,
char *buffer,
unsigned maxdigits,
ADI_COLLECT_PARMS *parms )

ctahd CTA context handle returned by ctaCreateContext.

buffer Pointer to a buffer which receives the collected digits (because the returned string is NULL-terminated, the buffer must be sized to at least maxdigits +1 bytes).

maxdigits Maximum number of digits to collect.

parms Pointer to a digit collection parameter structure as shown (NULL designates default values for parameters):

typedef struct

{

DWORD size; /* size of this structure */

DWORD firsttimeout; /* timeout waiting for the first digit */

/* use 0 to wait forever. */

DWORD intertimeout; /* timeout waiting for the next digit */

/* use 0 to wait forever. */

DWORD waitendtone; /* if non-zero, collection does not */

/* end until the end of the final dtmf */

DWORD validDTMFs; /* mask of acceptable digits; use 0 */

/* or ADI_DIGIT_ANY to accept all. */

DWORD terminators; /* mask of terminating digits; use 0 */

/* to indicate no terminators. */

} ADI_COLLECT_PARMS;

• SUCCESS
• ADIERR_INVALID_CALL_STATE
• CTAERR_BAD_ARGUMENT
  buffer pointer is NULL.
• CTAERR_BAD_SIZE
  maxdigits is 0.
• CTAERR_FUNCTION_ACTIVE
• CTAERR_INVALID_CTAHD
• CTAERR_INVALID_STATE

• ADIEVN_COLLECTION_DONE
  Generated when the collection function completes. The event buffer field points to the same buffer passed to adiCollectDigits. The size field contains the number of characters collected, plus one to account for the null terminator. The value field contains one of the following termination reasons, or an error code:
• CTA_REASON_DIGIT
  A terminating digit was received.
• CTA_REASON_FINISHED
  Expected number of digits were collected.
• CTA_REASON_RELEASED
  The call was terminated.
• CTA_REASON_STOPPED
  Terminated by adiStopCollection.
• CTA_REASON_TIMEOUT
  Timed out waiting for a digit.

This function starts the asynchronous collection of DTMF digits. Any digits received before collection is started will be included, unless they have been discarded by calling adiFlushDigitQueue. Any digit not included in the validDTMFs mask will be discarded. Collection terminates, which generates an ADIEVN_COLLECTION_DONE event, when one of the following occurs:

• The maximum number of digits (maxdigits) is collected.

• The initial (firsttimeout) or interdigit (intertimeout) timeout expires.

• A terminating (terminators) digit is received.

• adiStopCollection is issued.

• The call is released.

The validDTMFs and terminators masks are built with the ADI_DIGIT_x constants, where x can be 0-9, A-D, #, and *, or the groups ANY, 0_9, A_D.

The ADI_DIGIT_x values are defined in adidef.h.

Note: If a digit is in both the terminators mask and in the validDTMFs mask, it will be included as the last digit in the collected string. If the string contains maxdigits digits, the termination reason will be CTA_REASON_FINISHED.

Refer to the ADI Service Developer's Manual for a complete description of digit collection.

adiStopCollection, adiFlushDigitQueue, adiGetDigit, adiStartDTMFDetector, adiStopDTMFDetector

int myGetDigits( CTAHD ctahd, char *digits, int maxdigits )
{
    ADI_COLLECT_PARMS parms;
 CTA_EVENT         event;

    *digits = 0;

    adiGetParms( ADI_COLLECT_PARMID, &parms, sizeof parms );
    parms.firsttimeout = 4000;          /* wait 4 seconds for first digit */
    parms.intertimeout = 2000;          /* wait 2 seconds between digits  */

    adiCollectDigits( ctahd, digits, maxdigits, &parms );

    while( 1 )
    {
        myGetEvent( &event );           /* see ctaWaitEvent example     */
  switch( event.id )
        {
            case ADIEVN_COLLECTION_DONE:
                if( event.value == CTA_REASON_RELEASED )
                    return MYDISCONNECT;    /* remote hang-up           */
                else if( CTA_IS_ERROR( event.value ) )
                    return MYFAILURE;       /* AG Access API error    */
                else if( strlen( digits ) == 0 )
                    return MYFAILURE;       /* no digits provided     */
                else
                    return SUCCESS;         /* got digits               */
                break;

            case ADIEVN_CALL_DISCONNECTED:
                /* In case this event was on the way up when we started
                 * collection. Wait for 'collection done' event.
                 */
                break;

            case ADIEVN_DIGIT_BEGIN:
            case ADIEVN_DIGIT_END:
                /* Typically don't want digit events. Wait for the
                 * string of digits with 'collection done'. 
                 */
                break;
        }
    }
}