lineGenerateDigits 函式 (tapi.h)

發行項
03/05/2024

lineGenerateDigits 函式會使用指定的訊號模式，在指定的呼叫上起始指定的數位產生為帶式音調。使用 lpszDigits 的 NULL 值呼叫此函式會中止目前正在產生的任何數位。叫用 lineGenerateDigits 或 lineGenerateTone ，而數位產生正在進行中會中止目前的數位產生或音調產生，並起始最近指定數位或音調的產生。

語法

LONG lineGenerateDigits(
  HCALL  hCall,
  DWORD  dwDigitMode,
  LPCSTR lpszDigits,
  DWORD  dwDuration
);

參數

hCall

呼叫的句柄。應用程式必須是呼叫的擁有者。 hCall 的呼叫狀態可以是任何狀態。 TAPI 不會強制執行任何呼叫端需求，不過某些 Tapi 服務提供者可能會要求 hCall 處於LINECALLSTATE_CONNECTED狀態。

dwDigitMode

用於發出這些數位訊號的格式。請注意 ，dwDigitMode 只能設定單一旗標。此參數使用其中一個 LINEDIGITMODE_常數。

lpszDigits

包含要產生之數位之 Null 終止字元緩衝區的指標。有效字元是針對 dwDigitModes 中提供的LINEDIGITMODE_常數所指定的字元。

此外，逗號 (，) 也是有效的字元。逗號會在前一個和下一個數位的訊號之間插入額外的延遲。此暫停的持續時間是已定義的設定，而線條裝置功能則表示此持續時間。您可以使用多個逗號來插入較長的暫停。在產生期間會忽略無效的數位，而不是回報為錯誤。

驚嘆號 (！) 是有效的字元。此字元會造成「勾點」作業，如可撥號位址所述。

dwDuration

DTMF 位數和脈衝和 DTMF 位數間距的毫秒數的持續時間。值為 0 會使用預設值。 dwDuration 參數必須位於 LINEDEVCAPS 中 MinDialParams 和 MaxDialParams 所指定的範圍內。如果超出範圍，則實際值會設定為範圍中最接近的值。

傳回值

如果要求成功，則傳回零，如果發生錯誤，則傳回負錯誤號碼。可能的傳回值為：

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

備註

lineGenerateDigits 函式會被視為在成功起始數位產生時成功完成，而不是產生所有數位時。相較於以網路相依方式撥入數位的lineDial，lineGenerateDigits保證在使用脈衝時，使用 DTMF 或 hookswitch 撥號脈衝在語音通道上產生數位為帶狀音調。 lineGenerateDigits 函式通常不適合進行呼叫或撥號。其適用於透過已建立呼叫的端對端訊號。

在 產生 lpszDigits 中的所有數字之後，或在中止或取消數位產生之後，就會將 LINE_GENERATE 訊息傳送至應用程式。

只有一個頻內產生要求 (音調產生或數位產生) 允許在呼叫擁有者的所有應用程式中進行每個呼叫。呼叫上的數位產生會藉由起始另一個數位產生要求或音調產生要求來取消。若要取消目前的數位產生，應用程式可以叫用lineGenerateDigits，併為 lpszDigits 參數指定 NULL。

根據服務提供者和硬體，應用程式可以監視它本身產生的數位。如果不想要，應用程式可以在產生數位時停用數字監視。