TSPI_lineGatherDigits函式 (tspi.h)
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_常數。
| 值 | 意義 |
|---|---|
|
偵測數位做為使用旋轉脈衝序列結果的可聽聽點數。 脈衝模式的有效位數為 『0』 到 『9』。 |
|
偵測數位為 DTMF 音調。 DTMF 模式的有效位數為 '0' 到 '9'、'A'、'B'、'C'、'D'、'*'、'#'。 |
lpsDigits
緩衝區的指標，其中偵測到的數位會儲存為文字字元。 服務提供者可能會一次在收集數位時，將數位放在緩衝區中，但並非必要專案。 傳送 LINE_GATHERDIGITS 訊息時，緩衝區的內容必須完成。 如果 lpsDigits 指定為 NULL ，則會取消呼叫目前正在進行中的數位收集，並忽略 dwNumDigits 參數。 否則， 假設 lpsDigits 有 dwNumDigits 位數的空間。
dwNumDigits
傳送至 TAPI LINE_GATHERDIGITS訊息之前要收集的位數。 當 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 如果第二個、第三個、第三個、 (等) 位在先前偵測到的數字期間內未收到，則會傳回部分緩衝區。
- 在進行集合時再次呼叫此作業。 舊的集合會話會終止，而且未定義舊緩衝區的內容。 若要取消數位收集而不起始另一個作業，此作業會叫用 lpsDigits 等於 NULL。
當數字緩衝區填滿時，通常會傳送 LINE_GATHERDIGITS 訊息。 當部分緩衝區因為逾時或相符的終止位數而傳回，或在呼叫上透過另一個 TSPI_lineGatherDigits 要求取消要求時，也會傳送它。 一次只能有一個收集數位要求。 呼叫 TSPI_lineGatherDigits 時，服務提供者必須使用LINE_GATHERDIGITS訊息終止任何未完成的收集作業。
當後續呼叫函式) 取消與呼叫 TSPI_lineGatherDigits (函式相關聯的作業時，服務提供者會將收集的任何數位複製到原始呼叫中指定的緩衝區。
TAPI 可以使用 TSPI_lineMonitorDigits 來啟用或停用未緩衝的數位偵測。 每次以這種方式偵測到數位時， 就會將LINE_MONITORDIGITS 訊息傳送至TAPI。 緩衝處理 (收集數位) 和未緩衝的數位偵測都可以同時針對相同的呼叫啟用。
服務提供者允許此函式使用的計時品質有一些變化，包括完全不執行計時。 在 DWGatherDigitsMinTimeout 和 dwGatherDigitsMaxTimeout 成員中，LINEDEVCAPS 回報計時品質。
TAPI 層級的對應函式不包含正式參數 dwEndToEndID。 在該層級，沒有端對端標記。 TAPI 使用 TSPI 層級的端對端標記來區別一個 TSPI_lineGatherDigits 要求與另一個要求。
規格需求
| 需求 | 值 |
|---|---|
| 目標平台 | Windows |
| 標頭 | tspi.h |