RTL_RUN_ONCE_INIT_FN Rückruffunktion (ntddk.h)

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

Weitere Informationen

RTL_RUN_ONCE

RtlRunOnceBeginInitialize

RtlRunOnceComplete

RtlRunOnceExecuteOnce

RtlRunOnceInitialize