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 generates the specified inband tone over the specified call. Invoking this function with a zero for dwToneModeaborts the tone generation currently in progress on the specified call. Invoking lineGenerateTone or lineGenerateDigitswhile tone generation is in progress aborts the current tone generation or digit generation and initiates the generation of the newly specified tone or digits.

Syntax 

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 hCallcan 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 dwDurationparameter for both standard and custom tones. The dwToneModeparameter 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 LINETONEMODEconstants.

dwDuration

Duration, in milliseconds, during which the tone should be sustained. A value of zero for dwDurationuses 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 lpTonesarray. This parameter is ignored if dwToneModeis not equal to CUSTOM.

lpTones

A pointer to a LINEGENERATETONE (structure)array that specifies the tone's components. This parameter is ignored for standard LINETONEMODE constants tones such as LINETONEMODE_BUSY. If lpTonesis a multifrequency tone, the various tones are played simultaneously.

Return Value

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 dwNumTonesparameter 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 lineGenerateTonefunction 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 lineGenerateDigitscancels the tone generation.

If the LINEERR_INVALPOINTER error value is returned, the specified lpTonesparameter is invalid or the value specified by the dwNumTonesparameter is too large.

Note:
This function is for TAPI version 2.0 and later.

Requirements

Header tapi.h
Library coredll.lib
Windows Embedded CE Windows CE 1.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also