iKsJackDescription 接口 (devicetopology.h)

  • 项目

IKsJackDescription 接口提供有关插孔或内部连接器的信息，这些插孔或内部连接器在音频适配器上的设备与外部或内部终结点设备之间提供物理连接， (例如麦克风或 CD 播放器) 。 客户端通过调用 IPart：：Activate 方法获取对部件的 IKsJackDescription 接口的引用，并将参数 refiid 设置为 REFIID IID_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