RTL_RUN_ONCE_INIT_FN Rückruffunktion (ntddk.h)

Artikel
03/08/2023

Die RunOnceInitialization-Routine führt einen einmaligen Initialisierungsvorgang aus.

Syntax

RTL_RUN_ONCE_INIT_FN (
    _Inout_ PRTL_RUN_ONCE RunOnce,
    _Inout_opt_ PVOID Parameter,
    _Inout_opt_ PVOID *Context
  );

Parameter

[in, out] RunOnce

Ein Zeiger auf die RTL_RUN_ONCE einmalige Initialisierungsstruktur, die der Treiber zuvor als Parameter an die RtlRunOnceExecuteOnce-Routine übergeben hat, die diese RunOnceInitialization-Routine aufgerufen hat.

[in, out] Parameter

Der Parameterwert , den der Treiber an die RtlRunOnceExecuteOnce-Routine übergeben hat, die diese RunOnceInitialization-Routine aufgerufen hat.

[out] Context

Ein Zeiger auf eine PVOID-Variable, in die die Routine die Initialisierungsdaten schreibt.

Rückgabewert

Die RunOnceInitialization-Routine gibt einen Wert ungleich null zurück, um den Erfolg anzugeben, und gibt null zurück, um einen Fehler anzuzeigen.

Hinweise

Eine vom Treiber implementierte RunOnceInitialization-Routine führt eine treiberspezifische Initialisierung durch und schreibt dann die Initialisierungsdaten in den Speicherspeicherort, auf den der Context-Parameter verweist. Treiber verwenden die RtlRunOnceExecuteOnce-Routine , um einen einmaligen Aufruf einer RunOnceInitialization-Routine durchzuführen. Das Betriebssystem garantiert, dass die RunOnceInitialization-Routine nicht zweimal für den gleichen Wert des RunOnce-Parameters aufgerufen wird.

Eine kleine Anzahl von Bits niedriger Reihenfolge an der Position, auf die der Context-Parameter verweist, ist für die Verwendung durch das Betriebssystem reserviert. Die RunOnceInitialization-Routine Ihres Treibers sollte diese reservierten Bits im Ausgabewert, den er in *Context schreibt, auf Null festlegen. Die in Ntddk.h definierte RTL_RUN_ONCE_CTX_RESERVED_BITS-Konstante gibt die Anzahl der reservierten Bits niedriger Reihenfolge an. Derzeit ist RTL_RUN_ONCE_CTX_RESERVED_BITS als zwei definiert. Dies bedeutet, dass der Treiber die zwei am wenigsten signifikanten Bits des PVOID-Werts festlegen muss, auf den Kontext zeigt.

Beispiele

Um eine RunOnceInitialization-Rückrufroutine zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der Rückrufroutine identifiziert, die Sie definieren. 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 Voraussetzung für das Schreiben von Treibern für das Windows-Betriebssystem.

Um beispielsweise eine RunOnceInitialization-Rückrufroutine mit dem Namen MyRunOnceInitializationzu definieren, verwenden Sie den typ RTL_RUN_ONCE_INIT_FN, wie in diesem Codebeispiel gezeigt:

RTL_RUN_ONCE_INIT_FN MyRunOnceInitialization;

Implementieren Sie dann Ihre Rückrufroutine wie folgt:

_Use_decl_annotations_
ULONG 
  MyRunOnceInitialization(
    PRTL_RUN_ONCE  RunOnce,
    PVOID  Parameter,
    PVOID  *Context
    )
  {
      // Function body
  }

Der RTL_RUN_ONCE_INIT_FN Funktionstyp ist in der Wdm.h-Headerdatei 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 RTL_RUN_ONCE_INIT_FN 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 Verhalten von Funktionen mit Anmerkungen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Treiber können die RunOnceInitialization-Routine nur unter Windows Vista und höheren Versionen von Windows implementieren.
Zielplattform	Desktop
Kopfzeile	ntddk.h (include Ntddk.h, Ntifs.h)
IRQL	Wird bei IRQL <= APC_LEVEL aufgerufen.