MINIPORT_ADD_DEVICE Rückruffunktion (ndis.h)

Artikel
02/26/2024

Mit der Funktion MiniportAddDevice kann ein Miniporttreiber einen Kontextbereich für ein hinzugefügtes Gerät einrichten.

Hinweis Sie müssen die Funktion mit dem MINIPORT_ADD_DEVICE-Typ deklarieren. Weitere Informationen finden Sie im folgenden Abschnitt Beispiele.

Syntax

MINIPORT_ADD_DEVICE MiniportAddDevice;

NDIS_STATUS MiniportAddDevice(
  [in] NDIS_HANDLE NdisMiniportHandle,
  [in] NDIS_HANDLE MiniportDriverContext
)
{...}

Parameter

[in] NdisMiniportHandle

Ein NDIS-Handle, das den Miniportadapter identifiziert, den der PnP-Manager (Plug & Play) hinzufügt. NDIS übergibt diesen Handle auch an die MiniportInitializeEx-Funktion .

[in] MiniportDriverContext

Ein Handle für einen vom Treiber zugewiesenen Kontextbereich, in dem der Treiber Zustands- und Konfigurationsinformationen verwaltet. Der Miniporttreiber hat diesen Kontextbereich an die NdisMRegisterMiniportDriver-Funktion .

Rückgabewert

MiniportAddDevice gibt einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
NDIS_STATUS_SUCCESS	Der Miniporttreiber hat die Ressourcen erfolgreich zugeordnet, die zum Hinzufügen des Geräts erforderlich sind.
NDIS_STATUS_RESOURCES	Der Miniporttreiber konnte die erforderlichen Ressourcen nicht zuordnen.
NDIS_STATUS_FAILURE	MiniportAddDevice ist aus anderen Gründen als unzureichenden Ressourcen fehlgeschlagen.

Wenn MiniportAddDevice fehlschlägt , ruft NDIS die MiniportInitializeEx-Funktion nicht auf, um den Miniportadapter zu initialisieren.

Hinweise

Die MiniportAddDevice-Funktion ist eine optionale Funktion. Miniporttreiber, die MSI-X unterstützen, sollten einen Einstiegspunkt für diese Funktion im NDIS_MINIPORT_PNP_CHARACTERISTICS Struktur.

MiniportAddDevice kann einen Kontextbereich für die Behandlung zuweisen IRP_MN_FILTER_RESOURCE_REQUIREMENTS E/A-Anforderungspakete (IRPs) MiniportFilterResourceRequirements-Funktionshandles . Miniporttreiber geben den Kontextbereich an, indem sie einen initialisieren NDIS_MINIPORT_ADD_DEVICE_REGISTRATION_ATTRIBUTES Struktur, und rufen Sie dann die NdisMSetMiniportAttributes-Funktion . NDIS stellt später diesen Kontexthandle für miniportRemoveDevice bereit. MiniportFilterResourceRequirements-, MiniportStartDevice- und MiniportInitializeEx-Funktionen . Für MiniportInitializeEx wird das Kontexthandle im MiniportAddDeviceContext-Element des NDIS_MINIPORT_INIT_PARAMETERS Struktur, auf die der MiniportInitParameters-Parameter verweist.

Wenn der Miniporttreiber den MiniportAddDevice-Aufruf fehlschlägt , nachdem er den Kontextbereich zugewiesen hat, muss der Treiber den Kontextbereich freigeben, bevor er von MiniportAddDevice zurückkehrt.

Miniporttreiber sollten einen anderen Kontextbereich für das MiniportAddDeviceContext-Element der NDIS_MINIPORT_ADD_DEVICE_REGISTRATION_ATTRIBUTES-Struktur und das MiniportAdapterContext-Element der NDIS_MINIPORT_INIT_PARAMETERS-Struktur verwenden. Separate Kontextbereiche stellen sicher, dass Informationen im Kontextbereich nicht neu initialisiert werden. Dies kann in der Funktion MiniportInitializeEx auftreten, wenn der Miniportadapter angehalten und neu initialisiert wird.

Wenn der PnP-Manager anfordert, dass NDIS das Gerät entfernen soll, ruft NDIS die MiniportRemoveDevice-Funktion auf, um die von MiniportAddDevice ausgeführten Vorgänge rückgängig zu machen.

NDIS ruft MiniportAddDevice unter IRQL = PASSIVE_LEVEL auf.

Beispiele

Um eine MiniportAddDevice-Funktion zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der zu definierenden Funktion identifiziert. Windows stellt eine Reihe von Funktionstypen für Treiber bereit. Das Deklarieren einer Funktion mithilfe der Funktionstypen hilft der Codeanalyse für Treiber, der statischen Treiberüberprüfung (Static Driver Verifier , SDV) und anderen Überprüfungstools, Fehler zu finden, und es ist eine Anforderung zum Schreiben von Treibern für das Windows-Betriebssystem.

Um beispielsweise eine MiniportAddDevice-Funktion mit dem Namen "MyAddDevice" zu definieren, verwenden Sie den MINIPORT_ADD_DEVICE-Typ , wie in diesem Codebeispiel gezeigt:

MINIPORT_ADD_DEVICE MyAddDevice;

Implementieren Sie dann Ihre Funktion wie folgt:

_Use_decl_annotations_
NDIS_STATUS
 MyAddDevice(
    NDIS_HANDLE  NdisMiniportHandle,
    NDIS_HANDLE  MiniportDriverContext
    )
  {...}

Der MINIPORT_ADD_DEVICE Funktionstyp ist in der Ndis.h-Headerdatei definiert. Um Fehler beim Ausführen der Codeanalysetools genauer zu identifizieren, fügen Sie der Funktionsdefinition die Use_decl_annotations Anmerkung hinzu. Die Use_decl_annotations Anmerkung stellt sicher, dass die Anmerkungen verwendet werden, die auf den MINIPORT_ADD_DEVICE Funktionstyp in der Headerdatei angewendet werden. Weitere Informationen zu den Anforderungen für Funktionsdeklarationen finden Sie unter Deklarieren von Funktionen mithilfe von Funktionsrollentypen für NDIS-Treiber.

Informationen zu Use_decl_annotations finden Sie unter Verhalten von Funktionen mit Anmerkungen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Unterstützt in NDIS 6.0 und höher.
Zielplattform	Windows
Kopfzeile	ndis.h (einschließlich Ndis.h)
IRQL	PASSIVE_LEVEL