TSPI_lineGatherDigits函数 (tspi.h)

项目
08/26/2023

TSPI_lineGatherDigits 函数在指定的调用上启动数字的缓冲收集。 TAPI 指定要在其中放置数字和要收集的最大位数的缓冲区。

语法

LONG TSPIAPI TSPI_lineGatherDigits(
  HDRVCALL hdCall,
  DWORD    dwEndToEndID,
  DWORD    dwDigitModes,
  LPWSTR   lpsDigits,
  DWORD    dwNumDigits,
  LPCWSTR  lpszTerminationDigits,
  DWORD    dwFirstDigitTimeout,
  DWORD    dwInterDigitTimeout
);

参数

hdCall

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

dwEndToEndID

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

dwDigitModes

数字模式 (要监视的) 。此参数使用以下一个或多个LINEDIGITMODE_常量。

值	含义
LINEDIGITMODE_PULSE	将数字检测为使用旋转脉冲序列的结果的可听到的点击声。脉冲模式的有效数字为“0”到“9”。
LINEDIGITMODE_DTMF	将数字检测为 DTMF 音调。 DTMF 模式的有效数字为“0”到“9”、“A”、“B”、“C”、“D”、“*”、“#”。

lpsDigits

指向缓冲区的指针，其中检测到的数字将存储为文本字符。在收集数字时，服务提供商可以（但不是必需的）一次在缓冲区中放置一个数字。发送 LINE_GATHERDIGITS 消息时，缓冲区的内容必须完整。如果将 lpsDigits 指定为 NULL ，则取消当前正在调用的数字收集，并忽略 dwNumDigits 参数。否则， 假定 lpsDigits 为 dwNumDigits 数字留出空间。

dwNumDigits

在将LINE_GATHERDIGITS消息发送到 TAPI 之前要收集的位数。当 lpsDigits 为 NULL 时，将忽略 dwNumDigits 参数。如果 dwNumDigits 为零，则此函数必须返回LINEERR_INVALPARAM。

lpszTerminationDigits

指向以 null 结尾的 Unicode 字符串的指针，该字符串的终止数字作为文本字符。如果检测到字符串中的某个数字，则会将该终止数字追加到缓冲区，终止数字集合，并将 LINE_GATHERDIGITS 消息发送到 TAPI。

脉冲模式的有效字符为“0”到“9”。 DTMF 模式的有效字符为“0”到“9”、“A”、“B”、“C”、“D”、“*”、“#”。如果此指针为 NULL，或者它指向空字符串，则该函数的行为就像未提供终止数字一样。

dwFirstDigitTimeout

预期第一个数字的持续时间（以毫秒为单位）。如果在此时间范围内未收到第一个数字，则会终止数字集合，并将LINE_GATHERDIGITS消息发送到 TAPI。将单个 NULL 字符写入缓冲区，指示未收到任何数字，并且第一个数字超时终止了数字收集。呼叫的线路设备功能指定此参数的有效范围，或指示不支持超时。调用此函数时，TAPI 不会验证此参数。

dwInterDigitTimeout

连续数字之间的最长持续时间（以毫秒为单位）。如果在此时间范围内未收到数字，则会终止数字集合，并将 LINE_GATHERDIGITS 消息发送到 TAPI。将单个 NULL 字符写入缓冲区，指示 interdigit 超时终止了数字收集。 LINEDEVCAPS 结构必须指定此参数的有效范围或指示不支持超时。调用此函数时，TAPI 不会验证此参数。

返回值

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

LINEERR_INVALCALLHANDLE、LINEERR_RESOURCEUNAVAIL、LINEERR_INVALCALLSTATE、LINEERR_NOMEM、LINEERR_INVALTIMEOUT、LINEERR_OPERATIONUNAVAIL、LINEERR_INVALDIGITMODE、LINEERR_OPERATIONFAILED、LINEERR_INVALDIGITS、LINEERR_RESOURCEUNAVAIL LINEERR_INVALPARAM。

注解

如果 dwNumDigits 参数无效，则服务提供程序将返回LINEERR_INVALPARAM。

如果正确启动数字集合，此函数返回零 (成功) ;如果数字集合已终止，则不为。在返回部分缓冲区的所有情况下，如果有任何) 后跟 Unicode NULL 字符，则 (有效数字。

可以通过以下方式终止数字集合：

可能已收集请求的位数。
检测到的其中一个数字与收集指定位数之前 szTerminationDigits 中的数字匹配。检测到的终止数字也会放置在缓冲区中，并返回部分缓冲区。
其中一个超时过期。如果在此时间段内未收到第一个数字， dwFirstDigitTimeout 将过期。如果第二个、第三个、 (等) 数字未在该时间段内从之前检测到的数字收到，则 dwInterDigitTimout 将过期，并返回部分缓冲区。
在收集正在进行时再次调用此操作。旧集合会话终止，旧缓冲区的内容未定义。若要取消数字收集而不启动另一个操作，则会使用等于 NULL 的 lpsDigits 调用此操作。

尽管此函数可以在任何调用状态（空闲除外）中调用，但通常只能在调用处于连接状态时收集数字。

LINE_GATHERDIGITS消息通常在填充数字缓冲区时发送。当由于超时或匹配的终止数字而返回部分缓冲区时，或者通过调用上的另一个 TSPI_lineGatherDigits 请求取消请求时，也会发送该请求。一次只能有一个收集数字请求处于活动状态。调用 TSPI_lineGatherDigits时， 服务提供商必须使用LINE_GATHERDIGITS消息终止任何未完成的收集操作。

如果后续调用函数) 取消与 TSPI_lineGatherDigits 函数调用关联的操作 (，则服务提供商会将收集到该点的所有数字复制到原始调用中指定的缓冲区。

TAPI 可以使用 TSPI_lineMonitorDigits 启用或禁用无缓冲区数字检测。每次以这种方式检测到数字时，都会向 TAPI 发送 LINE_MONITORDIGITS 消息。可以同时为同一调用启用缓冲 (收集数字) 和未缓冲的数字检测。

允许服务提供商在用于此函数的计时质量方面有所变化，包括根本不执行计时。计时质量在 LINEDEVCAPS 中报告，成员 dwGatherDigitsMinTimeout 和 dwGatherDigitsMaxTimeout。

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

要求

要求	值
目标平台	Windows
标头	tspi.h

另请参阅

TSPI_lineMonitorDigits

通过

TSPI_lineGatherDigits函数 (tspi.h)

语法

参数

返回值

注解

要求

另请参阅

反馈

其他资源