Starts active collection of DTMF digits.

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

ctahd Context handle returned by adiOpenPort.

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 DTMFs; use 0 or     */
      /* ADI_DIGIT_ANY to accept all.           */
 DWORD terminators;     /* mask of terminating DTMFs; 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
  The terminating digit was received.
• CTA_REASON_FINISHED
  Expected number of digits was received.
• 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. 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;

• the adiStopCollection function 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.

See Appendix D for default values and a more detailed explanation of the fields in the ADI_COLLECT_PARMS structure.

See the AG Access 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;
    ADI_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 adiFetchAndProcess example */

        switch( event.id )
        {
            case ADIEVN_COLLECTION_DONE:
                if( event.value == CTA_REASON_RELEASED )
                    return MYDISCONNECT;    /* remote hang-up */
                else if( IS_ADI_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;
        }
    }
}