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

  • Статья

Подпрограмма IoReportTargetDeviceChange уведомляет диспетчер PnP о том, что на устройстве произошло пользовательское событие.

Синтаксис

NTSTATUS IoReportTargetDeviceChange(
  [in] PDEVICE_OBJECT PhysicalDeviceObject,
  [in] PVOID          NotificationStructure
);

Параметры

[in] PhysicalDeviceObject

Указатель на PDO сообщаемого устройства.

[in] NotificationStructure

Указатель на предоставленную вызывающей TARGET_DEVICE_CUSTOM_NOTIFICATION структуру, описывающую пользовательское событие. Диспетчер PnP отправляет эту структуру драйверам, зарегистрированным для уведомления о событии.

NotificationStructure. FileObject должен иметь значение NULL. NotificationStructure. Событие должно содержать настраиваемый GUID для события. Другие поля NotificationStructure должны быть заполнены соответствующим образом для настраиваемого события.

Диспетчер PnP заполняет NotificationStructure. Поле FileObject при отправке уведомлений владельцам реестра.

Возвращаемое значение

IoReportTargetDeviceChange возвращает STATUS_SUCCESS или соответствующее состояние ошибки. Возможные значения состояния ошибки включают следующие.

Код возврата Описание
STATUS_INVALID_DEVICE_REQUEST
 Вызывающий объект указал системное событие PnP, например GUID_TARGET_DEVICE_QUERY_REMOVE. Эта подпрограмма используется только для пользовательских событий.

Комментарии

После того как IoReportTargetDeviceChange уведомит диспетчер PnP о том, что на устройстве произошло пользовательское событие, диспетчер PnP отправляет уведомление о событии драйверам, зарегистрированным для уведомления на устройстве. Не используйте эту подпрограмму для создания отчетов о системных событиях PnP, таких как GUID_TARGET_DEVICE_REMOVE_COMPLETE.

Драйвер, определяющий пользовательское событие устройства, вызывает IoReportTargetDeviceChange , чтобы сообщить диспетчеру PnP о том, что произошло пользовательское событие. Настраиваемое уведомление можно использовать для таких событий, как изменение метки тома.

Чтобы предотвратить взаимоблокировки, драйвер должен вызывать асинхронную форму этой подпрограммы IoReportTargetDeviceChangeAsynchronous.

Некоторые компоненты режима ядра могут вызывать эту синхронную подпрограмму. Например, файловая система может вызвать IoReportTargetDeviceChange , чтобы сообщить о пользовательском событии "выйти из тома", когда компонент пытается открыть том для монопольного доступа. Клиенты, которые регистрируются для получения уведомлений о томах файловой системы, стараются не запрашивать монопольное открытие в процедуре обратного вызова уведомлений PnP.

Настраиваемая структура уведомлений содержит событие, определяемое драйвером, с собственным ИДЕНТИФИКАТОРом GUID. Модули записи драйверов могут создавать идентификаторы GUID с Uuidgen.exe или Guidgen.exe (которые включены в Microsoft Windows SDK).

Вызывающие объект IoReportTargetDeviceChange должны выполняться в IRQL = PASSIVE_LEVEL в контексте системного потока. Чтобы сообщить об изменении целевого устройства с PASSIVE_LEVEL IRQL > , вызовите IoReportTargetDeviceChangeAsynchronous.

IoReportTargetDeviceChange не поддерживается в Windows 98/Me; возвращает STATUS_NOT_IMPLEMENTED.

Требования

Требование Значение
Минимальная версия клиента Доступно начиная с Windows 2000.
Целевая платформа Универсальное
Верхняя часть wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
Библиотека NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL (см. раздел "Примечания")
Правила соответствия DDI HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)

См. также раздел

IoReportTargetDeviceChangeAsynchronous

TARGET_DEVICE_CUSTOM_NOTIFICATION