lineGenerateTone 函式 (tapi.h)

發行項
03/02/2024

lineGenerateTone 函式會透過指定的呼叫產生指定的帶式音調。針對 dwToneMode 叫用此函式時，會中止目前在指定呼叫上進行的音調產生。叫用 lineGenerateTone 或 lineGenerateDigits ，而音調產生正在進行中會中止目前的音調產生或數位產生，並起始新指定音調或數位的產生。

語法

LONG lineGenerateTone(
  HCALL                    hCall,
  DWORD                    dwToneMode,
  DWORD                    dwDuration,
  DWORD                    dwNumTones,
  LPLINEGENERATETONE const lpTones
);

參數

hCall

處理要產生音調的呼叫。應用程式必須是呼叫的擁有者。 hCall 的呼叫狀態可以是任何狀態。

dwToneMode

定義要產生的音調。音調可以是標準或自定義。自定義音調是由一組任意頻率所組成。預先定義少量的標準音調。音調的持續時間是針對標準和自定義音調使用 dwDuration 來指定。 dwToneMode 參數只能設定一個位。如果未設定位 (值 0 會) 傳遞，則會取消音調產生。此參數使用其中一個 LINETONEMODE_常數。

dwDuration

以毫秒為單位的持續時間，其中應該維持音調。 dwDuration 的值為 0，會針對指定的音調使用預設持續時間。預設值是：

自定義：音調會持續到關閉為止，通常是由用戶互動或設備逾時。

RINGBACK：音調會持續到關閉為止，通常是由用戶互動或設備逾時。

忙碌：音調會持續到關閉為止，通常是由用戶互動或設備逾時。

BEEP：音調會持續到關閉為止，通常是由用戶互動或設備逾時。

計費：已修正單一迴圈 () 。

dwNumTones

lpTones 陣列中的項目數。如果 dwToneMode 不等於 CUSTOM，則會忽略此參數。

lpTones

指定音調元件的 LINEGENERATETONE 陣列指標。標準 LINETONEMODE_常數的音調會忽略此參數，例如LINETONEMODE_BUSY。如果 lpTones 是多頻率音調，則會同時播放各種音調。

傳回值

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

LINEERR_INVALCALLHANDLE、LINEERR_NOTOWNER、LINEERR_INVALCALLSTATE、LINEERR_OPERATIONUNAVAIL、LINEERR_INVALPOINTER、LINEERR_OPERATIONFAILED、LINEERR_INVALTONEMODE、LINEERR_RESOURCEUNAVAIL、LINEERR_INVALTONE、LINEERR_UNINITIALIZED、LINEERR_NOMEM。

備註

lineGenerateTone 函式會在音調產生成功起始時順利完成，而不是在音調產生完成時完成。函式允許產生數個預先定義的音調，例如環圈、忙碌音調和 Beep。它也允許藉由指定其元件頻率、頻率和音量來產生自定義音調。由於這些音調產生為帶式音調，因此呼叫通常必須處於連線狀態，音調產生才會生效。當音調的產生完成或音調產生取消時，會將LINE_GENERATE訊息傳送至應用程式。

只有一個頻內產生要求 (音調產生或數位產生) ，才能在呼叫擁有者的所有應用程式中進行每個呼叫。這表示如果通話上的音調產生目前正在進行中，叫用 lineGenerateDigits 會取消音調產生。

如果傳回LINEERR_INVALPOINTER錯誤值，則指定的 lpTones 參數無效，或 dwNumTones 參數指定的值太大。