Função IoReportTargetDeviceChangeAsynchronous (wdm.h)
A rotina de IoReportTargetDeviceChangeAsynchronous notifica o gerenciador PnP de que ocorreu um evento personalizado em um dispositivo.
Sintaxe
NTSTATUS IoReportTargetDeviceChangeAsynchronous(
[in] PDEVICE_OBJECT PhysicalDeviceObject,
[in] PVOID NotificationStructure,
[in, optional] PDEVICE_CHANGE_COMPLETE_CALLBACK Callback,
[in, out] PVOID Context
);
Parâmetros
[in] PhysicalDeviceObject
Ponteiro para o PDO do dispositivo que está sendo relatado.
[in] NotificationStructure
Ponteiro para uma estrutura de TARGET_DEVICE_CUSTOM_NOTIFICATION fornecida pelo chamador que descreve o evento personalizado. O gerenciador PnP envia essa estrutura para drivers registrados para notificação do evento.
Essa estrutura fornecida pelo chamador pode ser liberada quando a rotina é retornada, pois o gerenciador PnP faz uma cópia superficial e usa a cópia para notificar os drivers. A cópia é liberada automaticamente pelo gerenciador PnP quando ela não é mais necessária. Consulte a seção Comentários sobre os requisitos do pool de alocação.
notificationStructure. FileObject deve ser NULL. notificationStructure. de evento deve conter o GUID personalizado para o evento. Os outros campos do NotificationStructure devem ser preenchidos conforme apropriado para o evento personalizado.
O gerenciador PnP preenche o NotificationStructure.campo FileObject ao enviar notificações aos inscritos.
[in, optional] Callback
Opcionalmente, aponta para uma rotina fornecida pelo chamador que o gerenciador de PnP chama depois que ele termina de notificar os drivers registrados para esse evento personalizado.
A rotina de retorno de chamada tem o seguinte tipo:
typedef
VOID
(*PDEVICE_CHANGE_COMPLETE_CALLBACK)(
IN PVOID Context
);
Uma rotina de retorno de chamada completa de alteração de dispositivo não deve ser bloqueada e não deve chamar rotinas síncronas que geram eventos PnP.
O gerenciador PnP chama rotinas de retorno de chamada completas de alteração de dispositivo em IRQL = PASSIVE_LEVEL.
[in, out] Context
Opcionalmente, aponta para uma estrutura de contexto fornecida pelo chamador que o gerenciador PnP passa para a rotina de de retorno de chamada. O chamador deve alocar essa estrutura de memória nãopagada.
Valor de retorno
| Código de retorno | Descrição |
|---|---|
| STATUS_INVALID_DEVICE_REQUEST | O chamador especificou um evento PnP do sistema, como GUID_TARGET_DEVICE_QUERY_REMOVE. Essa rotina é apenas para eventos personalizados. |
Observações
Depois que o rotina de IoReportTargetDeviceChangeAsynchronous notifica o gerenciador PnP de que ocorreu um evento personalizado em um dispositivo, a rotina retorna imediatamente; ele não aguarda enquanto o gerenciador PnP envia a notificação do evento para drivers registrados para notificação no dispositivo. Não use essa rotina para relatar eventos PnP do sistema, como GUID_TARGET_DEVICE_REMOVE_COMPLETE.
Um driver que define chamadas de evento de dispositivo personalizado IoReportTargetDeviceChangeAsynchronous para informar ao gerenciador PnP que o evento personalizado ocorreu. A notificação personalizada pode ser usada para eventos como uma alteração de rótulo de volume.
A estrutura de notificação personalizada contém um evento definido pelo driver com seu próprio GUID. Os gravadores de driver podem gerar GUIDs com Uuidgen.exe ou Guidgen.exe (que estão incluídos no SDK do Microsoft Windows).
Quando um driver chama essa rotina durante a manipulação de um evento, um IRP_MN_REMOVE_DEVICEou um IRP_MN_SURPRISE_REMOVAL, o gerenciador PnP chama a rotina de retorno de chamada do driver depois que o driver retorna e a pilha desenrola.
Os chamadores de IoReportTargetDeviceChangeAsynchronous devem estar em execução no IRQL <= DISPATCH_LEVEL. Se um gravador de driver chamar essa rotina em IRQL = DISPATCH_LEVEL, o NotificationStructure deverá ser alocado de memória nãopagada.