DRIVER_ADD_DEVICE Rückruffunktion (wdm.h)

Artikel
03/08/2023

Die AddDevice-Routine ist für das Erstellen von funktionalen Geräteobjekten (Functional Device Objects, FDO) oder das Filtern von Geräteobjekten (Filter DO) für Geräte verantwortlich, die vom PnP-Manager (Plug & Play) aufgelistet werden.

Syntax

DRIVER_ADD_DEVICE DriverAddDevice;

NTSTATUS DriverAddDevice(
  [in] _DRIVER_OBJECT *DriverObject,
  [in] _DEVICE_OBJECT *PhysicalDeviceObject
)
{...}

Parameter

[in] DriverObject

Vom Aufrufer bereitgestellter Zeiger auf eine DRIVER_OBJECT Struktur. Dies ist das Treiberobjekt des Treibers.

[in] PhysicalDeviceObject

Vom Aufrufer bereitgestellter Zeiger auf eine DEVICE_OBJECT Struktur, die ein physisches Geräteobjekt (PDO) darstellt, das von einem Treiber auf niedrigerer Ebene erstellt wurde.

Rückgabewert

Wenn die Routine erfolgreich ist, muss sie STATUS_SUCCESS zurückgeben. Andernfalls muss einer der In Ntstatus.h definierten Fehlerwerte status zurückgegeben werden.

Hinweise

Alle Kernelmodustreiber, die PnP unterstützen, müssen eine AddDevice-Routine bereitstellen.

Die AddDevice-Routine eines Treibers sollte XxxAddDevice heißen, wobei Xxx ein treiberspezifisches Präfix ist. Die DriverEntry-Routine des Treibers muss die Adresse der AddDevice-Routine in DriverObject-DriverExtension-AddDevice>> speichern.

Die hauptverantwortlichen Aufgaben einer AddDevice-Routine sind das Aufrufen von IoCreateDevice zum Erstellen eines Geräteobjekts und dann das Aufrufen von IoAttachDeviceToDeviceStack , um das Geräteobjekt an den Gerätestapel anzufügen. Ausführliche Informationen zum Implementieren der AddDevice-Routine eines Treibers finden Sie unter Schreiben einer AddDevice-Routine.

Eine AddDevice-Routine wird in einem Systemthreadkontext unter IRQL = PASSIVE_LEVEL ausgeführt.

Beispiele

Um eine AddDevice-Rückrufroutine zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der von Ihnen definierten Rückrufroutine identifiziert. Windows bietet eine Reihe von Rückruffunktionstypen für Treiber. Das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen 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 AddDevice-Rückrufroutine mit dem Namen MyAddDevice<zu definieren, verwenden Sie den typ DRIVER_ADD_DEVICE, wie in diesem Codebeispiel gezeigt:

DRIVER_ADD_DEVICE MyAddDevice;

Implementieren Sie dann Ihre Rückrufroutine wie folgt:

_Use_decl_annotations_
NTSTATUS
  MyAddDevice(
    struct _DRIVER_OBJECT  *DriverObject,
    struct _DEVICE_OBJECT  *PhysicalDeviceObject 
    )
  {
      // Function body
  }

Der DRIVER_ADD_DEVICE Funktionstyp ist in der Headerdatei Wdm.h definiert. Um Fehler beim Ausführen der Codeanalysetools genauer zu identifizieren, fügen Sie die _Use_decl_annotations_ Anmerkung ihrer Funktionsdefinition hinzu. Die _Use_decl_annotations_ Anmerkung stellt sicher, dass die Anmerkungen verwendet werden, die auf den DRIVER_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 WDM-Treiber. Informationen zu _Use_decl_annotations_finden Sie unter Annotating Function Behavior.

Anforderungen

Anforderung	Wert
Zielplattform	Desktop
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
IRQL	Wird bei PASSIVE_LEVEL aufgerufen (siehe Abschnitt Hinweise).

Freigeben über