Função IoReportTargetDeviceChangeAsynchronous (wdm.h)

A rotina 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 retorna, 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 depois que 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. O evento deve conter o GUID personalizado para o evento. Os outros campos da NotificationStructure devem ser preenchidos conforme apropriado para o evento personalizado.

O gerenciador PnP preenche NotificationStructure. Campo FileObject quando envia 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 que se registraram 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 retorno de chamada. O chamador deve alocar essa estrutura da memória nãopagada.

Retornar valor

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.

Comentários

Depois que a rotina IoReportTargetDeviceChangeAsynchronous notificar o gerenciador PnP de que um evento personalizado ocorreu em um dispositivo, a rotina retorna imediatamente; ele não aguarda enquanto o gerenciador de PnP envia a notificação do evento para drivers que se registraram 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 um evento de dispositivo personalizado chama 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 ao manipular um evento, um IRP_MN_REMOVE_DEVICE ou 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 em IRQL <= DISPATCH_LEVEL. Se um gravador de driver chamar essa rotina em IRQL = DISPATCH_LEVEL, a NotificationStructure deverá ser alocada da memória nãopagada.

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL (consulte a seção Comentários)
Regras de conformidade da DDI	HwStorPortProhibitedDDIs(storport)

Confira também

IoReportTargetDeviceChange

TARGET_DEVICE_CUSTOM_NOTIFICATION