音频终结点设备的友好名称

  • 项目

在 Windows Vista、Windows Server 2008 和更高版本的 Windows 中，音频子系统支持音频终结点设备的概念，例如扬声器、耳机、麦克风和 CD 播放器。 此音频终结点概念有助于创建用户友好的音频应用程序，这些应用程序具有引用用户直接操作的终结点设备的用户界面。 这些终结点具有友好名称，例如“扬声器”、“耳机”、“麦克风”和“CD 播放器”，应用程序可以在其用户界面中显示这些名称。 有关终结点设备的详细信息，请参阅音频终结点设备。

音频子系统将音频适配器上的即插即用 (PnP) 设备建模为 KS 筛选器。 数据流通过 KS 引脚进入和退出筛选器。 桥接引脚是一个 KS 引脚，音频终结点设备通过它连接到 KS 筛选器。 有关桥接引脚的详细信息，请参阅音频筛选器图。

音频子系统通过检查终结点设备连接到的桥接引脚的属性来获取有关音频终结点设备的信息。 其中一个此类属性是引脚类别属性 (KSPROPERTY_PIN_CATEGORY)。

对于每个 KS 筛选器，适配器驱动程序会提供一个 PCPIN_DESCRIPTOR 结构表，用于描述筛选器上 KS 引脚的属性。 引脚类别 GUID 存储在 PCPIN_DESCRIPTOR 结构的 KsPinDescriptor.Category 成员中。 对于桥接引脚，引脚类别 GUID 的值指示连接到桥接引脚的终结点的类型。 例如，引脚类别 GUID KSNODETYPE_MICROPHONE 会指示桥接引脚连接到麦克风，GUID KSNODETYPE_SPEAKER 会指示桥接引脚连接到扬声器等。 KSNODETYPE_XXX GUID 在 Ksmedia.h 头文件中定义。

此外，PCPIN_DESCRIPTOR 还包含可用于通过唯一名称标识引脚的 GUID。 此引脚名称 GUID 存储在 PCPIN_DESCRIPTOR 结构的 KsPinDescriptor.Name 成员中。 此名称 GUID 由 (KSPROPERTY_PIN_NAME) 属性用来将注册表中找到的友好名称与引脚相关联。

音频子系统会调用 KSPROPERTY_PIN_NAME 属性以将友好名称与音频终结点相关联。 KS 通过首先在描述 KsPinDescriptor.Name GUID 的注册表中搜索 unicode 字符串来处理此请求。 如果 KS 找不到条目，它会在注册表中搜索描述 KsPinDescriptor.Category GUID 的 unicode 字符串。

从 Windows 10 2018 年 10 月更新版本 1809 开始，在搜索注册表时，KS 会首先查找设备软件密钥中的条目。 这是由 INF 通过设备驱动程序 INF 的 [Models] 节引用的 AddReg 节创建的。 AddReg 节使用 HKR\MediaCategories 项构造这些条目。 这允许驱动程序开发人员为名称和类别 GUID 创建特定于设备的友好名称，无论 GUID 对设备是否唯一。

如果设备的软件密钥中未安装某个条目，或者驱动程序在 Windows 10 版本 1809 之前的操作系统上运行，KS 会检查 MediaCategories 注册表项。 第二个项被视为全局命名空间。 从 Windows 10 版本 1809 开始，此空间是为全局定义保留的，不应由新驱动程序修改。 将来的 OS 版本不支持修改此项下的条目。

公开具有标准类别 GUID 的引脚的音频设备应包括/需要设备 INF 中的收件箱 KS.INF 或 KSCAPTUR.INF 名称注册。 这些收件箱 INF 包含驱动程序可能希望填充的预定义类别 GUID 的默认友好名称定义。 这些 GUID 位于 PCPIN_DESCRIPTOR 结构的 KsPinDescriptor.Category 成员中。 例如，类别 GUID KSNODETYPE_MICROPHONE 条目具有关联的友好名称“麦克风”，类别 GUID KSNODETYPE_SPEAKER 条目具有关联的友好名称“扬声器”，依此类推。

类别和名称 GUID 的 GUID 和友好名称存储在注册表中。 对于注册表中的每个 GUID 名称对，GUID 字符串用作 MediaCategories 项下的子项。 在 GUID 项下，友好名称为“Name”变量下的 Unicode 字符串值。

如果音频子系统定义的所有友好名称和引脚类别都不能充分描述设备，则可以定义自己的引脚类别和名称 GUID，并将友好名称与 INF 中的友好名称相关联。 若要确保引脚类别 GUID 是唯一的，请使用实用工具（如 Uuidgen.exe）生成 GUID。 接下来，修改安装音频适配器的 INF 文件，以将引脚类别 GUID 和友好名称写入注册表。 下面的代码示例演示了一个 INF 文件的片段，该文件将两个引脚类别 GUID 及其关联的友好名称添加到注册表：

[Manufacturer]
MyOEMName=Unicorn,NTamd64

[Unicorn.NTamd64]
MyDeviceName=MyDevice,Root\MyDevice

[MyDevice.NT]
Include=ks.inf, kscaptur.inf
Needs=KS.Registration, KSCAPTUR.Registration.NT
CopyFiles=MyDevice.CopyFiles
AddReg=PinNameRegistration

...

[PinNameRegistration]
HKR,%MediaCategories%\%GUID.MyNewEndpointCategory%,Name,,%Name.MyNewEndpointCategory%
HKR,%MediaCategories%\%GUID.MyNewEndpointName%,Name,,%Name.MyNewEndpointName%

...

[Strings]
MyOEMName="Unicorns Inc."
MyDeviceName="Sparkly Unicorn"
MediaCategories="MediaCategories"

GUID.MyNewEndpointCategory="{B72FBD1A-4634-4240-B207-0E6B52F3701C}"
GUID.MyNewEndpoint_2="{71DD3A5D-E303-49A0-ACEE-908634AA9520}"

Name.MyNewEndpointCategory="Unicorn"
Name.MyNewEndpointName="Fred the Unicorn"

这两个 GUID 字符串都是由 Uuidgen.exe 生成的。

应用程序可以使用设备的 IPropertyStore 接口访问音频终结点设备的属性。 该接口使用在 Functiondiscoverykeys_devpkey.h 和 Mmdeviceapi.h 头文件中定义的属性键来标识这些属性。 应用程序可以使用 PKEY_Device_FriendlyName 属性键来检索终结点设备的友好名称。 对于空间受限型用户界面，可以使用 PKEY_Device_DeviceDesc 属性键检索更短版本的友好名称。 有关这些属性键的详细信息，请参阅 IMMDevice::OpenPropertyStore。

IPropertyStore 接口实例维护音频终结点设备的持久性属性存储。 属性存储从与注册表中的 KS 引脚类别 GUID 关联的友好名称字符串中复制 PKEY_Device_DeviceDesc 属性键的初始值。 应用程序可以从属性存储中读取 PKEY_Device_DeviceDesc 属性值（名称字符串），但它们无法更改该值。 但是，用户可以使用 Windows 多媒体控制面板 Mmsys.cpl 修改名称。 例如，在 Windows Vista 中，可以使用以下步骤修改呈现终结点设备的名称：

  1. 若要运行 Mmsys.cpl，请打开命令提示符窗口，然后输入以下命令：

    mmsys.cpl

    （或者，可以通过右键单击位于任务栏右侧通知区域中的扬声器图标并单击“播放设备”来运行 Mmsys.cpl。）

  2. 单击呈现设备的名称，然后单击“属性”。

  3. 在“属性”窗口中，单击“常规”选项卡。友好名称应显示在属性表顶部的文本框中。 可以编辑友好名称，然后单击“确定”保存所做的更改。

前面的步骤会更改存储在音频终结点设备的属性存储中的友好名称。 这些步骤不会影响与其他属于同一 KS 引脚类别的音频终结点设备关联的友好名称， 也不会影响任何可能直接向 KS 查询名称的组件。