IoSetDeviceInterfaceState 函数 (wdm.h)

IoSetDeviceInterfaceState 例程启用或禁用以前注册的设备接口类的实例。

语法

NTSTATUS IoSetDeviceInterfaceState(
  [in] PUNICODE_STRING SymbolicLinkName,
  [in] BOOLEAN         Enable
);

参数

[in] SymbolicLinkName

指向标识正在启用或禁用的设备接口实例的字符串的指针。 此字符串是从上一次调用 IoRegisterDeviceInterfaceIoGetDeviceInterfaces获取的。

[in] Enable

TRUE 指示正在启用设备接口。 FALSE 指示正在禁用设备接口。

返回值

如果调用成功,则 IoSetDeviceInterfaceState 返回STATUS_SUCCESS。 如果调用方请求启用已启用的设备接口,则此例程将返回STATUS_OBJECT_NAME_EXISTS的信息状态。 下面描述了可能的错误返回值。

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

言论

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)

另请参阅

IRP_MN_REMOVE_DEVICE

IRP_MN_START_DEVICE

IRP_MN_SURPRISE_REMOVAL

IoGetDeviceInterfaces

IoRegisterDeviceInterface

IoRegisterPlugPlayNotification