lineMonitorDigits
The lineMonitorDigits
function enables and disables the unbuffered detection of digits received on
the call. Each time a digit of the specified digit mode is detected, a message
is sent to the application indicating which digit has been detected.
LONG lineMonitorDigits(
|
HCALL hCall, |
|
|
DWORD dwDigitModes |
|
|
); |
|
Parameters
hCall
A handle to
the call on which digits are to be detected. The call state of hCall can
be any state except idle or disconnected.
dwDigitModes
The digit
mode or modes that are to be monitored. If dwDigitModes is zero, digit
monitoring is canceled. This parameter can have multiple flags set, and uses
the following LINEDIGITMODE_ constants:
LINEDIGITMODE_PULSE
Detect digits
as audible clicks that are the result of rotary pulse sequences. Valid digits
for pulse are '0' through '9'.
LINEDIGITMODE_DTMF
Detect digits
as DTMF tones. Valid digits for DTMF are '0' through '9', 'A', 'B', 'C', 'D',
'*', and '#'.
LINEDIGITMODE_DTMFEND
Detect and
provide application notification of DTMF down edges. Valid digits for DTMF are
'0' through '9', 'A', 'B', 'C', 'D', '*', and '#'.
Return Values
Returns zero
if the request is successful or a negative error number if an error has
occurred. Possible return values are:
LINEERR_INVALCALLHANDLE,
LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED,
LINEERR_INVALDIGITMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM,
LINEERR_UNINITIALIZED.
Remarks
This function
is considered successful if digit monitoring has been correctly initiated; not
when digit monitoring has terminated. Digit monitoring remains in effect until
it is explicitly disabled by calling lineMonitorDigits with dwDigitModes
set to zero, until the call transitions to idle, or when the application
deallocates its call handle for the call. Although this function can be invoked
in any call state, digits are usually detected only while the call is in the connected
state.
Each time a
digit is detected, a LINE_MONITORDIGITS message is sent to the application
passing the detected digit as a parameter.
An
application can use lineMonitorDigits to enable or disable unbuffered
digit detection. It can use lineGatherDigits for buffered digit detection.
After buffered digit gathering is complete, a LINE_GATHERDIGITS message is sent
to the application. Both buffered and unbuffered digit detection can be enabled
on the same call simultaneously.
Monitoring of
digits on a conference call applies only to the hConfCall, not to the
individual participating calls.
See Also