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

Syntax 

LONG TSPIAPI TSPI_lineGenerateTone(
  HDRVCALL 
hdCall, 
  DWORD 
dwEndToEndID, 
  DWORD 
dwToneMode, 
  DWORD 
dwDuration, 
  DWORD 
dwNumTones, 
  LPLINEGENERATETONE const 
lpTones 
);

Parameters

hdCall

Service provider's handle to the call on which tone generation is to be performed. The call state of hdCallcan be any state except idle.

dwEndToEndID

Unique, uninterpreted identifier of the request for its entire lifetime, that is, until the matching LINE_GENERATE (TSPI)message is sent. The service provider includes this identifier as one of the parameters in the message.

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 by dwDurationfor both standard and custom tones. If dwToneModeis set to zero, any digit or tone generation in progress is canceled. This parameter uses one and only one of the LINETONEMODEconstants.

dwDuration

Duration, in milliseconds, during which the tone is sustained. A value of zero for dwDurationuses a default duration for the specified tone. The following table shows the default values for this parameter.

Value Description

CUSTOM

Infinite duration

RINGBACK

Infinite duration

BUSY

Infinite duration

BEEP

Infinite duration

BILLING

Fixed (single cycle) duration

This parameter is not validated by TAPI when this function is called.

dwNumTones

Number of entries in the lpTonesarray. This parameter is ignored if dwToneModeis not equal to LINETONEMODE_CUSTOM.

lpTones

Pointer to a LINEGENERATETONE (structure)array that specifies the tone's components. This parameter is ignored for noncustom tones. If lpTonesis a multifrequency tone, the various tones are played simultaneously.

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_INVALTONEMODE

The tone mode is invalid.

LINEERR_OPERATIONFAILED

The operation failed.

LINEERR_INVALTONE

The tone is invalid.

LINEERR_RESOURCEUNAVAIL

The resource is unavailable.

Remarks

TSPI_lineGenerateTonereturns zero (success) when the tone generation is 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, if this is supported by the service provider. 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 tone generation is complete, or when tone generation is 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 tone generation is currently in progress on a call, invoking either TSPI_lineGenerateDigitsor TSPI_ lineGenerateTonecancels the tone generation. The service provider must terminate any tone generation in progress when a subsequent TSPI_ lineGenerateDigitsor TSPI_ lineGenerateTonefunction is invoked.

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 distinguish one TSPI_ lineGenerateTonerequest 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