lineGenerateDigits 函数 (tapi.h)

项目
08/26/2023

lineGenerateDigits 函数使用指定的信号模式以带内音的形式在指定调用上启动指定数字的生成。使用 lpszDigits 的 NULL 值调用此函数会中止当前正在进行的任何数字生成。在数字生成过程中调用 lineGenerateDigits 或 lineGenerateTone 会中止当前数字生成或音调生成，并启动最近指定的数字或音调的生成。

语法

LONG lineGenerateDigits(
  HCALL  hCall,
  DWORD  dwDigitMode,
  LPCSTR lpszDigits,
  DWORD  dwDuration
);

参数

hCall

调用的句柄。应用程序必须是调用的所有者。 hCall 的调用状态可以是任何状态。 TAPI 不施加任何调用状态要求，但某些 Tapi 服务提供商可能要求 hCall 处于LINECALLSTATE_CONNECTED状态。

dwDigitMode

用于向这些数字发出信号的格式。请注意， dwDigitMode 只能设置单个标志。此参数使用 LINEDIGITMODE_常量之一。

lpszDigits

指向以 null 结尾的字符缓冲区的指针，该缓冲区包含要生成的数字。有效字符是为 dwDigitModes 中提供的LINEDIGITMODE_常量指定的字符。

此外，逗号 (，) 也是有效的字符。逗号在它分隔的上一个数字和下一个数字的信号之间注入额外的延迟。此暂停的持续时间由配置定义，线路设备功能指示此持续时间。多个逗号可用于注入更长的暂停。在生成过程中，将忽略无效数字，而不是被报告为错误。

感叹号 (！) 是有效的字符。此字符会导致“hookflash”操作，如可拨号地址所述。

dwDuration

DTMF 数字和脉冲和 DTMF 数字间间距的持续时间（以毫秒为单位）。值 0 使用默认值。 dwDuration 参数必须在 LINEDEVCAPS 中的 MinDialParams 和 MaxDialParams 指定的范围内。如果范围外，实际值将设置为区域中最接近的值。

返回值

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

LINEERR_INVALCALLHANDLE、LINEERR_NOTOWNER、LINEERR_INVALCALLSTATE、LINEERR_OPERATIONUNAVAIL、LINEERR_INVALDIGITMODE、LINEERR_OPERATIONFAILED、LINEERR_INVALPOINTER、LINEERR_RESOURCEUNAVAIL、LINEERR_NOMEM、LINEERR_UNINITIALIZED。

注解

当成功启动数字生成时，将 lineGenerateDigits 函数视为已成功完成，而不是在生成所有数字时成功完成。与 lineDial（它以依赖于网络的方式拨号数字）不同， lineGenerateDigits 保证在使用脉冲时，使用 DTMF 或挂钩开关拨号脉冲，在语音通道上生成数字作为带内音调。 lineGenerateDigits 函数通常不适合进行呼叫或拨号。它用于通过已建立的调用进行端到端的信号传送。

生成 lpszDigits 中的所有数字后，或者在中止或取消数字生成后，会将LINE_GENERATE 消息发送到应用程序。

只有一个带内生成请求 (音调生成或数字生成) 在属于呼叫的所有应用程序中进行。通过发起另一个数字生成请求或音调生成请求，取消呼叫上的数字生成。若要取消当前数字生成，应用程序可以调用 lineGenerateDigits 并为 lpszDigits 参数指定 NULL。

根据服务提供商和硬件的不同，应用程序可以监视它自己生成的数字。如果不需要，应用程序可以在生成数字时禁用数字监视。