TSPI_lineGenerateTone函式 (tspi.h)

發行項
03/03/2024

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

語法

LONG TSPIAPI TSPI_lineGenerateTone(
  HDRVCALL                 hdCall,
  DWORD                    dwEndToEndID,
  DWORD                    dwToneMode,
  DWORD                    dwDuration,
  DWORD                    dwNumTones,
  LPLINEGENERATETONE const lpTones
);

參數

hdCall

服務提供者對要執行音調產生之呼叫的句柄。 hdCall 的呼叫狀態可以是閑置以外的任何狀態。

dwEndToEndID

整個存留期要求的唯一未解譯標識符，也就是直到傳送相符 LINE_GENERATE 訊息為止。服務提供者會將此標識碼包含在訊息中作為其中一個參數。

dwToneMode

定義要產生的音調。音調可以是標準或自定義。自定義音調是由一組任意頻率所組成。預先定義少量的標準音調。音調的持續時間是由標準與自定義音調的 dwDuration 所指定。如果 dwToneMode 設定為零，則會取消任何進行中的數位或音調產生。此參數只會使用其中一個 LINETONEMODE_常數。

dwDuration

持續音調的毫秒數。 dwDuration 的值為 0，會針對指定的音調使用預設持續時間。預設值是：

CUSTOM：無限

RINGBACK：無限

忙碌：無限

BEEP：無限

計費：固定 (單一迴圈)

呼叫此函式時，TAPI 不會驗證此參數。

dwNumTones

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

lpTones

指定音調元件之LINEGENERATETONE 陣列的指標。非自定義音調會忽略此參數。如果 lpTones 是多頻率音調，則會同時播放各種音調。

傳回值

如果函式成功，則傳回零;如果發生錯誤，則傳回錯誤號碼。可能的傳回值如下所示：

LINEERR_INVALCALLHANDLE、LINEERR_NOMEM、LINEERR_INVALCALLSTATE、LINEERR_OPERATIONUNAVAIL、LINEERR_INVALTONEMODE、LINEERR_OPERATIONFAILED、LINEERR_INVALTONE、LINEERR_RESOURCEUNAVAIL LINEERR_RESOURCEUNAVAIL。

備註

TSPI_lineGenerateTone 成功起始音調產生時，傳回零 (成功) ;不是當音調的產生完成時。函式允許產生數個預先定義的音調，例如響鈴、忙碌音調和嗶聲。如果服務提供者支援此功能，它也可藉由指定自定義音調的元件頻率、頻率和音量來允許自定義音調。由於這些音調會以帶式音調產生，因此呼叫通常必須處於連線狀態，音調產生才會生效。當音調產生完成，或取消音調產生時，會將LINE_GENERATE 訊息傳送至TAPI。

注意每個呼叫只能進行一個頻內產生要求 (音調產生或數位產生) 。這表示，如果通話上的音調產生目前正在進行中，則叫用TSPI_lineGenerateDigits 或 TSPI_lineGenerateTone 取消音調產生。當叫用後續的TSPI_lineGenerateDigits 或 TSPI_lineGenerateTone 函式時，服務提供者必須終止任何進行中的音調產生。

TAPI 層級的對應函式不包含正式參數 dwEndToEndID。在該層級，沒有端對端標記。 TAPI 使用 TSPI 層級的端對端標記來區分一個 TSPI_lineGenerateTone 要求。