lineGenerateTone 函数 (tapi.h)

项目
03/04/2024

lineGenerateTone 函数通过指定的调用生成指定的带内音调。如果为 dwToneMode 调用此函数，并为 dwToneMode 调用此函数，则会中止指定调用中当前正在进行的音调生成。在音调生成过程中调用 lineGenerateTone 或 lineGenerateDigits 会中止当前音调生成或数字生成，并启动新指定音调或数字的生成。

语法

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

参数

hCall

要生成音调的调用的句柄。应用程序必须是调用的所有者。 hCall 的调用状态可以是任何状态。

dwToneMode

定义要生成的音调。音调可以是标准音，也可以是自定义音调。自定义音调由一组任意频率组成。预定义了少量标准音。使用 dwDuration 为标准和自定义音指定音调的持续时间。 dwToneMode 参数只能设置一个位。如果未设置位 (值 0 传递到) ，则取消音调生成。此参数使用 LINETONEMODE_常量之一。

dwDuration

应维持音调的持续时间（以毫秒为单位）。对于 dwDuration ，值为 0 使用指定音调的默认持续时间。默认值为：

自定义：音调一直持续到关闭为止，通常是由用户交互或设备超时造成的。

RINGBACK：音调一直持续到关闭为止，通常是用户交互或设备超时。

忙碌：音调一直持续到关闭为止，通常是由用户交互或设备超时造成的。

BEEP：音调一直持续到关闭为止，通常是通过用户交互或设备超时。

计费：修复了单个周期) (。

dwNumTones

lpTones 数组中的条目数。如果 dwToneMode 不等于 CUSTOM，则忽略此参数。

lpTones

指向 LINEGENERATETONE 数组的指针，该数组指定音调的组件。对于标准 LINETONEMODE_常量音（如LINETONEMODE_BUSY），将忽略此参数。如果 lpTones 是多频音调，则同时播放各种音调。

返回值

如果请求成功，则返回零;如果发生错误，则返回负错误号。可能的返回值为：

LINEERR_INVALCALLHANDLE、LINEERR_NOTOWNER、LINEERR_INVALCALLSTATE、LINEERR_OPERATIONUNAVAIL、LINEERR_INVALPOINTER、LINEERR_OPERATIONFAILED、LINEERR_INVALTONEMODE、LINEERR_RESOURCEUNAVAIL、LINEERR_INVALTONE、LINEERR_UNINITIALIZED、LINEERR_NOMEM。

注解

lineGenerateTone 函数被视为在成功启动音调生成时成功完成，而不是在音调生成完成时成功完成。函数允许带内生成多个预定义的音调，例如回响音、繁忙音调和蜂鸣声。它还允许通过指定自定义音调的分量频率、节奏和音量来制造自定义音调。由于这些音调是作为带内音生成的，因此调用通常必须处于连接状态才能有效生成音调。当音调的生成完成或取消音调生成时，会将LINE_GENERATE消息发送到应用程序。

只有一个带内生成请求 (音调生成或数字生成) 在属于呼叫的所有应用程序中进行。这意味着，如果呼叫当前正在进行音调生成，调用 lineGenerateDigits 将取消音调生成。

如果返回LINEERR_INVALPOINTER错误值，则指定的 lpTones 参数无效或 dwNumTones 参数指定的值太大。