TSPI_lineMonitorMedia函式 (tspi.h)

發行項
03/03/2024

TSPI_lineMonitorMedia函式會在指定的呼叫上啟用和停用媒體類型的偵測。偵測到媒體類型時，會將LINE_MONITORMEDIA 訊息傳送至TAPI。

語法

LONG TSPIAPI TSPI_lineMonitorMedia(
  HDRVCALL hdCall,
  DWORD    dwMediaModes
);

參數

hdCall

要設定媒體監視之呼叫的句柄。 hdCall 的呼叫狀態可以是閑置以外的任何狀態。

dwMediaModes

要監視的媒體類型。 dwMediaModes 參數可以有其中一個LINEMEDIAMODE_常數。

值為 0 會取消所有媒體類型監視。

傳回值

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

LINEERR_INVALCALLHANDLE、LINEERR_OPERATIONUNAVAIL、LINEERR_INVALCALLSTATE、LINEERR_OPERATIONFAILED、LINEERR_INVALMEDIAMODE、LINEERR_RESOURCEUNAVAIL、LINEERR_NOMEM。

備註

如果要監視的媒體類型清單包含無效的資訊，服務提供者會傳回LINEERR_INVALMEDIAMODE。

當媒體類型監視已正確起始時，此函式會傳回零 (成功) ，而不是在媒體類型監視終止時傳回。指定媒體類型的媒體監視會維持有效狀態，直到透過將媒體類型設定為零的 dwMediaModes 參數呼叫 TSPI_lineMonitorMedia，或直到呼叫轉換為閑置為止。

TSPI_lineMonitorMedia 主要是事件報告機制。呼叫的媒體類型，如 LINECALLINFO 所示，不會受到服務提供者偵測媒體類型的影響。只有 TAPI 或用戶端應用程式可以使用 TSPI_lineSetMediaMode 來變更呼叫的指示媒體類型。特定媒體類型的實際用法是透過個別媒體數據流 API (發生，例如 Comm 或 WAVE) 。

服務提供者針對新的呼叫外觀所執行的默認媒體監視，會對應至 TSPI_lineSetDefaultMediaDetection所指定之所有媒體類型的聯集。在建立新呼叫之後，TAPI 通常會呼叫 TSPI_lineMonitorMedia ，以減少偵測到的媒體類型集，並回報此呼叫給呼叫之用戶端應用程式所需之所有媒體類型的聯集。

服務提供者必須在呼叫閑置時取消媒體監視。 TAPI 必須計算所有用戶端所需的媒體類型聯集，並將結果傳遞至此函式。服務提供者會使用 TAPI 傳遞至此函式的集合。

雖然此函式可以在任何呼叫狀態中叫用，但呼叫的媒體類型通常只能在呼叫處於特定呼叫狀態時偵測。這些狀態可以是裝置特定狀態。例如，在ISDN中，訊息可以指出媒體數據流存在的媒體類型。同樣地，關於通話的特別響鈴或呼叫標識符資訊可用來識別通話的媒體類型。否則，呼叫可能必須接聽 (處於連線狀態的呼叫) ，以允許服務提供者藉由篩選媒體串流來判斷呼叫的媒體類型。由於呼叫的媒體數據流篩選意指計算額外負荷，因此TAPI通常會使用此程式在不需要時停用媒體監視。

由於 TSPI_lineMonitorMedia 所啟用的媒體模式偵測會實作為呼叫媒體數據流的唯讀作業，因此不會造成干擾。因為設定 TSPI_lineMonitorMedia，所以不會在行上傳送任何訊號。

關於傳遞的媒體類型，TAPI 保證未設定保留位。服務提供者必須在媒體類型上執行任何進一步的有效檢查，例如檢查服務提供者是否確實支援任何媒體類型。