Функция 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 или в пользовательском режиме.

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

Функция или драйвер фильтра обычно вызывает эту подпрограмму с параметром Включить значение TRUE после успешного запуска устройства в ответ на IRP_MN_START_DEVICE IRP. Такой драйвер должен отключить экземпляр интерфейса устройства (то есть вызвать IoSetDeviceInterfaceState и установить для параметра Enableзначение 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 (включая Wdm.h, Ntddk.h, Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (см. раздел "Примечания")
Правила соответствия DDI	HwStorPortProhibitedDIs(storport), IrqlIoPassive1(wdm), LowerDriverReturn(wdm), PowerIrpDDis(wdm)