Rastreamento de eventos WMI

Esta seção descreve as extensões WMI para o WDM (com suporte do Windows 2000 e posterior) que os drivers do modo kernel, como provedores de informações, podem usar para fornecer informações aos consumidores de informações. Normalmente, os drivers fornecem informações que um consumidor usa para determinar a configuração do driver e o uso de recursos. Além das extensões WMI para WDM, uma API de modo de usuário dá suporte a provedores ou consumidores de informações de evento WMI, consulte o SDK do Windows para obter mais informações.

O agente de rastreamento de eventos dá suporte a até 32 instâncias. Uma das instâncias é reservada para rastrear o kernel. O registrador dá suporte ao rastreamento de uma alta taxa de eventos.

Os eventos de rastreamento são definidos da mesma maneira que outros eventos WMI. Os eventos WMI são descritos no arquivo MOF. Para obter mais informações sobre descrições de eventos WMI, consulte a sintaxe MOF para blocos de eventos e dados WMI.

O processo pelo qual drivers no modo kernel registram informações está integrado à infraestrutura WMI existente. Para registrar eventos de rastreamento, um driver executa as seguintes ações:

1. Registre-se como um provedor WMI chamando IoWMIRegistrationControl.

2. Marque eventos como rastreáveis definindo WMIREG_FLAG_TRACED_GUID no membro Flags da estrutura WMIREGGUID que é passada quando o driver registra eventos com WMI.

3. Especifique um evento como o evento de controle para habilitação/desabilitação geral de um conjunto de eventos de rastreamento definindo WMIREG_FLAG_TRACE_CONTROL_GUID no membro Flags da estrutura WMIREGGUID que é passada quando o driver registra eventos com WMI.

4. Ao receber uma solicitação do WMI para habilitar eventos em que o GUID corresponde ao GUID de controle de rastreamento, o driver deve armazenar o identificador para o registrador. O valor será necessário ao escrever um evento. Para obter informações sobre como usar esse identificador, consulte a etapa 6. O valor do identificador do registrador está contido no membro HistoricalContext da parte WNODE_HEADER do buffer WMI que faz parte dos parâmetros da solicitação para habilitar eventos.

5. Decida se o evento de rastreamento será enviado para os consumidores de eventos WMI ou se é direcionado apenas para o registrador de eventos WMI. Isso determinará de onde a memória da estrutura de EVENT_TRACE_HEADER deve vir. Essa memória eventualmente será passada para IoWMIWriteEvent.

   Se o evento for apenas um evento de log, a memória não será excluída pelo WMI. Nesse caso, o driver deve passar um buffer na pilha ou deve reutilizar um buffer já alocado para essa finalidade. Por motivos de desempenho, o driver deve minimizar as chamadas desnecessárias para alocar ou liberar memória. O não cumprimento dessa recomendação comprometerá a integridade das informações de tempo contidas no arquivo de log.

   Se o evento for enviado tanto ao registrador quanto aos consumidores de eventos WMI, a memória deverá ser alocada de um pool não paginado. Nesse caso, o evento será enviado ao logger e, em seguida, encaminhado para o WMI para ser transmitido aos consumidores de eventos do WMI que solicitaram a notificação do evento. A memória do evento será liberada pela WMI de acordo com o comportamento de IoWMIWriteEvent.

6. Depois que a memória do EVENT_TRACE_HEADER e quaisquer dados de evento de driver, se houver, tiverem sido protegidos, as seguintes informações deverão ser definidas:

   Defina o membro Size como sizeof(EVENT_TRACE_HEADER) mais o tamanho de qualquer dado de evento de driver adicional que será acrescentado ao final de EVENT_TRACE_HEADER.

   Defina o membro Flags como WNODE_FLAG_TRACED_GUID para que o evento seja enviado ao registrador. Caso o evento também deva ser enviado aos consumidores de eventos WMI, configure o WNODE_FLAG_LOG_WNODE. Observe que não é necessário definir WNODE_FLAG_TRACED_GUID se a configuração de WNODE_FLAG_LOG_WNODE. Se ambos estiverem definidos, WNODE_FLAG_TRACED_GUID terá precedência e o evento não será enviado para os consumidores de eventos do WMI.

   Defina o Guid ou o membro GuidPtr . Se estiver usando GuidPtr, defina WNODE_FLAG_USE_GUID_PTR no membro Flags .

   Opcionalmente, especifique um valor para TimeStamp. Se o driver não especificar um valor TimeStamp, o logger preencherá isso. Se o driver não quiser que o agente defina o carimbo de data/hora, deverá definir WNODE_FLAG_USE_TIMESTAMP no membro Flags.

   Defina qualquer um dos seguintes membros EVENT_TRACE_HEADER que tenham significado para o driver: Class.Type, Class.Level e Class.Version.

   Por fim, converta o EVENT_TRACE_HEADER em um WNODE_HEADER e atribua o identificador do logger ao valor HistoricalContext do Wnode que foi salvo na etapa 4 acima.

7. Chame IoWMIWriteEvent com o ponteiro para a estrutura EVENT_TRACE_HEADER.

O driver deve continuar registrando eventos de rastreamento associados ao GUID de controle até receber uma notificação para desabilitar o log de eventos por meio de uma solicitação IRP_MN_DISABLE_EVENTS.