ITLegacyCallMediaControl2::GatherDigits method (tapi3if.h)

Article
10/13/2021

The GatherDigits method initiates the gathering of digits on the specified call. The application specifies the maximum number of digits to collect.

Syntax

HRESULT GatherDigits(
  [in] TAPI_DIGITMODE DigitMode,
  [in] long           lNumDigits,
  [in] BSTR           pTerminationDigits,
  [in] long           lFirstDigitTimeout,
  [in] long           lInterDigitTimeout
);

Parameters

[in] DigitMode

The digit mode(s) to monitor. This parameter specifies one or more of the LINEDIGITMODE constants.

[in] lNumDigits

The number of digits to collect.

If this parameter is zero, the method cancels any digit-gathering in progress, without starting a new digit-gathering attempt. For more information, see the following Remarks section.

[in] pTerminationDigits

Pointer to a BSTR representation of the termination digits. If one of the termination digits in the string is detected, that digit is appended to the buffer, digit collection is terminated, and the TE_GATHERDIGITS event is sent to the application.

[in] lFirstDigitTimeout

The length of time, in milliseconds, during which the first digit is expected. If the first digit is not received in this timeframe, digit collection is aborted and a TE_GATHERDIGITS event is sent to the application. The buffer contains only the NULL character, indicating that no digits were received and that the first-digit-timeout terminated digit-gathering. The minimum and maximum timeouts you can specify are found in the AC_GATHERDIGITSMINTIMEOUT and AC_GATHERDIGITSMAXTIMEOUT capabilities.

[in] lInterDigitTimeout

The maximum time, in milliseconds, between consecutive digits. If the next digit is not received in this timeframe, digit collection is aborted and a TE_GATHERDIGITS event is sent to the application. The buffer contains only the digits collected up to this point followed by a NULL character, indicating that an interdigit-timeout terminated the digit-gathering. The minimum and maximum timeouts that can be specified are found in the AC_GATHERDIGITSMINTIMEOUT and AC_GATHERDIGITSMAXTIMEOUT capabilities.

Return value

This method can return one of these values.

Return code	Description
S_OK	Method succeeded.
E_POINTER	The pTerminationDigits parameter is not a valid pointer.
E_OUTOFMEMORY	There is not enough memory to allocate the gather digits buffer.
TAPI_E_INVALCALLSTATE	The call must be in the connected state.

Remarks

The GatherDigits method translates to a call to the TAPI 2.x lineGatherDigits function.

Only one GatherDigits call can be outstanding on a call. If you call GatherDigits again, before the TE_GATHERDIGITS event has occurred, the second call cancels the previous gathering of digits. Canceled digit-gathering attempts send a TE_GATHERDIGITS event with the digits collected so far.

Requirements

Requirement	Value
Target Platform	Windows
Header	tapi3if.h
Library	Uuid.lib
DLL	Tapi3.dll

Share via