Share via


lineGenerateTone

This function generates the specified inband tone over the specified call. Invoking this function with a zero for dwToneMode aborts the tone generation currently in progress on the specified call. Invoking lineGenerateTone or lineGenerateDigits while tone generation is in progress aborts the current tone generation or digit generation and initiates the generation of the newly specified tone or digits.

LONG WINAPI lineGenerateTone(
  HCALL hCall,
  DWORD dwToneMode,
  DWORD dwDuration,
  DWORD dwNumTones,
  LPLINEGENERATETONE const lpTones 
);

Parameters

  • hCall
    Handle to the call on which a tone is to be generated. The application must be an owner of the call. The call state of hCall can be any state.
  • dwToneMode
    Tone to be generated. Tones can be either standard or custom. A custom tone is composed of a set of arbitrary frequencies. A small number of standard tones are predefined. The duration of the tone is specified with the dwDuration parameter for both standard and custom tones. The dwToneMode parameter can only have one bit set. If no bits are set (the value zero is passed), tone generation is canceled. This parameter uses one of the LINETONEMODE constants.
  • dwDuration
    Duration, in milliseconds, during which the tone should be sustained. A value of zero for dwDuration uses a default duration for the specified tone. The following table shows the default values.
    Value Description
    CUSTOM The tone is sustained until it is shut off, usually by user interaction or an equipment time-out.
    RINGBACK The tone is sustained until it is shut off, usually by user interaction or an equipment time-out.
    BUSY The tone is sustained until it is shut off, usually by user interaction or an equipment time-out.
    BEEP The tone is sustained until it is shut off, usually by user interaction or an equipment time-out.
    BILLING Fixed (single cycle).
  • dwNumTones
    The number of entries in the lpTones array. This parameter is ignored if dwToneMode is not equal to CUSTOM.
  • lpTones
    A pointer to a LINEGENERATETONE array that specifies the tone's components. This parameter is ignored for standard LINETONEMODE constants tones such as LINETONEMODE_BUSY. If lpTones is a multifrequency tone, the various tones are played simultaneously.

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 unavailable.
LINEERR_INVALPOINTER The pointer is invalid or the value specified by the dwNumTones parameter is too large.
LINEERR_OPERATIONFAILED The operation failed.
LINEERR_INVALTONEMODE The tone mode is invalid.
LINEERR_RESOURCEUNAVAIL The resources are unavailable.
LINEERR_INVALTONE The tone is invalid.
LINEERR_UNINITIALIZED A parameter is uninitialized.
LINEERR_NOMEM Not enough memory is available.

Remarks

The lineGenerateTone function is considered to have completed successfully when the tone generation has been successfully initiated, not when the generation of the tone is finished. The function allows the inband generation of several predefined tones, such as ringback, busy tones, and beep. It also allows for the fabrication of custom tones by specifying their component frequencies, cadence, and volume. Because these tones are generated as inband tones, the call would typically have to be in the connected state for tone generation to be effective. When the generation of the tone is complete, or when tone generation is 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. This implies that if tone generation is currently in progress on a call, invoking lineGenerateDigits cancels the tone generation.

If the LINEERR_INVALPOINTER error value is returned, the specified lpTones parameter is invalid or the value specified by the dwNumTones parameter is too large.

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

lineGenerateDigits

 Last updated on Saturday, April 10, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.