DRIVER_INITIALIZE Rückruffunktion (wdm.h)

Artikel
10.02.2025

DRIVER_INITIALIZE ist die Typdefinition des Einstiegspunkts für die Treiberinitialisierung, der konventionell DriverEntrygenannt wird. Dies ist die erste Routine, die aufgerufen wird, nachdem ein Treiber geladen wurde.

Syntax

C++

DRIVER_INITIALIZE DriverInitialize;

NTSTATUS DriverInitialize(
  [in] _DRIVER_OBJECT *DriverObject,
  [in] PUNICODE_STRING RegistryPath
)
{...}

Parameter

[in] DriverObject

Ein Zeiger auf die DRIVER_OBJECT Struktur des Treibers.

[in] RegistryPath

Ein Zeiger auf eine gezählte Unicode-Zeichenfolge, die den Pfad zum Registrierungsschlüssel des Treibers angibt.

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

Der DriverObject Parameter stellt die DriverEntry Routine mit einem Zeiger auf das Treiberobjekt des Treibers bereit, das vom E/A-Manager zugewiesen wird. Die DriverEntry Routine muss das Treiberobjekt mit Einstiegspunkten für die Standardroutinen des Treibers ausfüllen.

Der DriverObject Zeiger gewährt dem Treiber Zugriff auf DriverObject->HardwareDatabase-, die auf eine gezählte Unicode-Zeichenfolge verweist, die einen Pfad zur \Registry\Machine\Hardware Struktur der Registrierung angibt.

Die Registrierungspfadzeichenfolge, auf die von RegistryPath- verwiesen wird, ist das Formular \Registry\Machine\System\CurrentControlSet\Services\DriverName. Ein Treiber kann diesen Pfad verwenden, um treiberspezifische Informationen zu speichern; siehe Registrierungsschlüssel für Treiber. Die DriverEntry Routine sollte eine Kopie der Unicode-Zeichenfolge speichern, nicht der Zeiger, da der E/A-Manager den RegistryPath Puffer freigibt, nachdem DriverEntry- zurückgegeben wurde.

Weitere Informationen zum Implementieren einer DriverEntry Routine finden Sie unter Schreiben einer DriverEntry Routine.

Obwohl es möglich ist, diese Routine etwas anderes als DriverEntryzu benennen, wird dies nicht empfohlen. Die von DDK bereitgestellten Buildtools informieren den Linker automatisch darüber, dass der Einstiegspunkt des Treibers DriverEntry-genannt wird. Wenn Sie also der Routine einen anderen Namen geben, müssen Sie die Buildtools ändern. Weitere Informationen zu Buildtools finden Sie unter Building a Driver.

Beispiele

Um eine DriverEntry- 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.

Um eine DriverEntry- Rückrufroutine zu definieren, verwenden Sie den DRIVER_INITIALIZE Typ, wie in diesem Codebeispiel gezeigt:

C++

DRIVER_INITIALIZE DriverEntry;

Implementieren Sie dann Ihre Rückrufroutine wie folgt:

C++

_Use_decl_annotations_
NTSTATUS 
  DriverEntry( 
    struct _DRIVER_OBJECT  *DriverObject,
    PUNICODE_STRING  RegistryPath 
    )
  {
      // Function body
  }

Der DRIVER_INITIALIZE 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_INITIALIZE 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 Mcd.h, Ntddk.h, Ntifs.h, Wudfwdm.h)
IRQL-	Wird bei PASSIVE_LEVEL aufgerufen.

Siehe auch

DRIVER_OBJECT

Freigeben über