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.
while tone generation is in progress aborts the current tone generation or
digit generation and initiates the generation of the newly specified tone or
| HCALL hCall,
| DWORD dwToneMode,
| DWORD dwDuration,
| DWORD dwNumTones,
| LPLINEGENERATETONE const lpTones
A 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.
Defines the 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 dwDuration
for both standard and custom tones. Note that dwToneMode
can only have one bit set. If no bits are set (the value 0 is passed), tone
generation is canceled. This parameter uses the following LINETONEMODE_
The tone is a custom tone, defined by the specified frequencies.
The tone to be generated is ring tone. The exact ringback tone is service
The tone is a standard (station) busy tone. The exact busy tone is service
The tone is a beep, as used to announce the beginning of a recording. The
exact beep tone is service provider defined.
The tone is billing information tone such as a credit card prompt tone. The
exact billing tone is service provider defined.
A value of zero for dwToneMode
cancels tone generation.
Duration in milliseconds during which the tone should be sustained. A value of
zero for dwDuration
uses a default duration for the specified tone. Default values are:
BILLING: fixed (single cycle)
The number of entries in the lpTones
array. This field is ignored if dwToneMode
is not equal to CUSTOM.
A pointer to a LINEGENERATETONE
array that specifies the tone's components. This parameter is ignored for
non-custom tones. If lpTones
is a multi-frequency tone, the various tones are played simultaneously.
Returns zero if the request is successful or a negative error number if an
error has occurred. Possible return values are:
LINEERR_INVALCALLHANDLE, LINEERR_NOTOWNER, LINEERR_INVALCALLSTATE,
LINEERR_OPERATIONUNAVAIL, LINEERR_INVALPOINTER, LINEERR_OPERATIONFAILED,
LINEERR_INVALTONEMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALTONE, LINEERR_UNINITIALIZED,
function is considered to have completed successfully when the tone
generation has been successfully initiated, not when the generation of the tone is done.
The function allows the inband generation of several predefined tones, such as
ring back, 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,
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.
- Software for developers
Software for Android Developers
- More information resources
Unix Manual Pages