IoSetDeviceInterfaceState 函数 (wdm.h)

项目
08/08/2023

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的信息状态。可能的错误返回值如下所述。

返回代码	说明
STATUS_OBJECT_NAME_NOT_FOUND	调用方尝试禁用未启用的设备接口。

注解

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)