TSPI_lineSetMediaControl函式 (tspi.h)

發行項
03/13/2024

TSPI_lineSetMediaControl函式會在與指定行、位址或呼叫相關聯的媒體數據流上啟用和停用控制動作。媒體控制項動作可以透過偵測指定的數位、媒體類型、自定義音調和呼叫狀態來觸發。新的指定媒體控制項會取代此要求之前，此行、位址或呼叫的所有控制件。

語法

LONG TSPIAPI TSPI_lineSetMediaControl(
  HDRVLINE                          hdLine,
  DWORD                             dwAddressID,
  HDRVCALL                          hdCall,
  DWORD                             dwSelect,
  LPLINEMEDIACONTROLDIGIT const     lpDigitList,
  DWORD                             dwDigitNumEntries,
  LPLINEMEDIACONTROLMEDIA const     lpMediaList,
  DWORD                             dwMediaNumEntries,
  LPLINEMEDIACONTROLTONE const      lpToneList,
  DWORD                             dwToneNumEntries,
  LPLINEMEDIACONTROLCALLSTATE const lpCallStateList,
  DWORD                             dwCallStateNumEntries
);

參數

hdLine

線條的句柄。

dwAddressID

指定開啟行裝置上的位址。位址標識符永久與地址相關聯;標識碼在操作系統升級之間維持不變。呼叫此函式時，TAPI 不會驗證此參數。

hdCall

呼叫的句柄。 hdCall 的呼叫狀態可以是任何狀態。

dwSelect

指定是否要求媒體控件與單一呼叫相關聯、是位址上所有呼叫的預設值，或是一行上所有呼叫的預設值。此參數會使用下列 LINECALLSELECT_常數。

lpDigitList

數位的指標，其中包含要觸發 LINEMEDIACONTROLDIGIT 類型之媒體控制項動作的數位。每次偵測到數位清單中列出的數位時，就會在呼叫的媒體數據流上執行指定的媒體控制項動作。

脈衝模式的有效位數為『0』到『9』。 DTMF 模式的有效位數為 '0' 到 '9'、'A'、'B'、'C'、'D'、'*'、'#'。

dwDigitNumEntries

lpDigitList 中的項目數。呼叫此函式時，TAPI 不會驗證此參數。

lpMediaList

陣列的指標，其類型為 LINEMEDIACONTROLMEDIA 的專案。陣列具有 dwMediaNumEntries 專案。每個專案都包含要監視的媒體類型、媒體類型特定資訊 (例如持續時間) ，以及媒體控件欄位。如果偵測到清單中的媒體類型，則會在呼叫的媒體數據流上執行對應的媒體控件動作。

dwMediaNumEntries

lpMediaList 中的項目數。呼叫此函式時，TAPI 不會驗證此參數。

lpToneList

陣列的指標，其類型為 LINEMEDIACONTROTONE 的專案。陣列具有 dwToneNumEntries 專案。每個專案都包含要監視的音調描述、音調的持續時間，以及媒體控件字段。如果偵測到清單中的音調，則會在呼叫的媒體數據流上執行對應的媒體控件動作。

dwToneNumEntries

lpToneList 中的項目數目。呼叫此函式時，TAPI 不會驗證此參數。

lpCallStateList

數位的指標，其類型為 LINEMEDIACONTROLCALLSTATE 的專案。陣列具有 dwCallStateNumEntries 專案。每個專案都包含呼叫狀態和媒體控制項動作。

dwCallStateNumEntries

lpCallStateList 中的項目數目。呼叫此函式時，TAPI 不會驗證此參數。

傳回值

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

LINEERR_INVALADDRESSID、LINEERR_INVALPOINTER、LINEERR_INVALCALLHANDLE、LINEERR_INVALTONELIST、LINEERR_INVALCALLSELECT、LINEERR_NOMEM、LINEERR_INVALCALLSTATELIST、LINEERR_OPERATIONUNAVAIL、LINEERR_INVALDIGITLIST、LINEERR_OPERATIONFAILED、LINEERR_INVALLINEHANDLE、LINEERR_RESOURCEUNAVAIL、LINEERR_INVALMEDIALIST。

備註

當媒體控件正確起始時，此函式會傳回零 (成功) ，而不是當任何媒體控件生效時。當此函式再次呼叫時，會以不同的參數或 NULL來呼叫時變更或取消媒體控制件。

只有單一媒體控件要求一次可以在呼叫上完成。要求會取代任何可能未完成的要求。

根據服務提供者和其他競爭這類資源的活動而定，可以進行的同時偵測量可能會隨著時間而有所不同。如果服務提供者資源已過度認可，則會傳回LINEERR_RESOURCEUNAVAIL。

服務提供者是否支持媒體控制，是否為 LINEDEVCAPS中所指出的裝置功能。

每次 呼叫TSPI_lineSetMediaControl時 ，新的要求都會覆寫目前作用中的任何媒體控件。如果一或多個參數 lpDigitList、lpMediaList、lpToneList 和 lpCallStateList 為 NULL，則會停用對應的數位、媒體類型、音調或呼叫狀態觸發的媒體控件。若要在保留其餘設定時只修改媒體控件參數的一部分，應用程式應該叫 用TSPI_lineSetMediaControl 為那些必須維持作用中的部分提供先前的參數，以及要修改之元件的新參數。