function initiates the buffered gathering of digits on the specified call.
The application specifies a buffer in which to place the digits and the maximum
number of digits to be collected.
| HCALL hCall,
| DWORD dwDigitModes,
| LPSTR lpsDigits,
| DWORD dwNumDigits,
| LPCSTR lpszTerminationDigits,
| DWORD dwFirstDigitTimeout,
| DWORD dwInterDigitTimeout
A handle to the call on which digits are to be gathered. The application must
be an owner of the call. The call state of hCall
can be any state.
The digit mode(s) to be monitored. Note that dwDigitModes
is allowed to have one or more flags set. This parameter uses the following
Detect digits as audible clicks that are the result of the use of rotary pulse
sequences. Valid digits for pulse mode are '0' through '9'.
Detect digits as DTMF tones. Valid digits for DTMF mode are '0' through '9',
'A', 'B', 'C', 'D', '*', '#'.
A pointer to the buffer where detected digits are to be stored as ASCII
characters. Digits may not show up in the buffer one at a time as they are collected.
Only after a LINE_GATHERDIGITS
message is received should the content of the buffer be assumed to be valid.
is NULL, the digit gathering currently in progress on the call is terminated
is ignored. Otherwise, lpsDigits
is assumed to have room for dwNumDigits
The number of digits to be collected before a LINE_GATHERDIGITS message is
sent to the application. The dwNumDigits
parameter is ignored when lpsDigits
is NULL. This function fails if dwNumDigits
Specifies a NULL-terminated string of termination digits as ASCII characters.
If one of the digits in the string is detected, that termination digit is
appended to the buffer, digit collection is terminated, and the LINE_GATHERDIGITS
message is sent to the application.
Valid characters for pulse mode are '0' through '9'. Valid characters for DTMF
mode are '0' through '9', 'A', 'B', 'C', 'D', '*', '#'. If this pointer is
NULL, or if it points to an empty string, the function behaves as though no
termination digits were supplied.
The time duration in milliseconds in which the first digit is expected. If the
first digit is not received in this timeframe, digit collection is aborted and
a LINE_GATHERDIGITS message is sent to the application. The buffer only
contains the NULL character, indicating that no digits were received and the first
digit timeout terminated digit gathering. The call's line-device capabilities
specify the valid range for this parameter or indicate that timeouts are not
The maximum time duration in milliseconds between consecutive digits. If no
digit is received in this timeframe, digit collection is aborted and a
LINE_GATHERDIGITS message is sent to the application. The buffer only contains the digits
collected up to this point followed by a NULL character, indicating that an
interdigit timeout terminated digit gathering. The call's line-device
capabilities specify the valid range for this parameter or indicate that timeouts are not
Returns zero if the request is successful or a negative error number if an
error has occurred. Possible return values are:
LINEERR_INVALCALLHANDLE, LINEERR_NOMEM, LINEERR_INVALCALLSTATE,
LINEERR_NOTOWNER, LINEERR_INVALDIGITMODE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDIGITS,
LINEERR_OPERATIONFAILED, LINEERR_INVALPARAM, LINEERR_RESOURCEUNAVAIL,
LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_INVALTIMEOUT.
Digit collection is terminated when the requested number of digits has been
collected. It is also terminated when one of the digits detected matches a digit
before the specified number of digits has been collected. The detected
termination digit is also placed in the buffer and the partial buffer is returned.
Another way of cancelling digit collection is when one of the timeouts
expires. The dwFirstDigitTimeout
expires if the first digit is not received in this time period. The dwInterDigitTimout
expires if the second, third, (and so forth) digit is not received within
that time period from the previously detected digit, and a partial buffer is
A fourth method for terminating digit detection is by calling this function
again while collection is in progress. The old collection session is terminated,
any digits collected up to that point are copied to the buffer supplied from
the previous call to this function, and the buffer is delivered when the
LINE_GATHERDIGITS message is sent to the application. The mechanism for terminating
digit gathering without initiating another gathering of the digits is by invoking
this function with lpsDigits
equal to NULL.
This function is considered successful if digit collection has been correctly
initiated, not when digit collection has terminated. In all cases where a
partial buffer is returned, valid digits (if any) are followed by an ASCII NULL
Although this function can be invoked in any call state, digits can typically
only be gathered while the call is in the connected
The message LINE_GATHERDIGITS is sent only to the application that initiated
the request. It is also sent when partial buffers are returned because of
timeouts or matching termination digits, or when the request is canceled by another lineGatherDigits
request on the call. Only one gather
digits request can be active on a call at any given time across all
applications that are owners of the call. Given the asynchronous behavior of the
operation, an application that issues multiple lineGatherDigits
in quick succession may be able to do so and receive several
LINE_GATHERDIGITS messages later. While this would be unusual application behavior, the
application will be able to count the number of these messages to allow cancel
messages to be matched with the earlier requests. In any case, only the most recent
request should be assumed to be valid.
An application can use lineMonitorDigits
to enable or disable unbuffered digit detection. Each time a digit is
detected in this fashion, a LINE_MONITORDIGITS
message is sent to the application. Both buffered and unbuffered digit
detection can be enabled for the same call simultaneously.
Gathering of digits on a conference call applies only to the hConfCall
, not to the individual participating calls.
If the lineGatherDigits
function is used to cancel a previous request to gather digits, the function
copies any digits collected up to that point to the buffer specified in the
original function call and sends a LINE_GATHERDIGITS message to the application,
regardless of whether the lpszDigits
parameter in the second call specifies a NULL or different address.
- Software for developers
Software for Android Developers
- More information resources
Unix Manual Pages