INF AddInterface 指令

项目
06/15/2023

可以在 INF DDInstall.Interfaces 部分中指定一个或多个 AddInterface 指令。此指令为导出到更高级别的组件（例如其他驱动程序或应用程序）的设备接口类安装特定于设备的支持。指令通常引用 add-interface-section ，它为设备接口类的特定于设备的实例设置注册表信息。

[DDInstall.Interfaces]
  
AddInterface={InterfaceClassGUID} [,[reference-string] [,[add-interface-section][,flags]]]

导出的设备接口类可以是系统定义的设备接口类之一，例如由内核流式处理定义的设备接口类，也可以是由 INF InterfaceInstall32 节指定的新设备接口类。

项

InterfaceClassGUID
指定标识设备接口类的 GUID 值。这可以表示为形式为 {nnnnnnnnnn nnnn-nnnn nnnn-nn--} 形式的显式 GUID 值，也可以表示为 INF 文件的 Strings 节中定义为“{nnnnnnnn-nnnn-nn-nn-}”的 %strkey% 标记。

有关如何创建 GUID 的详细信息，请参阅在驱动程序中使用 GUID。有关系统定义的接口类 GUIDS，请参阅相应的标头，例如内核流式处理接口 GUID 的 Ks.h 。

reference-string
此可选值与指定接口类的设备特定实例相关联，可以表示为“带引号的字符串”，也可以表示为 INF Strings 节中定义的 %strkey% 标记。

PnP 函数和筛选器驱动程序通常在其 INF 文件中的 AddInterface= 条目中省略此值。引用 字符串 由 swenum 驱动程序用作使用单个接口类的多个实例按需创建的软件设备的占位符。可以在具有两个或多个唯一引用字符串的 INF 条目中指定相同的 InterfaceClassGUID 值。由于 I/O 管理器在打开接口实例名称时将 引用字符串 值作为路径组件传递，因此安装的驱动程序可以区分单个设备的同一类的接口实例。

add-interface-section
引用 INF 文件中其他位置的节的名称。这通常包含 一个 INF AddReg 指令 ，用于设置用于导出驱动程序对此设备接口类的支持的注册表项。有关详细信息，请参阅以下 “备注” 部分。

flag
如果指定，则此项必须为零。

注解

如果指定的 {InterfaceClassGUID} 标识的设备接口类尚未安装，则系统安装代码会在系统中安装该类。安装新类的任何 INF 文件也可能具有 INF InterfaceInstall32 部分。本节包含指定的 {InterfaceClassGUID} 并引用为该类设置特定于接口的安装操作的 interface-install-section 。

若要启用设备接口类的实例供更高级别的组件运行时使用，设备驱动程序必须首先调用 IoRegisterDeviceInterface 来检索要启用的设备接口实例的符号链接名称。通常，PnP 函数或筛选器驱动程序从其 AddDevice 例程发出此调用。若要启用 INF 中预配的设备接口实例，设备驱动程序必须在调用 IoRegisterDeviceInterface 时提供 INF 中指定的 {InterfaceClassGUID} 和引用字符串。然后，驱动程序调用 IoSetDeviceInterfaceState ，以使用 IoRegisterDeviceInterface 返回的符号链接名称启用接口。

INF DDInstall.Interfaces 节中的每个 AddInterface 指令都可以引用 INF 文件中其他位置的 INF 编写器定义的 add-interface-section。 INF 编写器定义的每个节名称在 INF 文件中必须是唯一的，并且必须遵循定义节名称的一般规则。有关这些规则的详细信息，请参阅 INF 文件的一般语法规则。

AddInterface 指令引用的 add-interface-section 具有以下形式：

[add-interface-section]
 
AddReg=add-registry-section[, add-registry-section]...
[AddProperty=add-property-section[, add-property-section] ...]  (Windows Vista and later versions of Windows)
[DelReg=del-registry-section[, del-registry-section] ...]
[DelProperty=del-property-section[, del-property-section] ...]  (Windows Vista and later versions of Windows)
[BitReg=bit-registry-section[,bit-registry-section] ...]
[CopyFiles=@filename | file-list-section[,file-list-section]...]
[DelFiles=file-list-section[,file-list-section]...]
[RenFiles=file-list-section[,file-list-section]...]
[UpdateInis=update-ini-section[, update-ini-section] ...]
[UpdateIniFields=update-inifields-section[, update-inifields-section] ...]
[Ini2Reg=ini-to-registry-section[, ini-to-registry-section] ...]

从 Windows Vista 开始，可以通过在 add-interface 节中包含 INF AddProperty 指令 来设置设备接口属性。还可以通过在 add-interface 节中包含 INF DelProperty 指令来删除设备接口属性。但是，应仅使用 AddProperty 或 DelProperty 指令来修改 Windows Vista 或更高版本的 Windows 操作系统中新增的设备接口属性。对于在 Windows Server 2003、Windows XP 或 Windows 2000 上引入且具有相应注册表项的设备接口属性，应继续使用 INF AddReg 指令 和 INF DelReg 指令 来设置和删除设备接口属性。这些准则适用于系统定义的属性和自定义属性。有关如何使用 AddProperty 指令和 DelProperty 指令的详细信息，请参阅使用 INF AddProperty 指令和 INF DelProperty 指令。

通常， add-interface-section 仅包含 一个 INF AddReg 指令 ，该指令又引用单个 add-registry-section。 add-registry-section 用于在注册表中存储有关设备驱动程序支持的接口的信息，供更高级别的驱动程序和应用程序后续使用。

add-interface-section 中引用的 add-registry-section 特定于设备、驱动程序和接口的实例。它可能有一个值条目，用于定义导出的设备接口实例的友好名称，以便更高级别的组件可以在用户界面中按其友好名称来引用该接口。

此类 add-registry-section 中指定的 HKR 指定设备接口的运行时可访问状态注册表项。驱动程序可以通过调用 IoOpenDeviceInterfaceRegistryKey 来检索状态注册表项的 HANDLE，在运行时访问存储在此注册表项中的状态。用户模式组件可以通过调用 CM_Open_Device_Interface_Key 来查询状态。

示例

此示例演示 DDInstall 的一些扩展。支持系统定义的内核流式处理接口的特定音频设备的接口部分。

; ...
[ESS6881.Device.Interfaces]
AddInterface=%KSCATEGORY_AUDIO%,%KSNAME_Wave%,ESSAud.Interface.Wave
AddInterface=%KSCATEGORY_RENDER%,%KSNAME_Wave%,ESSAud.Interface.Wave
AddInterface=%KSCATEGORY_CAPTURE%,%KSNAME_Wave%,ESSAud.Interface.Wave
AddInterface=%KSCATEGORY_AUDIO%,%KSNAME_UART%,WDM.Interface.UART
AddInterface=%KSCATEGORY_RENDER%,%KSNAME_UART%,WDM.Interface.UART
AddInterface=%KSCATEGORY_CAPTURE%,%KSNAME_UART%,WDM.Interface.UART

[ESSAud.Interface.Wave]
AddReg=ESSAud.Interface.Wave.AddReg

[ESSAud.Interface.Wave.AddReg]
HKR,,CLSID,,%Proxy.CLSID%
HKR,,FriendlyName,,%ESSAud.Wave.szPname%
; ... 
[WDM.Interface.UART]
AddReg=WDM.Interface.UART.AddReg

[WDM.Interface.UART.AddReg]
HKR,,CLSID,,%Proxy.CLSID%
HKR,,FriendlyName,,%WDM.UART.szPname%
; ...
[Strings]
KSCATEGORY_AUDIO="{6994ad04-93ef-11d0-a3cc-00a0c9223196}"
KSCATEGORY_RENDER="{65e8773e-8f56-11d0-a3b9-00a0c9223196}"
KSCATEGORY_CAPTURE="{65e8773d-8f56-11d0-a3b9-00a0c9223196}"
; ...
KSNAME_WAVE="Wave"
KSNAME_UART="UART"
; ...
Proxy.CLSID="{17cca71b-ecd7-11d0-b908-00a0c9223196}"
; ... 
ESSAud.Wave.szPname="ESS AudioDrive" 
; ...