adiCollectDigits

Starts collecting DTMF digits.

Supported board types

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.

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;
     }
}
}