# adiCollectDigits

Starts collecting DTMF digits.

#### Supported board types

- AG

- CG

#### Prototype

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

Argument | Description
ctahd | Context handle returned by ctaCreateContext or ctaAttachContext.
buffer | Pointer to the buffer that 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; Refer to ADI_COLLECT_PARMS for field descriptions and valid values.

#### Return values

Return value | Description
SUCCESS |
ADIERR_INVALID_CALL_STATE | Function not valid in the current call state.
CTAERR_BAD_ARGUMENT | buffer pointer is NULL.
CTAERR_BAD_SIZE | maxdigits is 0.
CTAERR_FUNCTION_ACTIVE | Attempt was made to get a digit or flush the digit queue while collecting digits.
CTAERR_INVALID_CTAHD | Context handle is invalid.
CTAERR_INVALID_STATE | Function is not valid in the current port state.
CTAERR_SVR_COMM | Server communication error.

#### Events

Event | Description
ADIEVN_COLLECTION_DONE | Generated when collection 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 Terminating digit received. CTA_REASON_FINISHED Expected number of digits collected. CTA_REASON_RELEASED Call terminated. CTA_REASON_STOPPED Terminated by adiStopCollection. CTA_REASON_TIMEOUT Timed out waiting for a digit.

#### Details

Use adiCollectDigits to start the asynchronous collection of DTMF digits. Any digits received before collection is started are included, unless they were discarded by calling adiFlushDigitQueue. Any digit not included in the validDTMFs mask is discarded. Collection terminates and ADIEVN_COLLECTION_DONE is generated 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.

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

#### See also

adiGetDigit, adiStartDTMFDetector, adiStopDTMFDetector

#### Example

int myGetDigits( CTAHD ctahd, char *digits, int maxdigits )
{
ADI_COLLECT_PARMS parms;
CTA_EVENT event;
*digits = 0;
ctaGetParms( 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;
}
}
}