Функция IoReportTargetDeviceChangeAsynchronous (wdm.h)
Подпрограмма 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 (которые включены в пакет SDK для Microsoft Windows).
Когда драйвер вызывает эту подпрограмму при обработке события, IRP_MN_REMOVE_DEVICEили IRP_MN_SURPRISE_REMOVAL, диспетчер PnP вызывает обратного вызова драйвера после возврата драйвера и очистки стека.
Вызывающие IoReportTargetDeviceChangeAsynchronous должны работать в IRQL <= DISPATCH_LEVEL. Если модуль записи драйверов вызывает эту подпрограмму в IRQL = DISPATCH_LEVEL, необходимо выделить NotificationStructure из непагрегированной памяти.
Требования
| Требование | Ценность |
|---|---|
| целевая платформа | Всеобщий |
| заголовка | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| библиотеки | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | <= DISPATCH_LEVEL (см. раздел "Примечания") |
| правил соответствия DDI | HwStorPortProhibitedDIs(storport) |