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 或用户模式。
应用程序和其他系统组件只能打开已启用的接口。
函数或筛选器驱动程序通常会调用此例程,“启用” 设置为 TRUE 后,它成功启动设备以响应 IRP_MN_START_DEVICE IRP。 此类驱动程序应禁用设备接口实例(即 调用 ioSetDeviceInterfaceState,并在删除设备以响应 IRP_MN_REMOVE_DEVICE IRP 或 IRP_MN_SURPRISE_REMOVAL IRP 时将 启用 设置为 FALSE)。 如果驱动程序在处理这些删除 IRP 时未禁用设备接口,驱动程序不应随后尝试这样做,因为当 PnP 管理器删除设备时,PnP 管理器将禁用该接口。
如果设备突然删除(例如,意外删除),但仍具有有效的设备接口实例,则在重新附加设备时会出现问题。 当 PnP 管理器枚举新附加的设备并启用设备接口实例时,会出现此问题,该实例将存在于与现有设备接口实例相同的注册表路径中。
请注意,如果驱动程序调用 IoSetDeviceInterfaceState 来禁用设备接口实例以响应 IRP_MN_SURPRISE_REMOVAL IRP,驱动程序不得尝试禁用同一设备接口实例以响应 IRP_MN_REMOVE_DEVICE IRP。
如果调用 IoSetDeviceInterfaceState 成功公开设备接口实例,系统将通知注册了设备类 PnP 通知的任何组件更改。 同样,如果调用此例程会禁用现有设备接口实例,系统会发送相应的通知。
在 IRP_MN_START_DEVICE IRP 完成之前,PnP 管理器不会发送接口实例到达的通知,指示设备的所有驱动程序都已完成其启动作。 此外,PnP 管理器在 IRP_MN_START_DEVICE IRP 完成之前,将失败为设备创建请求。
IoSetDeviceInterfaceState 的调用方必须在系统线程的上下文中运行 IRQL = PASSIVE_LEVEL。
要求 | 价值 |
---|---|
最低支持的客户端 | 从 Windows 2000 开始可用。 |
目标平台 | 普遍 |
标头 | wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h) |
库 | NtosKrnl.lib |
DLL | NtosKrnl.exe |
IRQL | PASSIVE_LEVEL(请参阅“备注”部分) |
DDI 符合性规则 | HwStorPortProhibitedDIs(storport)、IrqlIoPassive1(wdm)、LowerDriverReturn(wdm)、PowerIrpDDis(wdm) |