Compartilhar via


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.

Requisitos

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

Consulte também

IoReportTargetDeviceChange

TARGET_DEVICE_CUSTOM_NOTIFICATION