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

Статья
08/08/2023

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

Синтаксис

NTSTATUS IoReportTargetDeviceChangeAsynchronous(
  [in]           PDEVICE_OBJECT                   PhysicalDeviceObject,
  [in]           PVOID                            NotificationStructure,
  [in, optional] PDEVICE_CHANGE_COMPLETE_CALLBACK Callback,
  [in, out]      PVOID                            Context
);

Параметры

[in] PhysicalDeviceObject

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

[in] NotificationStructure

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

Эта структура, предоставляемая вызывающим объектом, может быть освобождена после возврата подпрограммы, так как диспетчер PnP создает неглубокую копию и использует копию для уведомления драйверов. Копия автоматически освобождается диспетчером PnP, как только она больше не нужна. См. раздел Примечания о требованиях к пулу распределения.

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

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

[in, optional] Callback

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

Подпрограмма обратного вызова имеет следующий тип:

typedef
VOID
(*PDEVICE_CHANGE_COMPLETE_CALLBACK)(
    IN PVOID Context
    );

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

Диспетчер PnP вызывает процедуры обратного вызова с изменением устройства и завершением в IRQL = PASSIVE_LEVEL.

[in, out] Context

При необходимости указывает на предоставленную вызывающим объектом структуру контекста, которую диспетчер PnP передает подпрограмме обратного вызова . Вызывающий объект должен выделить эту структуру из памяти без памяти.

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

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

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

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

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

Когда драйвер вызывает эту подпрограмму при обработке события, IRP_MN_REMOVE_DEVICE или IRP_MN_SURPRISE_REMOVAL, диспетчер PnP вызывает подпрограмму обратного вызова драйвера после возврата драйвера и очистки стека.

Вызывающие устройства IoReportTargetDeviceChangeAsynchronous должны выполняться в IRQL <= DISPATCH_LEVEL. Если модуль записи драйверов вызывает эту подпрограмму в IRQL = DISPATCH_LEVEL, notificationStructure должна быть выделена из непагрегированной памяти.

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL (см. раздел "Примечания")
Правила соответствия DDI	HwStorPortProhibitedDIS(storport)

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

IoReportTargetDeviceChange

TARGET_DEVICE_CUSTOM_NOTIFICATION