TSPI_lineGenerateTone函数 (tspi.h)

项目
03/13/2024

TSPI_lineGenerateTone函数通过指定的调用生成指定的音带内。如果为 dwToneMode 调用此函数，且为 dwToneMode ，则会中止指定调用中当前正在进行的任何音调生成。在音调生成过程中调用 TSPI_lineGenerateTone 或 TSPI_lineGenerateDigits 会中止正在进行的当前音调生成或数字生成，并启动新指定的一个或多个数字的生成。

语法

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

参数

hdCall

要对其执行音调生成的调用的服务提供商句柄。 hdCall 的调用状态可以是除空闲之外的任何状态。

dwEndToEndID

请求的整个生命周期（即，直到发送匹配LINE_GENERATE消息）的唯一未解释标识符。服务提供商将此标识符作为消息中的参数之一包含在内。

dwToneMode

定义要生成的音调。音调可以是标准音，也可以是自定义音调。自定义音调由一组任意频率组成。预定义了少量标准音。音调的持续时间由标准音和自定义音的 dwDuration 指定。如果 dwToneMode 设置为零，则会取消正在进行的任何数字或音调生成。此参数使用一个且只使用一个 LINETONEMODE_常量。

dwDuration

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

自定义：无限

RINGBACK：无限

BUSY： infinite

BEEP：无限

计费：固定 (单个周期)

调用此函数时，TAPI 不会验证此参数。

dwNumTones

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

lpTones

指向 LINEGENERATETONE 数组的指针，该数组指定音调的组件。对于不自定义的音调，将忽略此参数。如果 lpTones 是多频音调，则同时播放各种音调。

返回值

如果函数成功，则返回零;如果发生错误，则返回错误号。可能的返回值如下所示：

LINEERR_INVALCALLHANDLE、LINEERR_NOMEM、LINEERR_INVALCALLSTATE、LINEERR_OPERATIONUNAVAIL、LINEERR_INVALTONEMODE、LINEERR_OPERATIONFAILED、LINEERR_INVALTONE、LINEERR_RESOURCEUNAVAIL、LINEERR_RESOURCEUNAVAIL。

注解

成功启动音调生成后，TSPI_lineGenerateTone返回零 (成功) ;不是在生成完音调时。函数允许带内生成多个预定义的音调，例如回响音、繁忙音调和蜂鸣声。如果服务提供商支持，它还允许通过指定自定义音调的组件频率、节奏和音量来制作自定义音。由于这些音调是作为带内音生成的，因此调用通常必须处于连接状态才能有效生成音调。当音调生成完成或取消音调生成时， LINE_GENERATE 消息将发送到 TAPI。

注意每次调用只能进行一个 (音调生成或数字生成) 的带内生成请求。这意味着，如果呼叫当前正在进行音调生成，则调用 TSPI_lineGenerateDigits 或 TSPI_lineGenerateTone 将取消音调生成。当调用后续 TSPI_lineGenerateDigits 或 TSPI_lineGenerateTone 函数时，服务提供商必须终止正在进行的任何音调生成。

TAPI 级别的相应函数不包括形参 dwEndToEndID。在该级别上，没有端到端标记。 TAPI 在 TSPI 级别使用端到端标记来区分一个 TSPI_lineGenerateTone 请求和另一个请求。