IoSetDeviceInterfaceState 函数 (wdm.h)
IoSetDeviceInterfaceState 例程启用或禁用以前注册的设备接口类的实例。
语法
NTSTATUS IoSetDeviceInterfaceState(
[in] PUNICODE_STRING SymbolicLinkName,
[in] BOOLEAN Enable
);
参数
[in] SymbolicLinkName
指向标识正在启用或禁用的设备接口实例的字符串的指针。 此字符串是从以前调用 IoRegisterDeviceInterface 或 IoGetDeviceInterfaces 获取的。
[in] Enable
TRUE 表示正在启用设备接口。 FALSE 表示正在禁用设备接口。
返回值
如果调用成功，IoSetDeviceInterfaceState 将返回STATUS_SUCCESS。 如果调用方请求启用已启用的设备接口，此例程将返回STATUS_OBJECT_NAME_EXISTS的信息状态。 可能的错误返回值如下所述。
| 返回代码 | 说明 |
|---|---|
|
调用方尝试禁用未启用的设备接口。 |
注解
IoSetDeviceInterfaceState 启用已注册设备接口的实例，供应用程序和其他系统组件使用。 接口类必须以前已注册 到 IoRegisterDeviceInterface 或从用户模式注册。
应用程序和其他系统组件只能打开已启用的接口。
函数或筛选器驱动程序通常在成功启动设备以响应IRP_MN_START_DEVICE IRP 后调用此例程，并将其“启用”设置为 TRUE。 此类驱动程序应禁用设备接口实例 (即调用 IoSetDeviceInterfaceState，并在删除设备以响应IRP_MN_REMOVE_DEVICE IRP 或 IRP_MN_SURPRISE_REMOVAL IRP 时将 Enable 设置为 FALSE) 。 如果驱动程序在处理这些删除 IRP 时未禁用设备接口，则驱动程序随后不应尝试这样做，因为 PnP 管理器将在 PnP 管理器删除设备时禁用该接口。
例如，如果设备突然 (删除，) 意外删除，但仍具有有效的设备接口实例，则重新附加设备时会出现问题。 当 PnP 管理器枚举新附加的设备并启用设备接口实例时，会出现此问题，该实例将与现有设备接口实例位于同一注册表路径中。
请注意，如果驱动程序调用 IoSetDeviceInterfaceState 以禁用设备接口实例以响应 IRP_MN_SURPRISE_REMOVAL IRP，则驱动程序不得尝试禁用相同的设备接口实例以响应 IRP_MN_REMOVE_DEVICE IRP。
如果对 IoSetDeviceInterfaceState 的调用成功公开了设备接口实例，系统会通知注册设备类更改 PnP 通知的任何组件。 同样，如果对此例程的调用禁用了现有设备接口实例，系统会发送相应的通知。
在 IRP_MN_START_DEVICE IRP 完成之前，PnP 管理器不会发送接口实例到达通知，表明设备的所有驱动程序都已完成其启动操作。 此外，在 IRP_MN_START_DEVICE IRP 完成之前，PnP 管理器无法为设备创建请求。
IoSetDeviceInterfaceState 的调用方必须在系统线程上下文中的 IRQL = PASSIVE_LEVEL 运行。
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 | 从 Windows 2000 开始可用。 |
| 目标平台 | 通用 |
| 标头 | wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h） |
| Library | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (请参阅备注部分) |
| DDI 符合性规则 | HwStorPortProhibitedDDI (storport) 、 IrqlIoPassive1 (wdm) 、 LowerDriverReturn (wdm) 、 PowerIrpDDis (wdm) |