NdisIMInitializeDeviceInstanceEx-Funktion (ndis.h)

Artikel
02/26/2024

Die Funktion NdisIMInitializeDeviceInstanceEx initiiert den Initialisierungsvorgang für einen virtuellen Miniport und richtet optional Zustandsinformationen zum virtuellen Miniport für nachfolgende gebundene Protokolltreiber ein.

Syntax

NDIS_STATUS NdisIMInitializeDeviceInstanceEx(
  [in]           NDIS_HANDLE  DriverHandle,
  [in]           PNDIS_STRING DriverInstance,
  [in, optional] NDIS_HANDLE  DeviceContext
);

Parameter

[in] DriverHandle

Der Miniporttreiber verarbeitet die Die NdisMRegisterMiniportDriver-Funktion gibt bei NdisMiniportDriverHandle zurück.

[in] DriverInstance

Ein Zeiger auf einen NDIS_STRING-Typ, der eine vom Aufrufer initialisierte zählige Zeichenfolge im Systemstandardzeichensatz beschreibt. Die Zeichenfolge enthält den Namen des Registrierungsschlüssels, in dem der Treiber Informationen zu einem virtuellen Miniport und möglicherweise bindungsspezifische Informationen speichert. Bei Treibern von Microsoft Windows 2000 und höher enthält diese Zeichenfolge Unicode-Zeichen. Das heißt, für Windows 2000 und höher definiert NDIS den NDIS_STRING-Typ als UNICODE_STRING-Typ .

[in, optional] DeviceContext

Ein Zeiger auf den vom Aufrufer bereitgestellten Arbeitsspeicher, der mit vom Treiber definierten Gerätekontextinformationen über den virtuellen Miniport eingerichtet werden soll, die noch höherstufige Protokolltreiber, die sich anschließend an diesen virtuellen Miniport binden, verwenden können. Dieser Parameter kann NULL sein, wenn der Zwischentreiber über keinen solchen Gerätekontextbereich verfügt.

Rückgabewert

NdisIMInitializeDeviceInstanceEx kann folgendes zurückgeben:

Rückgabecode	Beschreibung
NDIS_STATUS_SUCCESS	NDIS initiierte den Initialisierungsvorgang für den virtuellen Miniport des zwischengeschalteten Treibers.
NDIS_STATUS_NOT_ACCEPTED	Fehler bei NdisIMInitializeDeviceInstanceEx , da das von DriverHandle angegebene Gerät bereits initialisiert wurde.

Hinweise

Ein NDIS-Zwischentreiber sollte NdisIMInitializeDeviceInstanceEx über seine ProtocolBindAdapterEx-Funktion aufrufen. Ein Fehler beim Aufrufen von NdisIMInitializeDeviceInstanceEx von einem NDIS-Zwischentreiber verhindert effektiv, dass dieser Treiber erfolgreich geladen wird.

Bevor NdisIMInitializeDeviceInstanceEx aufgerufen wird, sollte die ProtocolBindAdapterEx-Funktion des Zwischentreibers an alle zugrunde liegenden Miniporttreiber gebunden werden, die für die Funktion des zwischengeschalteten Treibers erforderlich sind. Die ProtocolBindAdapterEx-Funktion kann auch einen Bereich bei DeviceContext zuordnen und ihn möglicherweise mit zwischen dem Treiber bestimmten Informationen über die Funktionen des zugrunde liegenden Miniportadapters einrichten, der von ProtocolBindAdapterEx erfasst wurde. Die MiniportInitializeEx-Funktion des zwischengeschalteten Treibers kann diese Informationen später verwenden, um diesen Kontextbereich mit Informationen über den virtuellen Miniport des Fahrers einzurichten.

Der Aufruf von NdisIMInitializeDeviceInstanceEx des Zwischentreibers bewirkt, dass NDIS die MiniportInitializeEx-Funktion des zwischengeschalteten Treibers aufruft, wenn NDIS eine IRP_MN_START_DEVICE IRP empfängt, um das Gerät zu starten. Wenn NDIS keinen solchen IRP empfängt, ruft NDIS die MiniportInitializeEx-Funktion des Zwischentreibers nicht auf.

Der Aufruf von MiniportInitializeEx kann zu einem späteren Zeitpunkt erfolgen und befindet sich daher nicht unbedingt im Kontext des Aufrufs von NdisIMInitializeDeviceInstanceEx. Wenn NDIS nie MiniportInitializeEx für den virtuellen Miniport aufruft, auf den in einem Aufruf von NdisIMInitializeDeviceInstanceEx verwiesen wird, und der zwischengeschaltete Treiber den virtuellen Miniport nicht mehr benötigt, sollte der zwischengeschaltete Treiber den NdisIMCancelInitializeDeviceInstance-Funktion zum Abbrechen der Initialisierung des virtuellen Miniports. Angenommen, ein Zwischentreiber erstellt einen virtuellen Miniport als Reaktion auf eine erfolgreiche Bindung an einen zugrunde liegenden Miniportadapter. Wenn diese Bindung entfernt wird, bevor NDIS MiniportInitializeEx aufruft, sollte der Zwischentreiber NdisIMCancelInitializeDeviceInstance aufrufen, um die Initialisierung des virtuellen Miniports abzubrechen.

MiniportInitializeEx weist alle Ressourcen zu, die der Treiber zum Ausführen von Netzwerk-E/A-Vorgängen benötigt, z. B. das Aufrufen des NdisMSetMiniportAttributes-Funktion und zum Initialisieren des virtuellen Miniports des Treibers in einen Betriebszustand. Dann können sich übergeordnete Protokolltreiber an den virtuellen Miniport binden, wenn die Initialisierung des Zwischentreibers erfolgreich abgeschlossen wurde.

Nachdem MiniportInitializeEx die Steuerung zurückgegeben hat, kann der Gerätekontextbereich des zwischengeschalteten Treibers ggf. alle zwischen dem Treiber definierten Daten enthalten, die anschließend allen Protokolltreibern höherer Ebene, die an denselben virtuellen Miniport gebunden sind, den Zugriff auf Informationen in diesem Kontextbereich ermöglichen. Ein solcher höherstufiger Protokolltreiber kann den Zwischentreiber-bereitgestellten Gerätekontext mit dem NdisIMGetBindingContext-Funktion .

Bevor NDIS die MiniportInitializeEx-Funktion eines Zwischentreibers aufruft, kann der Treiber aufrufen. NdisIMCancelInitializeDeviceInstance , um den Initialisierungsvorgang abzubrechen.

Nachdem NDIS die MiniportInitializeEx-Funktion eines Zwischentreibers aufruft, muss der Treiber aufrufen. NdisIMDeInitializeDeviceInstance , um den Initialisierungsvorgang rückgängig zu machen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Unterstützt für NDIS 6.0- und NDIS 5.1-Treiber (siehe NdisIMInitializeDeviceInstanceEx (NDIS 5.1)) in Windows Vista. Unterstützt für NDIS 5.1-Treiber (siehe NdisIMInitializeDeviceInstanceEx (NDIS 5.1)) in Windows XP.
Zielplattform	Desktop
Kopfzeile	ndis.h (einschließlich Ndis.h)
Bibliothek	Ndis.lib
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	Irql_IM_Function(ndis)