Śledzenie zdarzeń usługi WMI

W tej sekcji opisano rozszerzenia WMI do WDM (obsługiwane przez system Windows 2000 i nowsze), które sterowniki w trybie jądra, jako dostawcy informacji, mogą wykorzystywać do dostarczania informacji konsumentom. Sterowniki zazwyczaj udostępniają informacje używane przez użytkownika do określenia konfiguracji sterownika i użycia zasobów. Oprócz rozszerzeń usługi WMI dla WDM, interfejs API trybu użytkownika obsługuje dostawców lub użytkowników informacji o zdarzeniach usługi WMI — zobacz Windows SDK, aby uzyskać więcej informacji.

Rejestrator śledzenia zdarzeń obsługuje maksymalnie 32 wystąpienia. Jedno z wystąpień jest zarezerwowane do śledzenia jądra. Rejestrator obsługuje śledzenie dużej częstotliwości zdarzeń.

Zdarzenia śledzenia są definiowane w taki sam sposób, jak inne zdarzenia usługi WMI. Zdarzenia WMI są opisane w pliku MOF. Aby uzyskać więcej informacji na temat opisów zdarzeń usługi WMI, zobacz Składnia MOF dla danych i bloków zdarzeń usługi WMI.

Proces, za pomocą którego sterowniki trybu jądra rejestrują informacje, jest zintegrowany z istniejącą infrastrukturą WMI. Aby rejestrować zdarzenia śledzenia, sterownik wykonuje następujące czynności:

1. Zarejestruj się jako dostawca WMI, wywołując funkcję IoWMIRegistrationControl.

2. Oznacz zdarzenia jako możliwe do śledzenia, ustawiając WMIREG_FLAG_TRACED_GUID w elemencie członkowskim Flags struktury WMIREGGUID , która jest przekazywana, gdy sterownik rejestruje zdarzenia w usłudze WMI.

3. Określ jedno zdarzenie jako zdarzenie sterujące dla ogólnego włączania/wyłączania zestawu zdarzeń śledzenia, ustawiając WMIREG_FLAG_TRACE_CONTROL_GUID w elemencie członkowskim Flags struktury WMIREGGUID , która jest przekazywana, gdy sterownik rejestruje zdarzenia w usłudze WMI.

4. Po otrzymaniu żądania z usługi WMI w celu włączenia zdarzeń, w których identyfikator GUID jest zgodny z GUID kontrolującym śledzenie, sterownik powinien przechowywać dojście do rejestratora. Wartość będzie potrzebna podczas zapisywania zdarzenia. Aby uzyskać informacje o sposobie korzystania z tego uchwytu, zobacz krok 6. Wartość uchwytu rejestratora znajduje się w elemencie HistoricalContext części WNODE_HEADER buforu usługi WMI, który jest częścią parametrów w żądaniu włączania zdarzeń.

5. Zdecyduj, czy zdarzenie śledzenia zostanie wysłane do odbiorców zdarzeń usługi WMI, czy jest przeznaczone tylko dla rejestratora zdarzeń usługi WMI. Spowoduje to określenie, skąd powinna pochodzić pamięć dla struktury EVENT_TRACE_HEADER . Ta pamięć zostanie ostatecznie przekazana do IoWMIWriteEvent.

   Jeśli zdarzenie jest tylko zdarzeniem dziennika, pamięć nie zostanie usunięta przez usługę WMI. W takim przypadku sterownik powinien przekazać bufor na stosie albo ponownie użyć przydzielonego bufora do tego celu. Ze względu na wydajność sterownik powinien zminimalizować wszelkie niepotrzebne wywołania w celu przydzielenia lub zwolnienia pamięci. Brak zgodności z tym zaleceniem spowoduje naruszenie integralności informacji o chronometrażu zawartych w pliku dziennika.

   Jeśli zdarzenie ma być wysyłane zarówno do rejestratora, jak i do odbiorców zdarzeń usługi WMI, pamięć musi zostać przydzielona z puli niestronicowanej. W takim przypadku zdarzenie zostanie wysłane do rejestratora, a następnie przekazane do WMI do odbiorców zdarzeń WMI, którzy zażądali o powiadomienie o zdarzeniu. Pamięć dla zdarzenia zostanie następnie zwolniona przez WMI zgodnie z zachowaniem IoWMIWriteEvent.

6. Po zabezpieczeniu pamięci dla EVENT_TRACE_HEADER oraz wszelkich danych zdarzeń sterownika, jeśli takie istnieją, należy ustawić następujące informacje:

   Ustaw element członkowski Rozmiar na sizeof(EVENT_TRACE_HEADER) oraz rozmiar wszelkich dodatkowych danych zdarzenia sterownika, które zostaną dołączone na końcu EVENT_TRACE_HEADER.

   Ustaw człon Flags na WNODE_FLAG_TRACED_GUID, aby zdarzenie zostało wysłane do rejestratora. Jeśli zdarzenie ma być również wysyłane do odbiorców zdarzeń usługi WMI, ustaw WNODE_FLAG_LOG_WNODE. Należy pamiętać, że nie jest konieczne ustawienie WNODE_FLAG_TRACED_GUID, jeśli ustawiony jest WNODE_FLAG_LOG_WNODE. Jeśli oba te ustawienia zostaną ustawione, WNODE_FLAG_TRACED_GUID będą miały pierwszeństwo, a zdarzenie nie zostanie wysłane do odbiorców zdarzeń usługi WMI.

   Ustaw identyfikator GUID lub członek GuidPtr. Jeśli używasz GuidPtr, ustaw WNODE_FLAG_USE_GUID_PTR w polu Flags.

   Opcjonalnie określ wartość dla TimeStamp. Jeśli sterownik nie określi wartości znacznika czasu , rejestrator wypełni to pole. Jeśli sterownik nie chce, aby rejestrator ustawił znacznik czasu, powinien ustawić WNODE_FLAG_USE_TIMESTAMP w członie Flags.

   Ustaw dowolny z następujących elementów członkowskich EVENT_TRACE_HEADER, które mają znaczenie dla sterownika: Class.Type, Class.Level i Class.Version.

   Na koniec, przekonwertuj EVENT_TRACE_HEADER na WNODE_HEADER, a następnie ustaw wartość HistoricalContext dla Wnode na uchwyt rejestratora, który został zapisany w kroku 4 powyżej.

7. Wywołaj IoWMIWriteEvent za pomocą wskaźnika do struktury EVENT_TRACE_HEADER.

Sterownik powinien kontynuować rejestrowanie zdarzeń śledzenia skojarzonych z identyfikatorem GUID kontrolki, dopóki sterownik nie otrzyma powiadomienia o wyłączeniu rejestrowania zdarzeń za pośrednictwem żądania IRP_MN_DISABLE_EVENTS .