RTL_RUN_ONCE_INIT_FN Rückruffunktion (ntddk.h)
Die RunOnceInitialization Routine führt einen einmaligen Initialisierungsvorgang aus.
Syntax
ULONG /* LOGICAL */
NTAPI
RTL_RUN_ONCE_INIT_FN (
_Inout_ PRTL_RUN_ONCE RunOnce,
_Inout_opt_ PVOID Parameter,
_Inout_opt_ PVOID *Context
);
typedef RTL_RUN_ONCE_INIT_FN *PRTL_RUN_ONCE_INIT_FN;
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 Parameter Wert, 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 anzuzeigen, und gibt null zurück, um fehler anzuzeigen.
Bemerkungen
Eine vom Treiber implementierte RunOnceInitialization Routine führt treiberspezifische Initialisierung durch und schreibt dann die Initialisierungsdaten an den Speicherspeicherort, auf den der Context Parameter verweist. Treiber verwenden die RtlRunOnceExecuteOnce Routine, um einen einmaligen Aufruf an eine RunOnceInitialization Routine durchzuführen. Das Betriebssystem garantiert, dass die RunOnceInitialization- Routine nicht zweimal für denselben Wert des RunOnce-Parameters aufgerufen wird.
Eine kleine Anzahl von Bits in niedriger Reihenfolge in der Position, auf die durch den parameter Context verwiesen wird, sind für die Verwendung durch das Betriebssystem reserviert. Die RunOnceInitialization Routine Des Treibers sollte diese reservierten Bits im Ausgabewert auf Null festlegen, in den sie schreibt in *Context. Die in Ntddk.h definierte RTL_RUN_ONCE_CTX_RESERVED_BITS Konstante gibt die Anzahl der reservierten Bits mit niedriger Reihenfolge an. Derzeit ist RTL_RUN_ONCE_CTX_RESERVED_BITS als zwei definiert, was bedeutet, dass der Treiber die zwei am wenigsten signifikanten Bits des PVOID-Werts festlegen muss, auf den Context auf Null verweist.
Beispiele
Um eine RunOnceInitialization- Rückrufroutine zu definieren, müssen Sie zuerst eine Funktionsdeklaration bereitstellen, die den Typ der rückrufroutinen identifiziert, die Sie definieren. 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 RunOnceInitialization- Rückrufroutine definieren möchten, die MyRunOnceInitializationheißt, verwenden Sie den RTL_RUN_ONCE_INIT_FN Typ, 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 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 RTL_RUN_ONCE_INIT_FN 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 |
|---|---|
| mindestens unterstützte Client- | Treiber können die RunOnceInitialization-Routine nur unter Windows Vista und höheren Versionen von Windows implementieren. |
| Zielplattform- | Desktop |
| Header- | ntddk.h (enthalten Ntddk.h, Ntifs.h) |
| IRQL- | Wird bei IRQL-<= APC_LEVEL aufgerufen. |