EX_CALLBACK_FUNCTION Rückruffunktion (wdm.h)
Die RegistryCallback Routine eines Filtertreibers kann einen Registrierungsvorgang überwachen, blockieren oder ändern.
Syntax
EX_CALLBACK_FUNCTION ExCallbackFunction;
NTSTATUS ExCallbackFunction(
[in] PVOID CallbackContext,
[in, optional] PVOID Argument1,
[in, optional] PVOID Argument2
)
{...}
Parameter
[in] CallbackContext
Der Wert, den der Treiber als Context Parameter an CmRegisterCallback oder CmRegisterCallbackEx, wenn er diese RegistryCallback-Routine registriert hat.
[in, optional] Argument1
Ein REG_NOTIFY_CLASS-typed-Wert, der den Typ des ausgeführten Registrierungsvorgangs angibt und ob die RegistryCallback- routine vor oder nach dem Ausführen des Registrierungsvorgangs aufgerufen wird.
[in, optional] Argument2
Ein Zeiger auf eine Struktur, die Informationen enthält, die für den Registrierungsvorgangstyp spezifisch sind. Der Strukturtyp hängt vom REG_NOTIFY_CLASS-typed-Wert für Argument1ab, wie in der folgenden Tabelle dargestellt. Informationen dazu, welche REG_NOTIFY_CLASS-Typ-Werte für welche Betriebssystemversionen verfügbar sind, finden Sie unter REG_NOTIFY_CLASS.
Ab Windows 7 wird die tatsächliche Datenstruktur übergeben, wenn die Notify-Klasse regNtPreCreateKeyEx oder RegNtPreOpenKeyEx die V1-Version dieser Struktur, REG_CREATE_KEY_INFORMATION_V1 oder REG_OPEN_KEY_INFORMATION_V1ist. Überprüfen Sie das Reservierte Element, um die Version der Struktur zu ermitteln.
| Versionsnummer | Strukturname |
|---|---|
| 0 | REG_CREATE_KEY_INFORMATION und REG_OPEN_KEY_INFORMATION |
| 1 | REG_CREATE_KEY_INFORMATION_V1 und REG_OPEN_KEY_INFORMATION_V1 |
Rückgabewert
Weitere Informationen dazu, wann eine RegistryCallback Routine jeden dieser Statuswerte zurückgeben sollte, finden Sie unter Filtern von Registrierungsaufrufen.
Bemerkungen
Um über Registrierungsvorgänge benachrichtigt zu werden, kann eine Kernelmoduskomponente (z. B. die Treiberkomponente eines Antivirensoftwarepakets) CmRegisterCallback- oder CmRegisterCallbackEx- aufrufen, um eine RegistryCallback Routine zu registrieren.
Die RegistryCallback Routine kann den Inhalt der Eingabe- und Ausgabepuffer prüfen, die für Registrierungsvorgänge bereitgestellt werden. Ein Registrierungsvorgang kann von einer Benutzermodusanwendung initiiert werden, die eine Registrierungsroutine für den Benutzermodus aufruft (z. B. RegCreateKeyEx oder RegOpenKeyEx) oder von einem Treiber, der eine Kernelmodusregistrierungsroutine aufruft (z. B. ZwCreateKey oder ZwOpenKey). Ein Eingabepuffer ist ein Vom Initiator bereitgestellter Speicherpuffer, aus dem die Registrierung Eingabedaten für den Vorgang liest. Ein Ausgabepuffer ist ein Vom Initiator bereitgestellter Puffer, in den die Registrierung Ausgabedaten schreibt, die vom Initiator angefordert werden.
Bevor Sie die RegistryCallback Routine aufrufen, erfassen die Kernelsonden (zur Überprüfung der Ausrichtung und Barrierefreiheit) alle Member der Argument2 Strukturen, die auf Ausgabepuffer im Benutzermodusspeicher verweisen, aber keine Ausgabepuffer im Systemspeicher erfassen. Die Rückrufroutine muss den Zugriff eines Ausgabepuffers in einen versuchen,/außer Block zu verwenden. Wenn die Rückrufroutine einen Ausgabepufferzeiger an eine Systemroutine übergeben muss (z. B. ZwOpenKey), und der Puffer im Benutzermodusspeicher ist, muss die Rückrufroutine zuerst den Puffer erfassen.
Die Behandlung von Eingabepuffern hängt von der Windows-Version ab. Ab Windows 8 erfasst der Kernel alle Eingabepuffer, auf die von Mitgliedern der Argument2 Strukturen im Systemspeicher verwiesen wird, bevor die RegistryCallback- Routine aufgerufen wird. In Windows-Versionen vor Windows 8 testet der Kernel alle Member der Argument2 Strukturen, die auf Eingabepuffer im Benutzermodusspeicher verweisen, erfasst jedoch nur einige dieser Puffer im Systemspeicher. In diesen früheren Versionen von Windows muss die Rückrufroutine den Zugriff eines Eingabepuffers in einen versuchen,/außer Block zu verwenden. Wenn die Rückrufroutine einen Eingabepufferzeiger an eine Systemroutine übergeben muss (z. B. ZwOpenKey), und der Puffer im Benutzermodusspeicher ist, muss die Rückrufroutine zuerst den Puffer erfassen.
In der folgenden Tabelle sind die Anforderungen für Pufferzugriffe durch die RegistryCallback Routine zusammengefasst.
| Puffertyp | Windows-Version | An Rückrufroutine übergebener Pufferzeiger | Sicher für Rückrufroutine, um direkt darauf zuzugreifen? | Sicher, an Systemroutinen zu übergeben (z. B. ZwOpenKey)? |
|---|---|---|---|---|
| Benutzermoduseingabe | Windows 8 und höher | Verweist auf erfasste Daten. | Ja | Ja |
| Benutzermoduseingabe | Windows 7 und frühere Versionen | Verweist auf erfasste Daten oder den ursprünglichen Benutzermoduspuffer. | Nein. Muss unter try/except gelesen werden. | Nein. Muss Kernelspeicher zuweisen, Daten aus dem ursprünglichen Puffer kopieren, unter try/except, und übergeben Sie die kopierten Daten an die Systemroutine. |
| Ausgabe des Benutzermodus | Alle | Verweist auf den ursprünglichen Benutzermoduspuffer. | Nein. Muss unter "try/except" schreiben. | Nein. Muss Kernelspeicher zuweisen, Kernelspeicher an die Systemroutine übergeben und die Ergebnisse wieder in den ursprünglichen Puffer kopieren, unter try/except. |
| Kernelmoduseingabe und -ausgabe | Alle | Verweist auf den ursprünglichen Kernelmoduspuffer. | Ja | Ja |
Weitere Informationen zu RegistryCallback Routinen und Registrierungsfiltertreibern finden Sie unter Filtern von Registrierungsaufrufen.
Ein RegistryCallback- wird bei IRQL = PASSIVE_LEVEL und im Kontext des Threads ausgeführt, der den Registrierungsvorgang ausführt.
Beispiele
Um eine RegistryCallback- 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 RegistryCallback- Rückrufroutine definieren möchten, die MyRegistryCallbackheißt, verwenden Sie den EX_CALLBACK_FUNCTION Typ, wie in diesem Codebeispiel gezeigt:
EX_CALLBACK_FUNCTION MyRegistryCallback;
Implementieren Sie dann Ihre Rückrufroutine wie folgt:
_Use_decl_annotations_
NTSTATUS
MyRegistryCallback(
PVOID CallbackContext,
PVOID Argument1,
PVOID Argument2
)
{
// Function body
}
Der EX_CALLBACK_FUNCTION 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 EX_CALLBACK_FUNCTION 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_annotationsfinden Sie unter Annotating Function Behavior.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Unterstützt ab Windows XP (siehe Abschnitt "Rückgabewert"). |
| Zielplattform- | Desktop |
| Header- | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| IRQL- | Aufgerufen bei PASSIVE_LEVEL (siehe Abschnitt "Hinweise"). |