设备属性（核心音频 API）

项目
03/08/2024

在枚举音频终结点设备的过程中，客户端应用程序可以询问终结点对象的设备属性。设备属性在 MMDevice API 的 IPropertyStore 接口实现中公开。给定终结点对象的 IMMDevice 接口引用后，客户端可通过调用 IMMDevice::OpenPropertyStore 方法来获取终结点对象属性存储的引用。

客户端可以读取这些属性，但不应进行设置。属性值以 PROPVARIANT 结构进行存储。

终结点管理器为终结点设置基本设备属性。终结点管理器是负责检测音频终结点设备是否存在的 Windows 组件。

以下列表中的每个 PKEY_Xxx 属性标识符都是 PROPERTYKEY 类型的常量，该常量在头文件 Functiondiscoverykeys_devpkey.h 中定义。所有音频终结点设备都具有这些设备属性。

properties	说明
PKEY_DeviceInterface_FriendlyName	终结点设备所连接的音频适配器的友好名称（例如，“XYZ 音频适配器”）。
PKEY_Device_DeviceDesc	终结点设备的设备说明（例如“扬声器”）。
PKEY_Device_FriendlyName	终结点设备的友好名称（例如，“扬声器（XYZ 音频适配器）”）。
PKEY_Device_InstanceId	存储音频终结点设备实例标识符。也可以通过 IMMDevice::GetId 方法来获取该值。有关此属性的详细信息，请参阅终结点 ID 字符串和 DEVPKEY_Device_InstanceId。
PKEY_Device_ContainerId	存储实现音频终结点的 PnP 设备的容器标识符。有关此属性的详细信息，请参阅 DEVPKEY_Device_ContainerId。

某些音频终结点设备可能还具有未在前面列表中出现的其他属性。有关其他属性的详细信息，请参阅音频终结点属性。

有关 PROPERTYKEY 的详细信息，请参阅 Windows 属性系统文档。

下面的代码示例将打印系统中所有音频呈现终结点设备的显示名称：

//-----------------------------------------------------------
// This function enumerates all active (plugged in) audio
// rendering endpoint devices. It prints the friendly name
// and endpoint ID string of each endpoint device.
//-----------------------------------------------------------
#define EXIT_ON_ERROR(hres)  \
              if (FAILED(hres)) { goto Exit; }
#define SAFE_RELEASE(punk)  \
              if ((punk) != NULL)  \
                { (punk)->Release(); (punk) = NULL; }

const CLSID CLSID_MMDeviceEnumerator = __uuidof(MMDeviceEnumerator);
const IID IID_IMMDeviceEnumerator = __uuidof(IMMDeviceEnumerator);

void PrintEndpointNames()
{
    HRESULT hr = S_OK;
    IMMDeviceEnumerator *pEnumerator = NULL;
    IMMDeviceCollection *pCollection = NULL;
    IMMDevice *pEndpoint = NULL;
    IPropertyStore *pProps = NULL;
    LPWSTR pwszID = NULL;

    hr = CoCreateInstance(
           CLSID_MMDeviceEnumerator, NULL,
           CLSCTX_ALL, IID_IMMDeviceEnumerator,
           (void**)&pEnumerator);
    EXIT_ON_ERROR(hr)

    hr = pEnumerator->EnumAudioEndpoints(
                        eRender, DEVICE_STATE_ACTIVE,
                        &pCollection);
    EXIT_ON_ERROR(hr)

    UINT  count;
    hr = pCollection->GetCount(&count);
    EXIT_ON_ERROR(hr)

    if (count == 0)
    {
        printf("No endpoints found.\n");
    }

    // Each loop prints the name of an endpoint device.
    for (ULONG i = 0; i < count; i++)
    {
        // Get pointer to endpoint number i.
        hr = pCollection->Item(i, &pEndpoint);
        EXIT_ON_ERROR(hr)

        // Get the endpoint ID string.
        hr = pEndpoint->GetId(&pwszID);
        EXIT_ON_ERROR(hr)
        
        hr = pEndpoint->OpenPropertyStore(
                          STGM_READ, &pProps);
        EXIT_ON_ERROR(hr)

        PROPVARIANT varName;
        // Initialize container for property value.
        PropVariantInit(&varName);

        // Get the endpoint's friendly-name property.
        hr = pProps->GetValue(
                       PKEY_Device_FriendlyName, &varName);
        EXIT_ON_ERROR(hr)

        // GetValue succeeds and returns S_OK if PKEY_Device_FriendlyName is not found.
        // In this case vartName.vt is set to VT_EMPTY.      
        if (varName.vt != VT_EMPTY)
        {
            // Print endpoint friendly name and endpoint ID.
            printf("Endpoint %d: \"%S\" (%S)\n", 
                    i, varName.pwszVal, pwszID);
        }

        CoTaskMemFree(pwszID);
        pwszID = NULL;
        PropVariantClear(&varName);
        SAFE_RELEASE(pProps)
        SAFE_RELEASE(pEndpoint)
    }
    SAFE_RELEASE(pEnumerator)
    SAFE_RELEASE(pCollection)
    return;

Exit:
    printf("Error!\n");
    CoTaskMemFree(pwszID);
    SAFE_RELEASE(pEnumerator)
    SAFE_RELEASE(pCollection)
    SAFE_RELEASE(pEndpoint)
    SAFE_RELEASE(pProps)
}

前面的代码示例中的 FAILED 宏在头文件 Winerror.h 中定义。

在前面的代码示例中，PrintEndpointNames 函数中的 for 循环体调用了 IMMDevice::GetId 方法，以获取音频终结点设备的终结点 ID 字符串，该音频终结点设备由 IMMDevice 接口实例表示。相对于系统中的所有其他音频终结点设备，该字符串可唯一标识设备。客户端可以通过调用 IMMDeviceEnumerator::GetDevice 方法，在稍后时间或不同进程中使用终结点 ID 字符串来创建音频终结点设备实例。客户端应将终结点 ID 字符串的内容视为不透明。也就是说，客户端不应尝试解析字符串的内容来获取有关设备的信息。原因是字符串格式并未定义，在不同的 MMDevice API 实现中可能会发生变化。

在前面的代码示例中，通过 PrintEndpointNames 函数获得的友好设备名称和终结点 ID 字符串与 DirectSound 在设备枚举过程中提供的友好设备名称和终结点 ID 字符串完全相同。有关详细信息，请参阅传统音频应用程序的音频事件。

在前面的代码示例中，PrintEndpointNames 函数调用 CoCreateInstance 函数，为系统中的音频终结点设备创建一个枚举器。除非调用程序先前调用了 CoInitialize 或 CoInitializeEx 函数来初始化 COM 库，否则 CoCreateInstance 调用将失败。有关 CoCreateInstance、CoInitialize 和 CoInitializeEx 的详细信息，请参阅 Windows SDK 文档。

有关 IMMDeviceEnumerator、IMMDeviceCollection 和 IMMDevice 接口的更多信息，请参阅 MMDevice API。

设备属性（核心音频 API）

反馈

反馈

其他资源

设备属性（核心音频 API）

相关主题

反馈

反馈

其他资源