Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function initiates the generation of the specified digits on the specified call as in-band tones using the specified signaling mode. Invoking this function while digit or tone generation is in progress aborts the current digit or tone generation. Passing a NULL value for the lpsDigitsparameter generates no new digits.

Note:
Only one in-band generation request at a time (tone generation or digit generation) can be in progress per call.

Syntax 

LONG TSPIAPI TSPI_lineGenerateDigits(
  HDRVCALL 
hdCall,
  DWORD 
dwEndToEndID, 
  DWORD 
dwDigitMode,
  LPCWSTR 
lpszDigits, 
  DWORD 
dwDuration 
);

Parameters

hdCall

Handle to the call on which digit generation is to be done.

dwEndToEndID

This unique request identifier should be stored by the service provider and passed back as dwParam2to the LINEEVENTprocedure when the digit generation is completed.

dwDigitMode

Format to be used for signaling these digits. This parameter uses one and only one of the LINEDIGITMODEconstants.

lpszDigits

P to a null-terminated Unicode character buffer that contains the digits to be generated. A comma injects an extra delay between the signaling of the previous and next digits it separates. The duration of this pause is configuration defined. The line's device capabilities indicate what this duration is. Multiple commas can be used to inject longer pauses. Invalid digits are ignored during the generation, rather than being reported as an error.

dwDuration

Value that specifies both the duration in milliseconds of DTMF digits and pulse and DTMF inter-digit spacing. A value of zero uses a default value. The dwDurationparameter must be within the range specified by MinDialParamsto MaxDialParamsin LINEDEVCAPS. If out of range, the actual value is set by the service provider to the nearest value in the range. This parameter is not validated by TAPI when this function is called.

Return Value

Returns zero if the function succeeds or an error number if an error occurs. The following table shows the return values for this function.

Value Description

LINEERR_INVALCALLHANDLE

The handle to the call is invalid.

LINEERR_NOMEM

Not enough memory is available.

LINEERR_INVALCALLSTATE,

The call state is invalid.

LINEERR_OPERATIONUNAVAIL

The operation is unavailable.

LINEERR_INVALDIGITMODE

The digit mode is invalid.

LINEERR_OPERATIONFAILED

The operation failed.

LINEERR_RESOURCEUNAVAIL

The resource is unavailable

Remarks

The call state of hdCallcan be any state.

The TSPI_ lineGenerateDigitsfunction is considered to have completed successfully when the digit generation is successfully initiated; not when all digits are generated.

After all digits in lpsDigitsare generated, or after digit generation is aborted or canceled, a LINE_GENERATEmessage is sent to TAPI.

Only one inband generation request (tone generation or digit generation) is allowed to be in progress per call. This implies that if digit generation is currently in progress on a call, invoking either TSPI_ lineGenerateDigitsor the TSPI_lineGenerateTonefunction cancels the digit generation. The service provider must terminate any digit generation in progress when a subsequent TSPI_ lineGenerateDigitsor TSPI_ lineGenerateToneis invoked. Invoking TSPI_ lineGenerateDigitswith lpszDigitsset to NULL cancels any current digit (or tone) generation.

The corresponding function at the TAPI level does not include the formal parameter dwEndToEndID. At that level, there is no end-to-end marking. TAPI uses end-to-end marking at the TSPI level to disambiguate one TSPI_lineGenerateDigitsrequest from another.

Requirements

Header tapicomn.h
Library coredll.lib
Windows Embedded CE Windows CE 3.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also