Функция IoSetDeviceInterfaceState (wdm.h)

Статья
02/07/2025

подпрограмма 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 или из пользовательского режима.

Приложения и другие системные компоненты могут открывать только включенные интерфейсы.

Функция или драйвер фильтра обычно вызывает эту подпрограмму с Enable set to TRUE после успешного запуска устройства в ответ на IRP_MN_START_DEVICE IRP. Такой драйвер должен отключить экземпляр интерфейса устройства (то есть вызвать IoSetDeviceInterfaceStat e и задать включить значение FALSE) при удалении устройства в ответ на IRP_MN_REMOVE_DEVICE IRP или IRP_MN_SURPRISE_REMOVAL IRP. Если драйвер не отключает интерфейс устройства при обработке этих операций irps, драйвер не должен впоследствии пытаться сделать это, так как диспетчер PnP отключит интерфейс, когда диспетчер PnP удаляет устройство.

Если устройство внезапно удаляется (например, при неожиданном удалении), но по-прежнему имеет допустимый экземпляр интерфейса устройства, проблема будет возникать, если устройство повторно подключено. Эта проблема возникает, когда диспетчер PnP перечисляет только что подключенное устройство и включает экземпляр интерфейса устройства, который будет существовать в том же пути реестра, что и существующий экземпляр интерфейса устройства.

Обратите внимание, что если драйвер вызывает IoSetDeviceInterfaceState, чтобы отключить экземпляр интерфейса устройства в ответ на IRP_MN_SURPRISE_REMOVAL IRP, драйвер не должен пытаться отключить тот же экземпляр интерфейса устройства в ответ на IRP_MN_REMOVE_DEVICE IRP.

Если вызов IoSetDeviceInterfaceState успешно предоставляет экземпляр интерфейса устройства, система уведомляет все компоненты, зарегистрированные для уведомления PnP об изменении класса устройства. Аналогичным образом, если вызов этой подпрограммы отключает существующий экземпляр интерфейса устройства, система отправляет соответствующие уведомления.

Диспетчер PnP не отправляет уведомление о поступлении экземпляра интерфейса до завершения IRP_MN_START_DEVICE IRP, указывая, что все драйверы устройства завершили свои начальные операции. Кроме того, диспетчер PnP завершает создание запросов на устройство до завершения IRP_MN_START_DEVICE IRP.

Вызывающие IoSetDeviceInterfaceState должны выполняться в IRQL = PASSIVE_LEVEL в контексте системного потока.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Доступно начиная с Windows 2000.
целевая платформа	Всеобщий
заголовка	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
библиотеки	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (см. раздел "Примечания")
правил соответствия DDI	HwStorPortProhibitedDDIs(storport), IrqlIoPassive1(wdm), LowerDriverReturn(wdm), PowerIrpDDis(wdm)