Partager via


lineGenerateDigits (Windows CE 5.0)

Send Feedback

This function initiates the generation of the specified digits on the specified call as inband tones using the specified signaling mode. Invoking this function with a NULL value for lpszDigits aborts any digit generation currently in progress. Invoking lineGenerateDigits or lineGenerateTone (function) while digit generation is in progress aborts the current digit generation or tone generation and initiates the generation of the most recently specified digits or tone.

LONG WINAPI lineGenerateDigits(HCALL hCall,DWORD dwDigitMode,LPCWSTR lpszDigits,DWORD dwDuration);

Parameters

  • hCall
    Handle to the call. The application must be an owner of the call. Call state of hCall can be any state.

  • dwDigitMode
    Format to be used for signaling these digits. Note that dwDigitMode is allowed to have only a single flag set. This parameter uses one of the LINEDIGITMODE constants.

  • lpszDigits
    Pointer to a null-terminated character buffer that contains the digits to be generated. Valid characters are those specified for the LINEDIGITMODE constants provided in dwDigitModes.

    In addition, ',' (comma) is also a valid character. 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, and 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 errors.

    '!' (exclamation) is a valid character. This character causes a hookflash operation, as described for dialable addresses.

  • dwDuration
    Duration, in milliseconds, of DTMF digits and pulse and DTMF inter-digit spacing. A value of zero uses a default value. The dwDuration parameter must be within the range specified by MinDialParams and MaxDialParams in the LINEDEVCAPS structure. If out of range, the actual value is set to the nearest value in the range.

Return Values

Returns zero if the request succeeds or a negative 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_NOTOWNER The application is not the owner of this call.
LINEERR_INVALCALLSTATE The call state is invalid.
LINEERR_OPERATIONUNAVAIL The operation is invalid.
LINEERR_INVALDIGITMODE The digit mode is invalid.
LINEERR_OPERATIONFAILED The operation failed.
LINEERR_INVALPOINTER The pointer is invalid.
LINEERR_RESOURCEUNAVAIL The resources are unavailable.
LINEERR_NOMEM Not enough memory is available.
LINEERR_UNINITIALIZED A parameter is uninitialized.

Remarks

The lineGenerateDigits function is considered to have completed successfully when the digit generation has been successfully initiated, not when all digits have been generated. In contrast to the lineDial function, which dials digits in a network-dependent fashion, lineGenerateDigits guarantees to produce the digits as inband tones over the voice channel using DTMF or hookswitch dial pulses when using pulse. The lineGenerateDigits function is generally not suitable for making calls or dialing. It is intended for end-to-end signaling over an established call.

After all digits in lpszDigits have been generated, or after digit generation has been aborted or canceled, a LINE_GENERATE message is sent to the application.

Only one inband generation request (tone generation or digit generation) is allowed to be in progress per call across all applications that are owners of the call. Digit generation on a call is canceled by initiating either another digit generation request or a tone generation request. To cancel the current digit generation, the application can invoke lineGenerateDigits and specify NULL for the lpszDigits parameter.

Depending on the service provider and hardware, the application can monitor the digits it generates itself. If that is not desired, the application can disable digit monitoring while generating digits.

Note   This function is for TAPI version 2.0 and later.

Requirements

OS Versions: Windows CE 1.0 and later.
Header: Tapi.h.
Link Library: Coredll.lib.

See Also

lineGenerateTone (function) | lineDial | LINEDEVCAPS

Send Feedback on this topic to the authors

Feedback FAQs

© 2006 Microsoft Corporation. All rights reserved.