TSPI_lineMonitorTones函式 (tspi.h)

發行項
03/09/2024

TSPI_lineMonitorTones函式會啟用和停用呼叫上的內帶音偵測。每次偵測到指定的音調時，都會透過 TAPI 將訊息傳送至用戶端應用程式。

語法

LONG TSPIAPI TSPI_lineMonitorTones(
  HDRVCALL                hdCall,
  DWORD                   dwToneListID,
  LPLINEMONITORTONE const lpToneList,
  DWORD                   dwNumEntries
);

參數

hdCall

要執行音調偵測之呼叫的句柄。 hdCall 的呼叫狀態可以是閑置以外的任何狀態。

dwToneListID

這個音調清單的唯一標識符。一次可以處理數個音調清單。服務提供者必須將具有相同 dwToneListID 的任何舊清單取代為新的音調清單。如果 lpToneList 為 NULL，則只會捨棄 具有 dwToneListID 的音調清單。在任何情況下，具有不同 dwToneListID的其他音調清單會保持不變。

lpToneList

要監視的音調清單，類型為 LINEMONITORTONE。此清單中的每個音調都有一個應用程式定義的標記欄位，用來識別清單中的個別音調，以便報告音調偵測。進行中的音調監視會取消或變更，方法是使用 lpToneList 的 NULL 或另一個音調清單呼叫此作業。服務提供者必須將音調清單複製到自己的記憶體以供稍後參考，而不只是將指標保留在應用程式記憶體中。

dwNumEntries

lpToneList 中的項目數。如果 lpToneList 為 NULL，則會忽略 dwNumEntries 參數。呼叫此函式時，TAPI 不會驗證此參數。

傳回值

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

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

備註

當正確起始音調監視時，此函式會傳回零 (成功) ，而不是在音調監視終止時傳回。如同媒體監視，在指定的音調清單上，音調監視會維持有效狀態，直到呼叫具有相同 dwToneListID 的TSPI_lineMonitorTones和另一個音調清單 (或 NULL 音調清單) ，或直到通話轉換為閑置為止。

雖然此函式可以在閑置以外的任何呼叫狀態中叫用，但通常只能在呼叫處於連線狀態時偵測到音調。音調偵測通常需要計算資源。根據服務提供者和其他競爭這類資源的活動而定，可以偵測到的音調數目可能會隨著時間而有所不同。此外，可以取用對等的資源數量來監視單一三頻率音調與三個單一頻率音調。如果資源過度認可，服務提供者會傳回LINEERR_RESOURCEUNAVAIL。

服務提供者會同時監視所有音調清單中的所有音調。偵測到音調時，會使用 LINE_MONITORTONE 訊息個別報告每個音調清單中的相符音調。每個音調報告都包含音調清單標識碼和應用程式特定的標記。某些服務提供者可能無法區分非常接近的音調，因此即使描述不完全完全相同的音調，也可能回報多個相符專案。

注意TSPI_lineMonitorTones 也可用來偵測無聲。無聲會指定為具有所有零頻率的音調。

TAPI 層級的對應函式不包含 dwToneListID 參數。在 TSPI 介面中包含此參數，可讓 TAPI 將所有音調監視清單的聯集從所有應用程式轉送到服務提供者，同時仍保留根據應用程式篩選和轉送音調偵測事件的能力。這可讓服務提供者設計人員有最大的彈性，以判斷它們可以區分非常接近音調的程度，因為TAPI不會假設哪些音調描述相同。