lineGatherDigits 函数 (tapi.h)

项目
08/26/2023

lineGatherDigits 函数在指定调用中启动数字的缓冲收集。应用程序指定要在其中放置数字和要收集的最大位数的缓冲区。

语法

LONG lineGatherDigits(
  HCALL  hCall,
  DWORD  dwDigitModes,
  LPSTR  lpsDigits,
  DWORD  dwNumDigits,
  LPCSTR lpszTerminationDigits,
  DWORD  dwFirstDigitTimeout,
  DWORD  dwInterDigitTimeout
);

参数

hCall

要收集数字的调用的句柄。应用程序必须是呼叫的所有者。 hCall 的调用状态可以是任何状态。

dwDigitModes

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

lpsDigits

指向缓冲区的指针，其中检测到的数字将存储为文本字符。在收集数字时，可能不会在缓冲区中一次显示一个数字。仅在收到 LINE_GATHERDIGITS 消息后，才应假定缓冲区的内容有效。如果 lpsDigits 为 NULL，则会终止当前正在进行的调用的数字收集，并忽略 dwNumDigits 。否则， 假定 lpsDigits 为 dwNumDigits 数字留出空间。

dwNumDigits

在将LINE_GATHERDIGITS消息发送到应用程序之前要收集的位数。当 lpsDigits 为 NULL 时，将忽略 dwNumDigits 参数。如果 dwNumDigits 为零，则此函数失败。

lpszTerminationDigits

以 Null 结尾的终止数字字符串（以文本字符形式表示）。如果检测到字符串中的某个数字，则会将该终止数字追加到缓冲区，数字集合将终止，并将LINE_GATHERDIGITS 消息发送到应用程序。

有效字符的列表依赖于 dwDigitModes 中提供的常量。有关每个可能模式的有效字符的列表，请参阅 LINEDIGITMODE_常量。

如果此指针为 NULL，或者它指向空字符串，则函数的行为就像未提供终止数字一样。

dwFirstDigitTimeout

预计第一个数字的时间持续时间（以毫秒为单位）。如果在此时间范围内未收到第一个数字，则会中止数字集合，并将 LINE_GATHERDIGITS 消息发送到应用程序。缓冲区仅包含 NULL 字符，表示未收到任何数字，并且第一个数字超时终止了数字收集。调用的线路设备功能指定此参数的有效范围或指示不支持超时。

dwInterDigitTimeout

连续数字之间的最大持续时间（以毫秒为单位）。如果在此时间范围内未收到数字，则会中止数字集合，并将LINE_GATHERDIGITS消息发送到应用程序。缓冲区仅包含收集到此点的位数，后跟 NULL 字符，表示交叉超时终止了数字收集。调用的线路设备功能指定此参数的有效范围或指示不支持超时。

返回值

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

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

注解

当已收集请求的位数时，数字集合将终止。在收集指定位数之前检测到的某个数字与 szTerminationDigits 中的数字匹配时，也会终止该数字。检测到的终止数字也会放置在缓冲区中，并返回部分缓冲区。

当其中一个超时过期时，将发生另一种取消数字收集的方法。如果在此时间段内未收到第一个数字， dwFirstDigitTimeout 将过期。如果在该时间段内未从之前检测到的数字收到第二个、第三个、 () 等数字，则 dwInterDigitTimout 将过期，并返回部分缓冲区。

终止数字收集的第四种方法是在收集正在进行时再次调用此函数。旧的收集会话将终止，收集到该点的任何数字将复制到上一次调用此函数提供的缓冲区，并在将LINE_GATHERDIGITS 消息发送到应用程序时传递缓冲区。在不启动另一个数字收集的情况下终止数字收集的机制是调用此函数， lpsDigits 等于 NULL。

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

尽管可以在任何调用状态下调用此函数，但通常只能在调用处于连接状态时收集数字。

LINE_GATHERDIGITS的消息仅发送到发起请求的应用程序。当由于超时或匹配的终止数字而返回部分缓冲区时，或者当请求被调用上的另一 行GatherDigits 请求取消时，也会发送它。在任何给定时间，只有一个集合数字请求在呼叫上处于活动状态，这些应用程序是呼叫的所有者。鉴于操作的异步行为，快速连续发出多个 lineGatherDigits 请求的应用程序可能能够执行此操作，并在以后接收多个LINE_GATHERDIGITS消息。虽然这是不寻常的应用程序行为，但应用程序能够计算这些消息的数量，以允许取消消息与以前的请求匹配。在任何情况下，只应假定最近的请求有效。

注意当应用程序调用将数据写回应用程序内存的任何异步操作时，应用程序必须保持该内存可供写入，直到收到 LINE_REPLY 或 LINE_GATHERDIGITS 消息。

应用程序可以使用 lineMonitorDigits 启用或禁用无缓冲区数字检测。每次以这种方式检测到数字时，都会向应用程序发送 LINE_MONITORDIGITS 消息。可以同时为同一调用启用缓冲和无缓冲数字检测。

在电话会议中收集数字仅适用于 hConfCall，不适用于单个参与呼叫。

如果使用 lineGatherDigits 函数取消之前收集数字的请求，该函数会将收集到该点的任何数字复制到原始函数调用中指定的缓冲区。然后，该函数会将LINE_GATHERDIGITS消息发送到应用程序，而不管第二次调用中的 lpszDigits 参数是指定 NULL 还是其他地址。