Übersicht über die WDI-TLV-Parserschnittstelle

Zuordnungsmodell der Angerufenen

Ein Einstiegspunkt innerhalb des Treibers empfängt eine Nachricht oder einen Hinweis, der TLVs enthält. Nachdem der Code die Nachrichten-ID extrahiert und bestimmt, ob es sich um eine ID handelt, die er behandeln möchte, ruft er die generische Analyseroutine auf und übergibt das TLV-Blob (nach dem Übersteigen über den WDI_MESSAGE_HEADER), um die TLVs in eine C-Struktur zu analysieren.

ndisStatus = Parse(
    cbBufferLength,
    pvBuffer,
    messageId,
    &Context,
    &pParsed);

Nachdem die Rückgabe auf Fehler überprüft wurde, kann der Code den Ausgabepuffer (pParsed) in einen konkreten Typ umwandeln, z. B. im folgenden Beispiel.

((WDI_INDICATION_BSS_ENTRY_LIST_PARAMETERS*)pParsed)

Nachdem der Aufrufer mit den analysierten Daten fertig ist, muss der Aufrufer den Arbeitsspeicher zurück an den Parser zurückgeben. Der Parser muss die ursprüngliche Nachrichten-ID kennen, die zum Zuordnen verwendet wurde, damit er die richtigen Daten freigibt.

FreeParsed(messageId, pParsed);
pParsed = NULL;

Anruferzuordnungsmodell

In diesem Modell hat der Aufrufer bereits die richtige spezifische TLV für die Analyse ermittelt und verwendet möglicherweise einen lokalen Stapel, um Zuordnungen auf dem Heap zu vermeiden. Der Aufrufer erstellt die lokale und ruft eine bestimmte Analyseroutine auf. Die API benötigt die Nachrichten-ID nicht, und der Parameter wird stark mit einer Dereferenzierungsebene weniger eingegeben.

WDI_GET_ADAPTER_CAPABILITIES_PARAMETERS adapterCapabilitiesParsed;

ndisStatus = ParseWdiGetAdapterCapabilities(
    cbBufferLength,
    pvBuffer,
    &Context
    &adapterCapabilitiesParsed);

Nachdem der Aufrufer die -Struktur verwendet hat, sollte der Aufrufer dem Parser die Möglichkeit geben, die während der Analyse vorgenommene Zuordnung zu sauber und die Struktur zu löschen, damit sie wiederverwendet werden kann. Der Parameter ist stark eingegeben, sodass der Angerufene keine zusätzlichen Parameter benötigt.

CleanupParsedWdiGetAdapterCapabilities(&adapterCapabilitiesParsed);

Nach dem Aufrufen der CleanupParse-API sind alle Daten in der Struktur ungültig.

Einige Nachrichten enthalten keine zugeordneten Daten. Zur Vollständigkeit der API werden entsprechend benannte Analysemethoden bereitgestellt. Diese Methoden überprüfen, ob der Bytestream leer ist. Typedefs werden für den Parametertyp bereitgestellt, aber Aufrufer können auch NULL für den Out-Parameter übergeben, wenn sie das Aufruferzuordnungsmodell verwenden. In allen Fällen vermeidet der Parser Zuordnungen, indem eine konstante leere Analysestruktur zurückgegeben wird. Aufrufer sollten niemals in diese zurückgegebene leere Struktur schreiben (daher heißt das einzige Feld _Reserved). Diese Meldungen werden als "Keine zusätzlichen Daten. Die Daten im Header sind ausreichend".

Nachrichtenrichtung

Die meisten Nachrichten haben ein anderes Format für ihre M1 als ihre M0, M3 oder M4. Um dies zu berücksichtigen, weisen solche Nachrichten unterschiedliche Analyse- und Generierungs-APIs auf. Für M1-Nachrichten folgen die APIs der Benennungskonvention "Analysieren<von Nachrichtenname>ToIhv" oder "Generieren<von Nachrichtenname>ToIhv". Für M0-, M3- oder M4-Nachrichten folgen die APIs der Benennungskonvention parse<MessageName>FromIhv oder Generate<MessageName>FromIhv. Um code im IHV-Miniport zu vereinfachen, werden jedoch Definieren zum Alias Parse<MessageName> hinzugefügt, umMessageName>toIhv zu analysieren<undMessageName<> generieren, umMessageName>vonIhv zu generieren<. IHV-Code muss dieses Aliasing nur kennen, wenn er seinen eigenen M3 analysieren oder einen M1 generieren muss.

Fehlercodes

Der TLV-Parsergenerator kann mehrere verschiedene NDIS_STATUS-Codes zurückgeben. Weitere Informationen finden Sie in den WPP-Ablaufverfolgungsprotokollen. Die Protokolle sollten immer die Grundursache angeben. Hier finden Sie eine Liste der häufigsten Fehlercodes und deren Bedeutung.

NDIS_STATUS_INVALID_DATA	Bei der Analyse gibt dies an, dass ein TLV mit fester Größe die falsche Größe aufweist. Für Listen bedeutet dies, dass die Gesamtgröße nicht einmal ein Vielfaches der einzelnen Elementgröße beträgt, oder es gibt mehr Elemente, als vorhanden sein sollten. Dies kann auch bedeuten, dass eine Liste 0 Elemente enthält, wenn 1 oder mehr erforderlich ist. Wenn 0 Elemente gewünscht sind, sollte Optional_IsPresent auf false festgelegt werden (der TLV-Header sollte sich nicht im Bytestream befinden).
NDIS_STATUS_BUFFER_OVERFLOW	Beim Generieren gibt dies an, dass aufgrund der Anzahl der Elemente in einem Array (Liste) das Feld Länge von 2 Byte innerhalb des TLV-Headers überläuft. Sie sollten die Anzahl der Elemente reduzieren. Dies kann auch auftreten, wenn ein äußeres TLV über zu viele (oder zu große) innere TLVs verfügt, wodurch das Feld 2 Byte Length des Headers erneut überläuft. Bei der Analyse weist dies darauf hin, dass das Length-Feld eines TLV-Headers größer ist als das äußere TLV oder der Bytedatenstrom.
NDIS_STATUS_FILE_NOT_FOUND	Beim Analysieren gibt dies an, dass im Bytestream kein erforderlicher TLV vorhanden ist. Es handelt sich in der Regel um einen Fehler beim Generator des Bytestroms.
NDIS_STATUS_RESOURCES	Bei der Generierung gibt dies an, dass der Zuteilungsfehler aufgetreten ist.
NDIS_STATUS_UNSUPPORTED_REVISION	Beim Analysieren oder Generieren ist der Context-Parameter NULL, oder peerVersion ist kleiner als WDI_VERSION_MIN_SUPPORTED.