IRP_MN_ENABLE_EVENTS

Artigo
06/15/2023

Qualquer driver WMI que registre um ou mais blocos de eventos deve manipular esse IRP. Um driver pode lidar com IRPs WMI chamando WmiSystemControl ou manipulando o próprio IRP, conforme descrito em Manipulando solicitações WMI.

Se um driver chamar WmiSystemControl para lidar com uma solicitação de IRP_MN_ENABLE_EVENTS , o WMI, por sua vez, chamará a rotina DpWmiFunctionControl desse driver.

Código principal

IRP_MJ_SYSTEM_CONTROL

Quando enviado

O WMI envia esse IRP para informar ao driver que um consumidor de dados solicitou uma notificação de um evento.

O WMI envia esse IRP em IRQL = PASSIVE_LEVEL em um contexto de thread arbitrário.

Parâmetros de Entrada

Parameters.WMI.ProviderId aponta para o objeto de dispositivo do driver que deve responder à solicitação. Esse ponteiro está localizado no local da pilha de E/S do driver no IRP.

Parameters.WMI.DataPath aponta para um GUID que identifica o bloco de eventos a ser habilitado.

Parameters.WMI.BufferSize indica o tamanho do buffer nãopagado em Parameters.WMI.Buffer, que deve ser maior ou igual ao sizeof(WNODE_HEADER). Um driver que não registra blocos de rastreamento (WMIREG_FLAG_TRACED_GUID) pode ignorar esse parâmetro.

Parameters.WMI.Buffer aponta para um WNODE_HEADER que indica se o evento deve ser rastreado (WMI_FLAGS_TRACED_GUID) e fornece um identificador para o agente do sistema. Um driver que não registra blocos de rastreamento (WMIREG_FLAG_TRACED_GUID) pode ignorar esse parâmetro.

Parâmetros de saída

Nenhum.

Bloco de Status de E/S

Se o driver manipular o IRP chamando WmiSystemControl, o WMI definirá Irp-IoStatus.Status> e Irp-IoStatus.Information> no bloco de status de E/S.

Caso contrário, o driver define Irp-IoStatus.Status> como STATUS_SUCCESS ou como um erro apropriado status como o seguinte:

STATUS_WMI_GUID_NOT_FOUND

STATUS_INVALID_DEVICE_REQUEST

Em caso de êxito, um driver define Irp-IoStatus.Information> como zero.

Operação

Um driver pode lidar com IRPs WMI chamando WmiSystemControl ou manipulando o próprio IRP, conforme descrito em Manipulando solicitações WMI.

Se um driver manipular IRPs WMI chamando WmiSystemControl, essa rotina chamará a rotina DpWmiFunctionControl do driver ou retornará STATUS_SUCCESS se o driver não definir a rotina.

Se um driver manipular uma solicitação IRP_MN_ENABLE_EVENTS em si, ele deverá fazê-lo somente se Parameters.WMI.ProviderId apontar para o mesmo objeto de dispositivo que o ponteiro que o driver passou para IoWMIRegistrationControl. Caso contrário, o driver deve encaminhar a solicitação para o driver inferior seguinte.

Antes que o driver manipule a solicitação, ele deve determinar se Parameters.WMI.DataPath aponta para um GUID compatível com o driver. Caso contrário, o driver deve falhar no IRP e retornar STATUS_WMI_GUID_NOT_FOUND.

Se o driver der suporte ao bloco de eventos, ele habilitará o evento para todas as instâncias desse bloco de dados.

É desnecessário que o driver marcar se os eventos já estão habilitados para o bloco de eventos porque o WMI envia uma única solicitação para habilitar o bloco de eventos quando o primeiro consumidor de dados habilita o evento. O WMI não enviará outra solicitação para habilitar sem uma solicitação de desabilitação intermediária.

Um driver que registra blocos de rastreamento (WMIREG_FLAG_TRACED_GUID) também deve determinar se o evento deve ser enviado ao WMI ou ao agente do sistema para rastreamento. Se o rastreamento for solicitado, Parameters.WMI.Buffer apontará para uma estrutura WNODE_HEADER na qual Flags é definido com WNODE_FLAG_TRACED_GUID e HistoricalContext contém um identificador para o agente.

Para obter detalhes sobre como definir blocos de eventos, enviar eventos e rastreamento, consulte Instrumentação de Gerenciamento do Windows.