devicetopology.h (IKsJackDescription 介面)

  • 發行項

IKsJackDescription介面提供有關插孔或內部連接器的資訊，這些連接器提供音訊介面卡上裝置與外部或內部端點 (裝置之間的實體連線，例如麥克風或 CD 播放程式) 。 用戶端會呼叫IPart：：Activate方法，並將參數refiid設定為REFIID IID_IKsJackDescription，以取得元件的IKsJackDescription介面參考。 只有在元件支援IKsJackDescription介面時，IPart：：Activate的呼叫才會成功。 只有代表具有Physical_External或Physical_Internal連線類型的連接器的元件物件將支援這個介面。

大部分的 Windows 音訊介面卡驅動程式都支援 Windows 驅動程式模型 (WDM) ，並使用核心串流 (KS) 屬性來表示連接器中的硬體描述參數， (稱為 KS 針腳) 。 IKsJackDescription介面可讓您方便存取連接器至端點裝置的 KSPROPERTY_JACK_DESCRIPTION 屬性。 如需 KS 屬性和 KS 針腳的詳細資訊，請參閱 Windows DDK 檔。

繼承

IKsJackDescription介面繼承自IUnknown介面。 IKsJackDescription 也有下列類型的成員：

方法

IKsJackDescription介面具有這些方法。

 
IKsJackDescription：：GetJackCount

GetJackCount 方法會取得連線到音訊端點裝置所需的插孔數目。
IKsJackDescription：：GetJackDescription

GetJackDescription 方法會取得音訊插孔的描述。

備註

如果音訊端點裝置支援 IKsJackDescription 介面，Windows 多媒體控制台 Mmsys.cpl 會顯示插孔資訊。 若要檢視插孔資訊，請遵循下列步驟：

  1. 若要執行 Mmsys.cpl，請開啟 [命令提示字元] 視窗，然後輸入下列命令：

    控制項 mmsys.cpl

    或者，您也可以以滑鼠右鍵按一下通知區域中的喇叭圖示，其位於工作列右側，然後選取 [ 播放裝置 ] 或 [ 錄製裝置] 來執行 Mmsys.cpl。

  2. 開啟 [Mmsys.cpl] 視窗之後，請從播放裝置清單或錄製裝置清單中選取裝置，然後按一下 [ 內容]。
  3. 當屬性視窗開啟時，按一下 [ 一般]。 如果選取的屬性頁顯示裝置的插孔資訊，則裝置支援 IKsJackDescription 介面。 如果屬性頁顯示「沒有可用的插孔資訊」文字，則裝置不支援 介面。
下列程式碼範例示範如何取得音訊端點裝置的 IKsJackDescription 介面：
//-----------------------------------------------------------
// Get the IKsJackDescription interface that describes the
// audio jack or jacks that the endpoint device plugs into.
//-----------------------------------------------------------
#define EXIT_ON_ERROR(hres)  \
              if (FAILED(hres)) { goto Exit; }
#define SAFE_RELEASE(punk)  \
              if ((punk) != NULL)  \
                { (punk)->Release(); (punk) = NULL; }

HRESULT GetJackInfo(IMMDevice *pDevice,
                    IKsJackDescription **ppJackDesc)
{
    HRESULT hr = S_OK;
    IDeviceTopology *pDeviceTopology = NULL;
    IConnector *pConnFrom = NULL;
    IConnector *pConnTo = NULL;
    IPart *pPart = NULL;
    IKsJackDescription *pJackDesc = NULL;

    if (NULL != ppJackDesc)
    {
        *ppJackDesc = NULL;
    }
    if (NULL == pDevice || NULL == ppJackDesc)
    {
        return E_POINTER;
    }

    // Get the endpoint device's IDeviceTopology interface.
    hr = pDevice->Activate(__uuidof(IDeviceTopology), CLSCTX_ALL,
                           NULL, (void**)&pDeviceTopology);
    EXIT_ON_ERROR(hr)

    // The device topology for an endpoint device always
    // contains just one connector (connector number 0).
    hr = pDeviceTopology->GetConnector(0, &pConnFrom);
    EXIT_ON_ERROR(hr)

    // Step across the connection to the jack on the adapter.
    hr = pConnFrom->GetConnectedTo(&pConnTo);
    if (HRESULT_FROM_WIN32(ERROR_PATH_NOT_FOUND) == hr)
    {
        // The adapter device is not currently active.
        hr = E_NOINTERFACE;
    }
    EXIT_ON_ERROR(hr)

    // Get the connector's IPart interface.
    hr = pConnTo->QueryInterface(__uuidof(IPart), (void**)&pPart);
    EXIT_ON_ERROR(hr)

    // Activate the connector's IKsJackDescription interface.
    hr = pPart->Activate(CLSCTX_INPROC_SERVER,
                         __uuidof(IKsJackDescription), (void**)&pJackDesc);
    EXIT_ON_ERROR(hr)

    *ppJackDesc = pJackDesc;

Exit:
    SAFE_RELEASE(pDeviceTopology)
    SAFE_RELEASE(pConnFrom)
    SAFE_RELEASE(pConnTo)
    SAFE_RELEASE(pPart)
    return hr;
}

在上述程式碼範例中，GetJackInfo 函式會採用兩個參數。 輸入參數 pDevice 指向端點裝置的 IMMDevice 介面。 輸出參數 ppJackDesc 指向指標值，如果介面存在，函式會寫入對應 IKsJackDescription 介面的位址。 如果介面不存在，函式會將 Null 寫入 *ppJackDesc ，並傳回錯誤碼E_NOINTERFACE。

在上述程式碼範例中， IMMDevice：：Activate 的呼叫會擷取端點裝置的 IDeviceTopology 介面。 端點裝置的裝置拓撲包含連接到介面卡裝置的單一連接器 (連接器號碼 0) 。 在此連線的另一端，介面卡裝置上的連接器代表端點裝置所插入的音訊插孔或插接器。 呼叫 IDeviceTopology：：GetConnector 方法會擷取端點裝置上連接器的 IConnector 介面，而 IConnector：：GetConnectedTo 方法呼叫會擷取配接器裝置上的對應連接器。 最後， IConnector：：QueryInterface 方法呼叫會擷取介面卡裝置連接器的 IPart 介面，而 IPart：：Activate 方法呼叫會擷取連接器的 IKsJackDescription 介面，如果有的話。

需求

   
最低支援的用戶端 Windows Vista [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2008 [僅限傳統型應用程式]
目標平台 Windows
標頭 devicetopology.h

另請參閱

核心音訊介面

DeviceTopology API

IPart：：Activate