MB-Betriebssemantik

Asynchrone Transaktionen

Das MB-Treibermodell setzt voraus, dass die operative Semantik zwischen den MB-Dienst- und Miniporttreibern nicht blockiert wird, indem der asynchrone Benachrichtigungsmechanismus verwendet wird, der in NDIS 6.x bereitgestellt wird. Mit diesem Mechanismus kann der MB-Dienst weiterhin OID-Anforderungen zur Verarbeitung an den Miniporttreiber senden, ohne auf den Abschluss des aktuellen Vorgangs zu warten.

Eine asynchrone Transaktion ist ein dreiseitiger Handshake, der mit der anfänglichen Anforderung beginnt, gefolgt von einer Anforderungsstatusantwort und dann durch eine endgültige Transaktionsanzeige abgeschlossen wird. Die Anforderungsstatusantwort ist vorläufig, da nur bestätigt wird, dass der Miniporttreiber die Anforderung erhalten hat. Die asynchrone Nachverfolgungsanzeige ist transaktionsbereit, da sie den Abschluss der Transaktion signalisiert. Der Miniporttreiber gibt den Statuscode sowie die resultierenden Daten in der Transaktionsanzeige zurück.

Asynchrone Set- und Query-Anfragen

Viele der vom MB-Dienst verwendeten Set- und Abfrage-OID-Anforderungen werden asynchron verarbeitet. Weitere Informationen zu Set- und Abfrage-OID-Anforderungen finden Sie unter NDIS_OID_REQUEST. Die Tabelle "WWAN-spezifische OIDs" im Thema "MB-Datenmodell " identifiziert, welche OIDs asynchron verarbeitet werden.

Das folgende Diagramm stellt die Interaktionssequenz für eine asynchrone Abfragetransaktion zwischen dem MB-Dienst und dem Miniporttreiber dar. Die Bezeichnungen in Fettformat stellen OID-Bezeichner oder Transaktionsflusssteuerung dar, und die Beschriftungen im regulären Text stellen die wichtigen Flags innerhalb der OID-Struktur dar.

Der Drei-Wege-Handshake ist für Abfrage - und Satzanforderungen identisch.

Mit Ausnahme von OID_WWAN_DRIVER_CAPS folgen alle anderen MB-spezifischen OID-Anforderungen dem asynchronen Transaktionsmechanismus für den Informationsaustausch zwischen Miniporttreibern und dem MB-Dienst mit den folgenden zusätzlichen Hinweisen:

• Miniport-Treiber sollten sofort eine OID-Anforderung bei einer Fehlerbedingung fehlschlagen, z. B. eine ungültige OID-Anforderung.

• Miniport-Treiber müssen alle WWAN-spezifischen Fehlerbedingungen mit dem richtigen Fehlercode (z. B. WWAN_STATUS_XXX) zurückgeben, der im uStatus-Element der Ereignisbenachrichtigungsstruktur angegeben ist. Miniport-Treiber sollten bei Bedarf auch die Mitglieder ausfüllen, die dem uStatus-Mitglied folgen. Miniporttreiber sollten z. B. den ContextState.uNwError-Member der NDIS_WWAN_CONTEXT_STATE Struktur ausfüllen, sofern verfügbar. Im Falle eines Fehlers bei der Verarbeitung von OIDs im Zusammenhang mit PINs verfügen Miniporttreiber möglicherweise nicht unbedingt über die aktuellen PIN-Statusinformationen, die im PinInfo.PinState-Mitglied von NDIS_WWAN_PIN_INFO angegeben werden sollen.

• Miniport-Treiber sollten NDIS_STATUS_INDICATION_REQUIRED als vorläufige Antwort für alle asynchronen OID-Anforderungen zurückgeben.

• Miniport-Treiber sollten Gerätestatusänderungen unterscheiden können, die durch eine OID-Anforderung verursacht werden, von anderen Ursachen. Miniport-Treiber sollten Transaktionsbenachrichtigungen für Zustandsänderungen senden, die sich aus OID-Anforderungen ergeben, und sie sollten unerwünschte Ereignisbenachrichtigungen für Zustandsänderungen aus anderen Ursachen senden.

• Miniporttreiber sind für die Verwaltung des Kernelmodusspeichers verantwortlich, obwohl der MB-Dienst zunächst den Speicher für Anforderungen zuweist. Nachdem der MB-Dienst eine Antwort von einem Miniporttreiber empfängt, kann der Dienst den Für die OID-Anforderung zugewiesenen Benutzermodusspeicher freigeben.

Das folgende Diagramm stellt die Interaktionssequenz für eine asynchrone Satztransaktion zwischen dem MB-Dienst und dem Miniporttreiber dar. Die Bezeichnungen in Fettformat stellen OID-Bezeichner oder Transaktionsflusssteuerung dar, und die Beschriftungen im regulären Text stellen die wichtigen Flags innerhalb der OID-Struktur dar.

Asynchrone Antwort

Mit der NDIS 6.0-Spezifikation (veröffentlicht mit Windows Vista) wurde ein neuer Statuscode eingeführt, NDIS_STATUS_INDICATION_REQUIRED für Miniporttreiber, um die asynchrone Art einer Transaktion an den MB-Dienst in der vorläufigen Antwort eines Miniporttreibers auf eine OID-Anforderung zu übermitteln.

Wie in der MB Interface Overview erwähnt, verfügt der MB-Dienst nicht über direkten Zugriff auf den Kernelmodusspeicher, der von einem MB-Miniporttreiber zugewiesen wird. Das im Kernelmodus gespeicherte Ausführungsergebnis wird davon ausgegangen, dass es von einem Vermittler, z. B. WMI oder einem NDIS-Filtertreiber, dem MB-Dienst zur Verfügung gestellt wird. Daher können Miniporttreiber den zugewiesenen Kernelmodusspeicher freigeben, nachdem der NdisMIndicateStatusEx-Funktionsaufruf in der Transaktionsanzeige zurückgegeben wurde.

Die Handshake-Verfahren, denen Miniporttreiber und der MB-Dienst folgen müssen, werden im Folgenden beschrieben.

MB Miniport-Treiberprozedur

Bei Erhalt einer OID-Anforderung sollten Miniporttreiber die folgenden Schritte ausführen:

1. Weisen Sie Speicher im Kernelmodus zu, um den Inhalt der NDIS_OID_REQUEST Datenstruktur zu kopieren, die der OID-Anforderung zugeordnet ist.

2. Stellen Sie unter den Parametern der Anforderung sicher, dass auch die Mitglieder "RequestId" und "RequestHandle" der OID-Anforderungsstruktur kopiert werden. Diese Mitglieder werden später in der Transaktionsanzeige verwendet.

3. Gibt eine vorläufige NDIS_STATUS_INDICATION_REQUIRED-Status-Antwort zurück, um den MB-Dienst darüber zu informieren, dass der Miniporttreiber die Anforderung asynchron abschließen wird.

4. Speichern Sie nach Abschluss des Vorgangs das Ergebnis nach Bedarf im lokalen oder vom Treiber zugewiesenen Speicher.

5. Rufen Sie die NdisMIndicateStatusEx-Funktion auf, um den MB-Dienst zu benachrichtigen, dass der ausstehende Vorgang abgeschlossen wurde. Miniporttreiber sollten die Elemente der NDIS_STATUS_INDICATION Struktur wie folgt ausfüllen:

   1. Legen Sie das StatusCode-Element auf den Typ der Statusbenachrichtigung fest. Beispiel: NDIS_STATUS_WWAN_XXX.
   2. Legen Sie das DestinationHandle-Element auf das RequestHandle-Element fest, das in der NDIS_OID_REQUEST Datenstruktur empfangen wurde, als der Miniporttreiber die entsprechende OID-Anforderung empfangen hat.
   3. Legen Sie das RequestId-Element so fest, dass es mit dem RequestId-Element der NDIS_OID_REQUEST Statusstruktur übereinstimmt, wenn der Miniporttreiber die entsprechende OID-Anforderung empfangen hat.
   4. Legen Sie die Mitglieder StatusBuffer und StatusBufferSize so fest, dass sie auf den vom Miniport-Treiber zugewiesenen Speicher und die Größe des Speicherpuffers verweisen. Dieser Speicherpuffer enthält das Ergebnis des abgeschlossenen Vorgangs.
   5. Wenn der Vorgang erfolgreich abgeschlossen ist, legen Sie das uStatus-Element auf WWAN_STATUS_SUCCESS fest. Legen Sie andernfalls das uStatus-Element auf den entsprechenden WWAN_STATUS_XXX Wert fest, um den Typ des Fehlers anzugeben.

6. Wenn der Funktionsaufruf zurückgegeben wird, sollte der Miniporttreiber den Speicher freigeben, den er für die OID-Anforderung zugewiesen hat.

MB-Dienstprozedur

Der MB-Dienst verarbeitet asynchrone Transaktionen mithilfe des folgenden Verfahrens:

1. Weisen Sie den Pufferspeicher für die Anforderung basierend auf der OID-Datenstruktur zu. Füllen Sie die Elemente der Datenstruktur mit den entsprechenden Werten aus.

2. Rufen Sie die NdisOidRequest-Funktion mit dem InformationBuffer-Element auf, das auf die OID-Datenstruktur für die OID-Anforderung zeigt, und warten Sie, bis der Miniporttreiber reagiert.

3. Nach Erhalt einer NDIS_STATUS_INDICATION_REQUIRED vorläufige Antwort vom Miniporttreiber speichert der MB-Dienst die RequestId, gibt den zugewiesenen Speicher frei und markiert die Transaktion als geöffnet. Zu diesem Zeitpunkt kann der MB-Dienst nachfolgende OID-Anforderungen und -Benachrichtigungen verarbeiten.

4. Überprüfen Sie nach Erhalt einer Benachrichtigung mit NDIS_STATUS_WWAN_XXX als StatusCode-Wert , ob die RequestId mit der einer Transaktion übereinstimmt, die als geöffnet gekennzeichnet ist. Wenn eine Übereinstimmung vorhanden ist, schließt der Dienst die Transaktion. Wenn keine Übereinstimmung gefunden wird, behandeln Sie die Benachrichtigung als nicht angeforderte Ereignisbenachrichtigung.

5. Verarbeiten Sie die im StatusBuffer-Mitglied zurückgegebenen Daten, und nehmen Sie ggf. Statusänderungen am MB-Dienst vor.

Hinweise

Es gibt zwei Arten von WWAN-spezifischen Indikationen , die Miniporttreiber generieren können:

• Ereignisbenachrichtigungen, die sich aus einer Änderung des Objektzustands im MB-Gerät ergeben.

• Transaktionsbenachrichtigungen, die den Abschluss eines asynchronen Vorgangs signalisieren.

In beiden Fällen sollten Miniporttreiber die NdisMIndicateStatusEx-Funktion aufrufen.

Ereignisbenachrichtigung

Ereignisbenachrichtigungen werden in dem Sinne nicht angefordert, dass der Miniporttreiber proaktiv den Hinweis als Zustandsänderungsereignis an den MB-Dienst sendet. Die Statusänderung wird durch eine Aktion aus einer anderen Entität als dem MB-Dienst verursacht. Der MB-Dienst geht davon aus, dass Miniporttreiber die Ursache der Änderung erkennen können.

Für jede WWAN-spezifische Ereignisbenachrichtigung müssen Miniporttreiber das RequestId-Element der NDIS_STATUS_INDICATION Struktur auf Null festlegen. Das StatusCode-Element gibt an, welches Objekt im MB-Gerät geändert wurde. Der Miniporttreiber kann dieses Objekt auf einen der folgenden Werte festlegen:

NDIS_STATUS_WWAN_DEVICE_CAPS

NDIS_STATUS_WWAN_READY_INFO

NDIS_STATUS_WWAN_RADIO_STATE

NDIS_STATUS_WWAN_PIN_INFO

NDIS_STATUS_WWAN_PIN_LIST

NDIS_STATUS_WWAN_HOME_PROVIDER

NDIS_STATUS_WWAN_PREFERRED_PROVIDERS

NDIS_STATUS_WWAN_VISIBLE_PROVIDERS

NDIS_STATUS_WWAN_REGISTER_STATE

NDIS_STATUS_WWAN_PACKET_SERVICE

NDIS_STATUS_WWAN_SIGNAL_STATE

NDIS_STATUS_WWAN_CONTEXT_STATE

NDIS_STATUS_WWAN_PROVISIONED_CONTEXTS

NDIS_STATUS_WWAN_SERVICE_ACTIVATION

NDIS_STATUS_WWAN_SMS_CONFIGURATION

NDIS_STATUS_WWAN_SMS_RECEIVE

NDIS_STATUS_WWAN_SMS_SEND

NDIS_STATUS_WWAN_SMS_DELETE

NDIS_STATUS_WWAN_SMS_STATUS

NDIS_STATUS_WWAN_VENDOR_SPECIFIC

Der MB-Dienst kann auch andere Ereignisbenachrichtigungen von NDIS verarbeiten. Diese Nicht-MB-Ereignisbenachrichtigungen unterliegen nicht unbedingt der Anforderung, dass ihre RequestId-Werte auf Null festgelegt werden.

Transaktionsbenachrichtigungen

Miniport-Treiber verwenden Transaktionsbenachrichtigungen, um den MB-Dienst darüber zu informieren, dass eine asynchrone Transaktion abgeschlossen ist, und der MB-Dienst verwendet Transaktionsbenachrichtigungen, um geöffnete Transaktionen zu schließen und seinen Zustandsautomaten zu aktualisieren.

Der MB-Dienst erwartet Transaktionsbenachrichtigungen, sodass geöffnete Transaktionen geschlossen werden können. Es handelt sich um den abschließenden Austausch des Three-Way-Handshakes zwischen dem MB-Dienst und dem Miniport-Treiber in einer asynchronen Transaktion. Der Wert des RequestId-Mitglieds der NDIS_STATUS_INDICATION in jeder Transaktionsbenachrichtigung muss nicht null sein, die aus der entsprechenden Anforderung in derselben Transaktion kopiert wird.

Sie müssen das RequestId-Element der NDIS_STATUS_INDICATION Struktur korrekt festlegen, damit der asynchrone Mechanismus ordnungsgemäß funktioniert. Der MB-Dienst stellt sicher, dass der RequestId-Wert unter allen ausstehenden Anforderungen eindeutig und nicht null ist. Miniport-Treiber müssen den gleichen RequestId-Wert in der entsprechenden Angabe zurückgeben, damit der MB-Dienst die Angabe mit einer geöffneten Transaktion korreliert.

Statusanzeigestruktur

Sowohl die asynchrone Antwort für eine bestimmte OID-Anforderung als auch die unaufgeforderten Ereignisbenachrichtigungsstrukturen teilen sich die folgenden Strukturmitglieder, auf die durch das StatusBuffer-Element des StatusIndication-Parameters in NdisMIndicateStatusEx verwiesen wird:

typedef struct _NDIS_WWAN_XXX {
  NDIS_OBJECT_HEADER Header;
  WWAN_STATUS uStatus;
  ULONG uNwError;//Optional. Only used for network operations.
  WWAN_XXX XxxStruct;
} NDIS_WWAN_XXX, *PNDIS_WWAN_XXX;

Ein Wert von Null im RequestId-Element der NDIS_STATUS_INDICATION-Struktur bedeutet, dass es sich um eine unaufgeforderte Ereignisbenachrichtigung handelt und jederzeit auftreten kann.

Wenn der uStatus-Member in der zurückgegebenen Angabe einer Set- oder Abfrage-OID-Anforderung nicht gleich WWAN_STATUS_SUCCESS ist, müssen die Member der zugeordneten NDIS_WWAN_XXX-Struktur nicht gültig sein.

Bei nicht angeforderten Ereignisbenachrichtigungen basierend auf Netzwerkereignissen müssen Miniporttreiber ggf. das uNwError-Mitglied ausfüllen.

Die folgende Tabelle zeigt Die Registrierung, Paketanfügung und Pakettrennfunktion verursachen Codefehlerwerte, die in der 3GPP TS 24.008-Spezifikation für GSM-basierte Netzwerke definiert sind:

Wenn das Netzwerk z. B. ein Deaktivierungskontextereignis initiiert, da Roaming im Standortbereich nicht zulässig ist, sollten Miniporttreiber das uNwError-Mitglied auf 13 gemäß dem 3GPP TS 24.008 Ursachencodes für GSM-basierte Netzwerke festlegen.

Ähnliche Logik sollte auch auf CDMA-basierte Netzwerke angewendet werden. Es gibt jedoch keinen Standard für CDMA-basierte Netzwerkfehlercodes. CDMA-Geräte sollten das Netzwerk -specific oder gerätespezifische Fehlercodes verwenden.

Bei der asynchronen Antwort eines Miniporttreibers auf OID-Anforderungen ist das RequestId-Element der NDIS_STATUS_INDICATION-Struktur eine Nicht-Null-Nummer, die als Teil einer Satz - oder Abfrageanforderung an den Miniporttreiber übergeben wurde. Der Miniporttreiber muss das uStatus-Element entsprechend ausfüllen. Beispiel: WWAN_STATUS_SUCCESS oder eine der entsprechenden Fehlerwerte, die im folgenden Abschnitt aufgeführt sind. Darüber hinaus muss der Miniporttreiber den uNwError-Member, wo dies angebracht und möglich ist, ausfüllen.

Ereignisbenachrichtigungsstatus

In der folgenden Tabelle sind die WWAN_STATUS Codes aufgeführt, die MB-Miniporttreiber im uStatus-Element der NDIS_WWAN_XXX Ereignisbenachrichtigungsstrukturen angeben können.

Die folgende Tabelle zeigt SMS-spezifische Statuswerte.

Anmerkung Diese WWAN-spezifischen Statuscodes werden nur für asynchrone Transaktionen im uStatus-Element der NDIS_WWAN_XXX-Strukturen verwendet.

Miniport-Treiber verwenden Ereignisbenachrichtigungen, um den MB-Dienst über eine Objektstatusänderung in ihrem MB-Gerät zu informieren, ohne zuerst eine OID-Anforderung erhalten zu haben. Der MB-Dienst verwendet Ereignisbenachrichtigungen, um seinen Zustandscomputer nur zu aktualisieren.

Beachten Sie, dass NDIS zwar alle Anforderungen serialisiert, die an Miniporttreiber gesendet werden, aber miniport-Treiber geben möglicherweise nicht die Antworten in derselben Reihenfolge zurück. Dies liegt daran, dass die in die Warteschlange eingereihten Anforderungen im Miniporttreiber parallel verarbeitet werden können. Daher stellt der MB-Dienst sicher, dass, wenn zwei Anforderungen voneinander abhängig sind, die zweite Anforderung erst gesendet wird, nachdem der Miniporttreiber die erste Anforderung abgeschlossen hat.

Statusänderungsbenachrichtigung

Im Allgemeinen sollten Miniporttreiber den MB-Dienst immer über den aktualisierten Zustand ihres MB-Geräts über Transaktionsbenachrichtigungen oder über nicht angeforderte Ereignisbenachrichtigungen benachrichtigen. Die folgenden Szenarien sind einige Ausnahmen, bei denen Miniporttreiber nicht mit aktualisierten Statusinformationen reagieren sollen. Der MB-Dienst kann den aktualisierten Zustand aus dem Abschlussstatus anderer Vorgänge ermitteln:

1. Miniporttreiber müssen keine NDIS_STATUS_WWAN_PIN_LIST Ereignisanzeige senden, wenn sich der PIN-Zustand ändert, da der MB-Dienst angefordert hat, die PIN zu aktivieren oder zu deaktivieren.

2. Miniport-Treiber müssen in Transaktionsantworten auf OID_WWAN_PROVISIONED_CONTEXT Festlegen-Operationen nicht die aktualisierte Liste der bereitgestellten Kontexte zurückgeben.

3. Miniport-Treiber müssen nicht in den Transaktionsantworten auf OID_WWAN_PREFERRED_PROVIDERS Setzen-Operationen auf die aktualisierte Liste der bevorzugten Anbieter reagieren. Der MB-Dienst kann diese Informationen basierend auf der anfänglichen Liste und dem Erfolgsstatus des Set-Vorgangs ermitteln.

4. Miniporttreiber müssen nicht mit dem aktuellen WWAN_SMS_CONFIGURATION Wert für OID_WWAN_SMS_CONFIGURATION festgelegte Vorgänge reagieren.