NdisIMInitializeDeviceInstanceEx-Funktion (ndis.h)
Die NdisIMInitializeDeviceInstanceEx-Funktion 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 übernimmt den NdisMRegisterMiniportDriver Funktion gibt bei NdisMiniportDriverHandle zurück.
[in] DriverInstance
Ein Zeiger auf einen NDIS_STRING Typ, der eine vom Aufrufer initialisierte Zeichenfolge im Systemstandardzeichensatz beschreibt. Die Zeichenfolge enthält den Namen des Registrierungsschlüssels, in dem der Treiber Informationen zu einem virtuellen Miniport und ggf. bindungsspezifischen Informationen speichert. Für Microsoft Windows 2000 und höhere Treiber enthält diese Zeichenfolge Unicode-Zeichen. Für Windows 2000 und höher definiert NDIS den NDIS_STRING Typ als UNICODE_STRING Typ.
[in, optional] DeviceContext
Ein Zeiger, um vom Aufrufer bereitgestellten Speicher einzurichten, der mit treiberdefinierten Gerätekontextinformationen über den virtuellen Miniport eingerichtet werden soll, die protokollbasierte Treiber auf höherer Ebene, die sich anschließend an diesen virtuellen Miniport binden, verwenden können. Dieser Parameter kann NULL- werden, wenn der Zwischentreiber keinen solchen Gerätekontextbereich aufweist.
Rückgabewert
NdisIMInitializeDeviceInstanceEx- kann eine der folgenden Werte zurückgeben:
| Rückgabecode | Beschreibung |
|---|---|
|
NDIS initiierte den Initialisierungsvorgang für den virtuellen Miniport des Zwischentreibers. |
|
NdisIMInitializeDeviceInstanceEx fehlgeschlagen, da das durch DriverHandle- angegebene Gerät bereits initialisiert wurde. |
Bemerkungen
Ein NDIS-Zwischentreiber sollte NdisIMInitializeDeviceInstanceEx- aus seiner ProtocolBindAdapterEx--Funktion aufrufen. Fehler beim Aufrufen von NdisIMInitializeDeviceInstanceEx von einem NDIS-Zwischentreiber, der effektiv verhindert, dass dieser Treiber erfolgreich geladen wird.
Bevor NdisIMInitializeDeviceInstanceExaufgerufen wird, sollte die ProtocolBindAdapterEx--Funktion des Zwischentreibers an alle zugrunde liegenden Miniporttreiber gebunden werden, die für die Funktion des Zwischentreibers erforderlich sind. Die ProtocolBindAdapterEx--Funktion kann auch einen Bereich an DeviceContext- zuordnen, möglicherweise mit zwischengeschalteten treiberbestimmten Informationen über die Funktionen des zugrunde liegenden Miniportadapters und das von ProtocolBindAdapterExerfasst wurde. Die MiniportInitializeEx-Funktion des Zwischentreibers kann diese Informationen später verwenden, um diesen Kontextbereich mit Informationen zum virtuellen Miniport des Fahrers einzurichten.
Der Aufruf des Zwischentreibers an NdisIMInitializeDeviceInstanceEx bewirkt, dass NDIS die MiniportInitializeEx-Funktion des Zwischentreibers aufruft, wenn NDIS eine IRP_MN_START_DEVICE IRP empfängt, um das Gerät zu starten. Wenn NDIS kein solches IRP empfängt, ruft NDIS die MiniportInitializeEx- Funktion des Zwischentreibers nicht auf.
Der Aufruf von MiniportInitializeEx kann zu einem späteren Zeitpunkt erfolgen und liegt daher nicht unbedingt im Kontext des Aufrufs von NdisIMInitializeDeviceInstanceEx. Wenn NDIS niemals 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 Zwischentreiber den Zwischentreiber aufrufen NdisIMCancelInitializeDeviceInstance Funktion, um die Initialisierung des virtuellen Miniports abzubrechen. Angenommen, ein Zwischentreiber erstellt als Reaktion auf eine erfolgreiche Bindung an einen zugrunde liegenden Miniportadapter einen virtuellen Miniport. Wenn diese Bindung entfernt wird, bevor NDIS MiniportInitializeExaufruft, sollte der Zwischentreiber NdisIMCancelInitializeDeviceInstance aufrufen, um die Initialisierung des virtuellen Miniports abzubrechen.
MiniportInitializeEx alle Ressourcen zuordnet, die der Treiber zum Ausführen von Netzwerk-E/A-Vorgängen benötigt, z. B. das Aufrufen der NdisMSetMiniportAttributes Funktion und zum Initialisieren des virtuellen Miniports des Treibers in einen Betriebszustand. Anschließend können Protokolltreiber auf höherer Ebene sich an den virtuellen Miniport binden, wenn die Initialisierung des Zwischentreibers erfolgreich abgeschlossen wird.
Nachdem MiniportInitializeEx die Steuerung zurückgibt, kann der Gerätekontextbereich des Zwischentreibers ggf. beliebige zwischengeschaltete Daten enthalten, die anschließend alle Protokolltreiber auf höherer Ebene ermöglichen, die an denselben virtuellen Miniport gebunden sind, um auf Informationen in diesem Kontextbereich zuzugreifen. Ein solcher Protokolltreiber auf höherer Ebene kann den vom 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 aufgerufen hat, muss der Treiber aufrufen. NdisIMDeInitializeDeviceInstance, um den Initialisierungsvorgang umzukehren.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte 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 |
| Header- | ndis.h (include Ndis.h) |
| Library | Ndis.lib |
| IRQL- | PASSIVE_LEVEL |
| DDI-Complianceregeln | Irql_IM_Function(ndis) |