lineGatherDigits 函式 (tapi.h)

發行項
03/08/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 字元，表示 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 訊息傳送至應用程式時傳遞緩衝區。終止數位收集而不起始另一個數位收集的機制，是叫用等於Null的lpsDigits此函式。

如果數位集合已正確起始，則此函式會被視為成功，而不是數位集合已終止。在傳回部分緩衝區的所有情況下，如果有任何) 後面接著 Null 字元，則有效數字會 (。

雖然此函式可以在任何撥號狀態中叫用，但通常只能在呼叫處於連線狀態時收集數位。

訊息LINE_GATHERDIGITS只會傳送至起始要求的應用程式。當部分緩衝區因為逾時或相符的終止數位而傳回，或在呼叫時由另一個 lineGatherDigits 要求取消要求時，也會傳送它。在任何指定時間，呼叫上只能有一個收集數位要求作用中，這些應用程式都是呼叫的擁有者。假設作業的非同步行為，在快速連續發出多個 lineGatherDigits 要求的應用程式，稍後可能會收到數個LINE_GATHERDIGITS訊息。雖然這會是不尋常的應用程式行為，但應用程式能夠計算這些訊息的數目，以允許取消訊息與先前的要求相符。在任何情況下，應該只假設最新的要求有效。

注意當應用程式叫用任何將資料寫回應用程式記憶體的非同步作業時，應用程式必須保留該記憶體可供寫入，直到收到 LINE_REPLY 或 LINE_GATHERDIGITS 訊息為止。

應用程式可以使用 lineMonitorDigits 來啟用或停用未緩衝的數位偵測。每次以這種方式偵測到數位時，都會將 LINE_MONITORDIGITS 訊息傳送至應用程式。緩衝和未緩衝的數位偵測都可以針對相同的呼叫同時啟用。

會議通話上的數位收集僅適用于 hConfCall，不適用於個別參與通話。

如果使用 lineGatherDigits 函式取消先前收集數位的要求，此函式會將收集到該點的任何數位複製到原始函式呼叫中指定的緩衝區。函式接著會將LINE_GATHERDIGITS訊息傳送至應用程式，不論第二次呼叫中的 lpszDigits 參數是否指定 Null 或不同的位址。