TSPI_lineMonitorDigits

The TSPI_lineMonitorDigits function enables and disables the unbuffered detection of digits received on the call. Each time a digit of the specified digit mode(s) is detected, a LINE_MONITORDIGITS message is sent to the application by TAPI, indicating which digit is detected.

LONG TSPI_lineMonitorDigits(
  HDRVCALL hdCall,    
  DWORD dwDigitModes  
);
 

Parameters

hdCall

The handle to the call on which digits are to be detected. The call state of hdCall can be any state except idle or disconnected.

dwDigitModes

The digit mode(s) that are to be monitored. A dwDigitModes parameter with a value of 0 cancels digit monitoring. The dwDigitModes parameter can have any of the following LINEDIGITMODE_ flags set:

LINEDIGITMODE_PULSE

Detect digits as audible clicks that are the result of rotary pulse sequences. Valid digits for pulse are '0' through '9'. The LINE_MONITORDIGITS message is sent as soon after the last pulse of each digit as possible.

LINEDIGITMODE_DTMF

Detect digits as DTMF tones. Valid digits for DTMF are '0' through '9', 'A', 'B', 'C', 'D', '*', and '#'. The LINE_MONITORDIGITS message is sent as soon after the onset of each tone as possible.

LINEDIGITMODE_DTMFEND

Detect and provide notification of DTMF down edges. Valid digits for DTMF are '0' through '9', 'A', 'B', 'C', 'D', '*', and '#'. The LINE_MONITORDIGITS message is sent as soon as possible after the end of each digit, and before any indication of the beginning of a following digit.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALDIGITMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM.

Remarks

This function returns zero (success) when digit monitoring is correctly initiated, not when digit monitoring is terminated. Digit monitoring remains in effect until it is explicitly disabled by a call to TSPI_lineMonitorDigits with dwDigitModes set to zero, or until the call transitions to idle. The function must return zero when digit monitoring is canceled (that is, when the dwDigitModes parameter is zero). The service provider must terminate digit monitoring when the call goes idle. TAPI does not spontaneously call TSPI_lineMonitorDigits to terminate monitoring.

Although this function can be invoked in any call state, digits typically are detected only while the call is in the connected state.

Each time a digit is detected, the service provider sends a LINE_MONITORDIGITS message to TAPI, passing the detected digit as a parameter. If both LINEDIGITMODE_DTMF and LINEDIGITMODE_DTMFEND are set in dwDigitModes, the two LINE_MONITORDIGITS messages are sent for each digit.

TAPI can use TSPI_lineMonitorDigits to enable or disable unbuffered digit detection. It can use TSPI_lineGatherDigits for buffered digit detection. After buffered digit gathering is complete, a LINE_GATHERDIGITS message is sent. Both buffered and unbuffered digit detection can be enabled on the same call simultaneously.

See Also

LINE_GATHERDIGITS, LINE_MONITORDIGITS, LINEDEVCAPS, LINEDIGITMODE_ Constants, TSPI_lineGatherDigits, TSPI_lineGetDevCaps, TSPI_lineSetMediaControl