Função IoReportTargetDeviceChange (wdm.h)

  • Artigo

A rotina IoReportTargetDeviceChange notifica o gerenciador PnP de que um evento personalizado ocorreu em um dispositivo.

Sintaxe

NTSTATUS IoReportTargetDeviceChange(
  [in] PDEVICE_OBJECT PhysicalDeviceObject,
  [in] PVOID          NotificationStructure
);

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.

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.

Retornar valor

IoReportTargetDeviceChange retorna STATUS_SUCCESS ou um erro apropriado status. Possíveis valores de status de erro incluem o seguinte.

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 IoReportTargetDeviceChange notifica o gerenciador de PnP de que ocorreu um evento personalizado em um dispositivo, o gerenciador PnP envia uma 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 um evento de dispositivo personalizado chama IoReportTargetDeviceChange 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.

Um driver deve chamar a forma assíncrona dessa rotina, IoReportTargetDeviceChangeAsynchronous, em vez dessa rotina, para evitar deadlocks.

Determinados componentes do modo kernel podem chamar essa rotina síncrona. Por exemplo, um sistema de arquivos pode chamar IoReportTargetDeviceChange para relatar um evento personalizado "sair do volume" quando um componente tenta abrir o volume para acesso exclusivo. Os clientes que se registram para notificação em volumes do sistema de arquivos têm o cuidado de não solicitar uma abertura exclusiva em uma rotina de retorno de chamada de notificação PnP.

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).

Os chamadores de IoReportTargetDeviceChange devem estar em execução em IRQL = PASSIVE_LEVEL no contexto de um thread do sistema. Para relatar uma alteração de dispositivo de destino de PASSIVE_LEVEL IRQL > , chame IoReportTargetDeviceChangeAsynchronous.

Não há suporte para IoReportTargetDeviceChange no Windows 98/Me; retorna STATUS_NOT_IMPLEMENTED.

Requisitos

Requisito Valor
Cliente mínimo com suporte Disponível a partir do Windows 2000.
Plataforma de Destino Universal
Cabeçalho wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Biblioteca NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL (consulte a seção Comentários)
Regras de conformidade da DDI HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)

Confira também

IoReportTargetDeviceChangeAsynchronous

TARGET_DEVICE_CUSTOM_NOTIFICATION