Função IoRegisterPlugPlayNotification (wdm.h)

Artigo
10/04/2023

A rotina IoRegisterPlugPlayNotification registra uma rotina de retorno de chamada de notificação de Plug and Play (PnP) a ser chamada quando ocorre um evento PnP da categoria especificada.

Sintaxe

NTSTATUS IoRegisterPlugPlayNotification(
  [in]           IO_NOTIFICATION_EVENT_CATEGORY        EventCategory,
  [in]           ULONG                                 EventCategoryFlags,
  [in, optional] PVOID                                 EventCategoryData,
  [in]           PDRIVER_OBJECT                        DriverObject,
  [in]           PDRIVER_NOTIFICATION_CALLBACK_ROUTINE CallbackRoutine,
  [in, optional] __drv_aliasesMem PVOID                Context,
  [out]          PVOID                                 *NotificationEntry
);

Parâmetros

[in] EventCategory

Especifica um valor de enumeração de IO_NOTIFICATION_EVENT_CATEGORY que indica a categoria do evento PnP para o qual a rotina de retorno de chamada está sendo registrada.

[in] EventCategoryFlags

Sinalizar bits que modificam a operação de registro. Os valores possíveis incluem:

PNPNOTIFY_DEVICE_INTERFACE_INCLUDE_EXISTING_INTERFACES

Válido somente com um EventCategory de EventCategoryDeviceInterfaceChange. Se definido, o gerenciador PnP chamará a rotina de retorno de chamada do driver para cada instância de interface do dispositivo atualmente registrada e ativa e registrará a rotina de retorno de chamada para chegadas futuras ou remoções de instâncias de interface do dispositivo.

[in, optional] EventCategoryData

Um ponteiro para obter mais informações sobre os eventos para os quais CallbackRoutine está sendo registrado. As informações variam para diferentes valores EventCategory :

Quando EventCategory é EventCategoryDeviceInterfaceChange, EventCategoryData deve apontar para um GUID que especifica uma classe de interface do dispositivo. CallbackRoutine será chamado quando uma interface dessa classe estiver habilitada ou removida.
Quando EventCategory é EventCategoryHardwareProfileChange, EventCategoryData deve ser NULL.
Quando EventCategory é EventCategoryTargetDeviceChange, EventCategoryData deve apontar para o objeto de arquivo para o qual a notificação PnP é solicitada.

[in] DriverObject

Um ponteiro para o objeto de driver do chamador.

Para garantir que o driver permaneça carregado enquanto está registrado para notificação PnP, essa chamada incrementa a contagem de referência em DriverObject. O gerenciador PnP diminui a contagem de referência quando esse registro é removido.

Para EventCategoryTargetDeviceChange, DriverObject não deve ser o objeto driver do dispositivo de destino; em vez disso, ele deve ser o objeto driver do driver que implementa CallbackRoutine.

[in] CallbackRoutine

Um ponteiro para a rotina de retorno de chamada de notificação PnP a ser chamada quando o evento PnP especificado ocorrer.

O protótipo de função para essa rotina de retorno de chamada é definido da seguinte maneira:

typedef NTSTATUS
  DRIVER_NOTIFICATION_CALLBACK_ROUTINE(
    _In_ PVOID NotificationStructure,
    _Inout_opt_ PVOID Context
    );

O NotificationStructure da rotina de retorno de chamada é específico para o valor EventCategory, conforme mostrado na tabela a seguir.

Categoria de evento	Estrutura de notificação
EventCategoryDeviceInterfaceChange	DEVICE_INTERFACE_CHANGE_NOTIFICATION
EventCategoryHardwareProfileChange	HWPROFILE_CHANGE_NOTIFICATION
EventCategoryTargetDeviceChange	TARGET_DEVICE_REMOVAL_NOTIFICATION Para obter mais informações, consulte Usando a notificação PnP e TARGET_DEVICE_CUSTOM_NOTIFICATION.

O parâmetro Context da rotina de retorno de chamada contém os dados de contexto fornecidos pelo driver durante o registro.

Para obter informações sobre como incluir uma declaração de função para a rotina de retorno de chamada que atende aos requisitos do SDV ( Verificador de Driver Estático ), consulte Exemplos.

O gerenciador PnP chama rotinas de retorno de chamada do driver em IRQL = PASSIVE_LEVEL.

[in, optional] Context

Um ponteiro para um buffer alocado pelo chamador que contém o contexto que o gerenciador PnP passa para a rotina de retorno de chamada.

[out] NotificationEntry

Um ponteiro para um valor opaco retornado por essa chamada que identifica o registro. Passe esse valor para a rotina IoUnregisterPlugPlayNotificationEx para remover o registro.

Retornar valor

IoRegisterPlugPlayNotification retorna STATUS_SUCCESS ou um erro apropriado status.

Comentários

Um driver se registra para uma categoria de evento. Cada categoria inclui um ou mais tipos de eventos PnP.

Um driver pode registrar diferentes rotinas de retorno de chamada para diferentes categorias de evento ou pode registrar uma única rotina de retorno de chamada. Uma única rotina de retorno de chamada pode converter NotificationStructure em um PLUGPLAY_NOTIFICATION_HEADER e usar o campo Evento para determinar o tipo exato da estrutura de notificação.

Se o chamador especificar PNPNOTIFY_DEVICE_INTERFACE_INCLUDE_EXISTING_INTERFACES, o sistema operacional poderá chamar a rotina de retorno de chamada de notificação PnP duas vezes para um único evento EventCategoryDeviceInterfaceChange para uma interface existente. Você pode ignorar com segurança a segunda chamada para o retorno de chamada. O sistema operacional não chamará o retorno de chamada mais de duas vezes para um único evento.

As rotinas de retorno de chamada de notificação PnP devem concluir suas tarefas o mais rápido possível e retornar o controle ao gerenciador PnP, para evitar atrasos na notificação de outros drivers e aplicativos registrados para o evento.

O gerenciador PnP não faz uma referência no objeto de arquivo quando um driver se registra para notificação de um evento EventCategoryTargetDeviceChange . Se a rotina de retorno de chamada de notificação PnP do driver exigir acesso ao objeto de arquivo, o driver deverá fazer uma referência extra no objeto de arquivo antes de chamar IoRegisterPlugPlayNotification.

Normalmente, Kernel-Mode drivers kmdf (Driver Framework) devem chamar IoRegisterPlugPlayNotification de sua função de retorno de chamada EvtDeviceSelfManagedIoInit e devem chamar IoUnregisterPlugPlayNotification de sua função de retorno de chamada EvtDeviceSelfManagedIoCleanup . Esses drivers não devem chamar IoRegisterPlugPlayNotification da função de retorno de chamada EvtDriverDeviceAdd ; caso contrário, a rotina de retorno de chamada de notificação PnP pode ser chamada antes que a pilha de driver seja iniciada pelo PnP, caso em que o driver não estará preparado para lidar com a notificação.

Para obter mais informações, consulte Usando a notificação PnP.

Exemplos

Para definir uma rotina de retorno de chamada de notificação PnP, primeiro você deve fornecer uma declaração de função que identifique o tipo de rotina de retorno de chamada que você está definindo. O Windows fornece um conjunto de tipos de função de retorno de chamada para drivers. Declarar uma função usando os tipos de função de retorno de chamada ajuda a Análise de Código para Drivers, SDV ( Verificador de Driver Estático ) e outras ferramentas de verificação a encontrar erros e é um requisito para gravar drivers para o sistema operacional Windows.

Por exemplo, para definir uma rotina de retorno de chamada de notificação PnP chamada MyCallbackRoutine, use o tipo DRIVER_NOTIFICATION_CALLBACK_ROUTINE conforme mostrado neste exemplo de código:

DRIVER_NOTIFICATION_CALLBACK_ROUTINE MyCallbackRoutine;

Em seguida, implemente sua rotina de retorno de chamada da seguinte maneira:

_Use_decl_annotations_
NTSTATUS
  MyCallbackRoutine(
    PVOID NotificationStructure,
    PVOID Context
    )
  {
      // Function body
  }

O tipo de função DRIVER_NOTIFICATION_CALLBACK_ROUTINE é definido no arquivo de cabeçalho Wdm.h. Para identificar erros com mais precisão ao executar as ferramentas de análise de código, adicione a anotação Use_decl_annotations à sua definição de função. A anotação Use_decl_annotations garante que as anotações aplicadas ao tipo de função DRIVER_NOTIFICATION_CALLBACK_ROUTINE no arquivo de cabeçalho sejam usadas. Para obter mais informações sobre os requisitos para declarações de função, consulte Declarando funções usando tipos de função de função para drivers WDM. Para obter informações sobre _Use_decl_annotations_, consulte Anotando o comportamento da função.

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	PASSIVE_LEVEL
Regras de conformidade de DDI	HwStorPortProhibitedDIs(storport), MarkPower(wdm), MarkPowerDown(wdm), MarkQueryRelations(wdm), MarkStartDevice(wdm), PowerIrpDDis(wdm)