Struktury WNODE_XXX usługi WMI

Usługa WMI używa zestawu standardowych struktur danych o nazwie WNODE_XXX do przekazywania danych między użytkownikami danych trybu użytkownika i dostawcami danych trybu jądra, takimi jak sterowniki. Jeśli sterownik obsługuje żądania WMI przez wywołanie WmiSystemControl, sterownik nie musi odczytywać ani zapisywać struktur WNODE_XXX. W przeciwnym razie sterownik musi interpretować dane wejściowe WNODE_XXX w Parameters.WMI.Buffer i/lub zapisać dane wyjściowe WNODE_XXX do tej lokalizacji.

W poniższej tabeli wymieniono elementy IRP usługi WMI i odpowiadające im struktury WNODE_XXX XXX.

Dwie dodatkowe struktury WNODE_XXX, WNODE_EVENT_ITEM i WNODE_EVENT_REFERENCE, służą do wysyłania powiadomień o zdarzeń z włączonymi funkcjami. Sterownik, który rejestruje bloki zdarzeń, jeśli zdarzenie jest włączone i wystąpi zdarzenie, wysyła powiadomienie o zdarzeniu do usługi WMI, wywołując IoWMIWriteEvent i przekazując WNODE_EVENT_XXX struktury. Aby uzyskać informacje na temat wysyłania zdarzeń usługi WMI, zobacz Wysyłanie zdarzeń usługi WMI.

Każda struktura WNODE_XXX składa się z następujących elementów:

• Osadzona struktura WNODE_HEADER zawierająca informacje wspólne dla wszystkich WNODE_XXX, w tym rozmiar buforu, identyfikator GUID reprezentujący blok danych oraz flagi wskazujące typ struktury WNODE_XXX, niezależnie od tego, czy używa ona nazw wystąpień statycznych, czy dynamicznych, i inne cechy bloku.

• Stałe elementy członkowskie konkretnej struktury WNODE_XXX, takie jak przesunięcia nazw wystąpień i danych.

Struktura WNODE_XXX w buforze IRP (Parameters.WMI.Buffer) zwykle następuje po danych zmiennych powiązanych z żądaniem, takich jak nazwy wystąpień dynamicznych, ciągi nazw wystąpień statycznych, dane wejściowe lub wyjściowe z metody lub dane dla co najmniej jednego wystąpienia bloku danych. W związku z tym rozmiar buforu musi przekraczać rozmiar (WNODE_XXX) ilością danych zmiennych.

Należy pamiętać, że usługa WMI nie przeprowadza sprawdzania typów na danych zmiennych dostarczonych przez sterownik. Sterownik musi wyrównać dane wyjściowe do odpowiedniej granicy w buforze wyjściowym, aby odbiorca danych mógł poprawnie analizować dane. W szczególności każde wystąpienie musi rozpoczynać się od granicy 8-bajtowej, a każdy z jego elementów musi być wyrównany do granicy naturalnej zgodnie ze schematem bloku danych, który został wcześniej zarejestrowany przez sterownik. Dynamiczne nazwy wystąpień można wyrównać do granicy 2-bajtowej.

Na poniższej ilustracji przedstawiono diagram blokowy buforu IRP zawierającego strukturę WNODE_SINGLE_INSTANCE, którą sterownik może zwrócić w odpowiedzi na żądanie IRP_MN_QUERY_SINGLE_INSTANCE.

Począwszy od góry poprzedniej ilustracji:

• Struktura WNODE_HEADER na początku WNODE_SINGLE_INSTANCE znajduje się w składowej WnodeHead er. Usługa WMI wypełnia wszystkie elementy członkowskie WNODE_HEADER przed wysłaniem żądania. W WNODE_HEADER:

  • WnodeHeader.Buffersize wskazuje rozmiar WNODE_SINGLE_INSTANCE, w tym dane zgodne ze stałymi elementami członkowskimi struktury. (Wartość WnodeHeader.Buffersize jest zwykle mniejsza niż Parameters.WMI.Buffersize, co wskazuje rozmiar buforu przydzielonego przez usługę WMI do odbierania danych wyjściowych ze sterownika).
  • WnodeHeader.Guid zawiera identyfikator GUID identyfikujący blok danych.
  • W tym przykładzie WnodeHeader.Flags wskazuje, że ta struktura jest WNODE_SINGLE_INSTANCE i że blok danych używa statycznych nazw wystąpień.

• Ponieważ blok danych używa nazw wystąpień statycznych, usługa WMI ustawia InstanceIndex do indeksu wystąpienia na liście nazw wystąpień statycznych przekazywanych przez sterownik po zarejestrowaniu bloku. offsetinstanceNames nie jest używana.

• Usługa WMI ustawia DataBlockOffset, aby wskazać przesunięcie od początku buforu do pierwszego bajtu danych wystąpienia. (Sterownik nie może zmienić tej wartości) Ponownie, ponieważ blok danych używa nazw wystąpień statycznych, to przesunięcie wskazuje tę samą lokalizację co VariableData. Jeśli blok danych używał nazw wystąpień dynamicznych, nazwy wystąpień zaczynają się od VariableData, a DataBlockOffset określi większe przesunięcie do buforu.

• Sterownik ustawia SizeDataBlock do liczby bajtów zwracanych danych wystąpienia.

• W VariableData (po danych nazwy wystąpienia, jeśli istnieją), sterownik zapisuje dane wystąpienia dla żądanego wystąpienia w buforze wyjściowym.

Sterownik odczytuje i zapisuje struktury WNODE_METHOD_ITEM i WNODE_SINGLE_ITEM w taki sam sposób jak WNODE_SINGLE_INSTANCE. Te struktury przypominają siebie w tym, że każdy z nich ma stałe elementy członkowskie OffsetInstanceName, InstanceIndex, DataBlockOffset, SizeDataBlock (lub w przypadku WNODE_SINGLE_ITEM, SizeDataItem) i VariableData. WNODE_METHOD_ITEM zawiera MethodId i WNODE_SINGLE_ITEM zawiera ItemId, którego WNODE_SINGLE_INSTANCE brakuje.

WNODE_ALL_DATA różni się od poprzednich struktur, które są używane do przekazywania wielu wystąpień bloku danych, w tym nazw wystąpień dynamicznych i ewentualnie różnych rozmiarów.

Na poniższej ilustracji przedstawiono diagram blokowy buforu IRP zawierającego WNODE_ALL_DATA, które sterownik może zwrócić w odpowiedzi na żądanie IRP_MN_QUERY_ALL_DATA.

Począwszy od góry poprzedniej ilustracji:

• Jak opisano na poprzedniej ilustracji, struktura WNODE_HEADER na początku WNODE_ALL_DATA jest zawarta w składowej WnodeHeader. WnodeHeader.Buffersize i WnodeHeader.Guid wskazują rozmiar WNODE_ALL_DATA i identyfikator GUID bloku danych, odpowiednio.

  W tym przykładzie usługa WMI ustawia WnodeHeader.Flags, aby wskazać, że ta struktura jest WNODE_ALL_DATA i że blok danych został zarejestrowany przy użyciu nazw wystąpień dynamicznych (czyli usługa WMI czyści WNODE_FLAG_STATIC_INSTANCE_NAMES i WNODE_FLAG_PDO_INSTANCE_NAMES). W danych wyjściowych sterownik ustawia WNODE_FLAG_FIXED_INSTANCE_SIZE, aby wskazać, że wszystkie wystąpienia mają ten sam rozmiar.

• Usługa WMI ustawia DataBlockOffset, aby wskazać przesunięcie od początku buforu do pierwszego bajtu danych wystąpienia. (Sterownik nie może zmienić tej wartości). W tym przykładzie dane wystąpienia są zgodne z nazwami wystąpień w OffsetInstanceNameOffsets.

• Sterownik ustawia InstanceCount, aby wskazać liczbę zwracanych wystąpień.

• WNODE_XXX bloków danych, które używają nazw wystąpień dynamicznych, zawsze zawierają ciągi nazw wystąpień. Ponieważ w tym przykładzie użyto nazw wystąpień dynamicznych, OffsetInstanceNameOffsets wskazuje przesunięcie od początku buforu do tablicy przesunięć na nazwy wystąpień dynamicznych w buforze.

• FixedInstanceSize wskazuje liczbę bajtów danych w każdym wystąpieniu zwracanym przez sterownik. Jeśli wystąpienia tego bloku danych miały różny rozmiar, Sterownik wyczyściłby WNODE_FLAG_FIXED_INSTANCE_SIZE w WnodeHeader.Flags i ustawił OffsetInstanceDataAndLength do tablicy OFFSETINSTANCEDATAANDLENGTH struktur, z których każdy określa przesunięcie danych dla jednego wystąpienia i liczbę bajtów w tym wystąpieniu zamiast ustawiać FixedInstanceSize.

Aby uzyskać więcej informacji o strukturach WNODE_XXX, zobacz Struktury systemowe.