DRIVER_ADD_DEVICE Rückruffunktion (wdm.h)

Artikel
02/07/2025

Die AddDevice Routine ist für das Erstellen funktionaler Geräteobjekte (FDO) oder des Filterns von Geräteobjekten (Filter DO) für Geräte verantwortlich, die vom Plug and Play (PnP)-Manager aufgezählt 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 eine der fehlerstatuswerte zurückgegeben werden, die in Ntstatus.h definiert sind.

Bemerkungen

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

Die AddDevice Routine eines Treibers sollte Xxx-AddDevice benannt werden, wobei Xxx- ein treiberspezifisches Präfix ist. Die DriverEntry-Routine des Treibers muss die AddDevice--Routineadresse in DriverObject->DriverExtension->AddDevice-speichern.

Eine AddDevice primäre Zuständigkeiten der Routine ruft IoCreateDevice auf, um ein Geräteobjekt zu erstellen, und dann IoAttachDeviceToDeviceStack- aufruft, 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 bei IRQL = PASSIVE_LEVEL ausgeführt.

Beispiele

Um eine AddDevice- Rückrufroutine zu definieren, müssen Sie zuerst eine Funktionsdeklaration bereitstellen, die den Typ der von Ihnen definierten Rückrufroutine identifiziert. Windows stellt eine Reihe von Rückruffunktionstypen für Treiber bereit. Durch das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen können Codeanalyse für Treiber, statische Treiberüberprüfung (SDV) und andere Überprüfungstools Fehler finden, und es ist eine Anforderung zum Schreiben von Treibern für das Windows-Betriebssystem.

Wenn Sie beispielsweise eine AddDevice- Rückrufroutine definieren möchten, die MyAddDevice<heißt, verwenden Sie den DRIVER_ADD_DEVICE Typ, 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 wird in der Wdm.h-Headerdatei definiert. Um Fehler genauer zu identifizieren, wenn Sie die Codeanalysetools ausführen, müssen Sie der Funktionsdefinition die _Use_decl_annotations_ Anmerkung hinzufügen. Die _Use_decl_annotations_ Anmerkung stellt sicher, dass die Anmerkungen, die auf den Funktionstyp DRIVER_ADD_DEVICE in der Headerdatei angewendet werden, verwendet 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 (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL-	Aufgerufen bei PASSIVE_LEVEL (siehe Abschnitt "Hinweise").

Freigeben über