lineSetMediaControl 函式 (tapi.h)

發行項
03/02/2024

lineSetMediaControl 函式會在與指定行、位址或呼叫相關聯的媒體數據流上啟用和停用控制動作。媒體控制項動作可以透過偵測指定的數位、媒體類型、自定義音調和呼叫狀態來觸發。

語法

LONG lineSetMediaControl(
  HLINE                             hLine,
  DWORD                             dwAddressID,
  HCALL                             hCall,
  DWORD                             dwSelect,
  LPLINEMEDIACONTROLDIGIT const     lpDigitList,
  DWORD                             dwDigitNumEntries,
  LPLINEMEDIACONTROLMEDIA const     lpMediaList,
  DWORD                             dwMediaNumEntries,
  LPLINEMEDIACONTROLTONE const      lpToneList,
  DWORD                             dwToneNumEntries,
  LPLINEMEDIACONTROLCALLSTATE const lpCallStateList,
  DWORD                             dwCallStateNumEntries
);

參數

hLine

開啟行裝置的句柄。

dwAddressID

指定開啟行裝置上的位址識別碼。位址標識符永久與地址相關聯;標識碼在操作系統升級之間維持不變。

hCall

呼叫的句柄。應用程式必須是呼叫的擁有者。 hCall 的呼叫狀態可以是任何狀態。

dwSelect

要求的媒體控制項是否與單一呼叫相關聯、是位址上所有呼叫的預設值，或是一行上所有呼叫的預設值。此參數一個，而且只有一個 LINECALLSELECT_常數。

lpDigitList

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

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

dwDigitNumEntries

lpDigitList 中的項目數。

lpMediaList

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

dwMediaNumEntries

lpMediaList 中的項目數。

lpToneList

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

dwToneNumEntries

lpToneList 中的項目數。

lpCallStateList

具有 LINEMEDIACONTROLCALLSTATE 類型專案的陣列指標。陣列具有 dwCallStateNumEntries 專案。每個專案都包含呼叫狀態和媒體控制項動作。每當指定的呼叫轉換成清單中的其中一個呼叫狀態時，就會叫用對應的媒體控件動作。

dwCallStateNumEntries

lpCallStateList 中的項目數。

傳回值

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

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

備註

如果媒體控件已正確起始，則 lineSetMediaControl 函式會被視為成功，而不是當任何媒體控件生效時。進行中的媒體控件會變更或取消，方法是再次使用不同的參數或 NULL呼叫此函式。如果一或多個參數 lpDigitList、lpMediaList、lpToneList 和 lpCallStateList 為 NULL，則會停用對應的數位、媒體類型、音調或呼叫狀態觸發媒體控件。若要只修改媒體控件參數的一部分，同時讓其餘設定生效，應用程式應該叫用 lineSetMediaControl，併為那些部分提供先前的參數，這些部分必須維持作用中狀態，以及要修改之元件的新參數。

如果選取 hCall ，且呼叫終止或應用程式解除分配其句柄，則會取消該呼叫上的媒體控件。

所有屬於呼叫擁有者的應用程式，都允許在呼叫上提出媒體控制要求。只有單一媒體控制項要求可以在擁有呼叫的所有應用程式中進行未完成。每次呼叫 lineSetMediaControl 時，新的要求都會覆寫任何媒體控件，然後對呼叫生效，無論是由呼叫應用程式或任何其他擁有的應用程式所設定。

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

服務提供者是否支持媒體控制是裝置功能。