Platform SDK: TAPI |
The lineGenerateTone 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 );
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).
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.
Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:
LINEERR_INVALCALLHANDLE, LINEERR_NOTOWNER, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALPOINTER, LINEERR_OPERATIONFAILED, LINEERR_INVALTONEMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALTONE, LINEERR_UNINITIALIZED, LINEERR_NOMEM.
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.
Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
Windows 95/98: Requires Windows 95 or later.
Version: Requires TAPI 1.3 or later.
Header: Declared in Tapi.h.
Library: Use Tapi32.lib.
TAPI 2.2 Reference Overview, Supplementary Line Service Functions, LINE_GENERATE, lineGenerateDigits, LINEGENERATETONE