lineGatherDigitsA 函数 （tapi.h）
lineGatherDigits 函数在指定调用中启动数字的缓冲收集。 应用程序指定要在其中放置数字和要收集的最大位数的缓冲区。
LONG lineGatherDigitsA(
HCALL hCall,
DWORD dwDigitModes,
LPSTR lpsDigits,
DWORD dwNumDigits,
LPCSTR lpszTerminationDigits,
DWORD dwFirstDigitTimeout,
DWORD dwInterDigitTimeout
);
hCall
要收集数字的调用的句柄。 应用程序必须是调用的所有者。 hCall 的调用状态可以是任何状态。
dwDigitModes
要监视的数字模式。 此参数使用一个或多个 LINEDIGITMODE_ 常量。
lpsDigits
指向将检测到的数字存储为文本字符的缓冲区的指针。 在收集数字时，一次可能不会在缓冲区中显示一个数字。 只有在收到 LINE_GATHERDIGITS 消息后，才会假定缓冲区的内容有效。 如果 lpsDigitsNULL，则调用中当前正在进行的数字收集将终止，并忽略 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 字符，指示 interdigit 超时终止数字收集。 调用的线路设备功能指定此参数的有效范围或指示不支持超时。
如果请求成功，则返回零;如果发生错误，则返回负错误号。 可能的返回值为：
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仅发送到启动请求的应用程序。 当由于超时或匹配的终止位数而返回部分缓冲区，或者在调用时由另一个 lineGatherDigits 取消请求时，也会发送该缓冲区。 在任何给定时间，只有一个收集数字请求可以在呼叫中处于活动状态，这些应用程序都是呼叫所有者。 鉴于操作的异步行为，在快速连续发出多个 lineGatherDigits 请求的应用程序可能能够执行此操作，并在以后接收多个LINE_GATHERDIGITS消息。 虽然这将是不寻常的应用程序行为，但应用程序能够计算这些消息的数量，以允许取消消息与前面的请求匹配。 在任何情况下，只应假定最新的请求有效。
电话会议中的数字收集仅适用于 hConfCall，不适用于单个参与呼叫。
如果使用 lineGatherDigits 函数取消以前的收集数字请求，该函数会将收集到该点的任何数字复制到原始函数调用中指定的缓冲区。 然后，该函数会将LINE_GATHERDIGITS消息发送到应用程序，无论第二次调用中的 lpszDigits 参数是否指定 NULL 或不同的地址。
备注
tapi.h 标头将 lineGatherDigits 定义为一个别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将中性编码别名与不中性编码的代码混合使用可能会导致编译或运行时错误不匹配。 有关详细信息，请参阅函数原型的
| 要求 | 价值 |
|---|---|
| 目标平台 | 窗户 |
| 标头 | tapi.h |
| 库 | Tapi32.lib |
| DLL | Tapi32.dll |