ZwNotifyChangeKey-Funktion (ntifs.h)

Artikel
02/26/2024

Die ZwNotifyChangeKey-Routine ermöglicht es einem Treiber, eine Benachrichtigung anzufordern, wenn sich ein Registrierungsschlüssel ändert.

Syntax

NTSYSAPI NTSTATUS ZwNotifyChangeKey(
  [in]            HANDLE           KeyHandle,
  [in, optional]  HANDLE           Event,
  [in, optional]  PIO_APC_ROUTINE  ApcRoutine,
  [in, optional]  PVOID            ApcContext,
  [out]           PIO_STATUS_BLOCK IoStatusBlock,
  [in]            ULONG            CompletionFilter,
  [in]            BOOLEAN          WatchTree,
  [out, optional] PVOID            Buffer,
  [in]            ULONG            BufferSize,
  [in]            BOOLEAN          Asynchronous
);

Parameter

[in] KeyHandle

Handle mit dem Schlüssel, für den eine Benachrichtigungsroutine registriert werden soll. Dieses Handle wird durch einen erfolgreichen Aufruf von ZwCreateKey oder ZwOpenKey erstellt. Der Aufrufer muss KEY_NOTIFY Zugriff angegeben haben.

[in, optional] Event

Optionales Handle für ein vom Aufrufer erstelltes Ereignis, das nach Abschluss des Vorgangs auf den Signalzustand festgelegt werden soll. Wenn nicht NULL, wird der Aufrufer in einen Wartezustand versetzt, bis der Vorgang erfolgreich ist. Zu diesem Zeitpunkt wird das Ereignis auf den Signalzustand festgelegt.

[in, optional] ApcRoutine

Zeiger auf eine vom Aufrufer bereitgestellte APC-Routine, die nach Abschluss des Vorgangs ausgeführt werden soll. Dieser Parameter ist optional und kann NULL sein.

[in, optional] ApcContext

Zeiger, der als Argument an die APC-Routine übergeben soll, auf die ApcRoutine verweist. Dieses Argument ist erforderlich, wenn ApcRoutine nicht NULL ist und in den Typ PVOID umgewandelt werden muss. Wenn ApcRoutine NULL ist, legen Sie diesen Parameter andernfalls ebenfalls auf NULL fest.

Die Bedeutung dieses Parameters hängt davon ab, ob die Routine aus dem Kernelmodus oder aus dem Benutzermodus aufgerufen wird:

Legen Sie für einen Kernelmodusaufruf diesen Parameter auf einen der folgenden WORK_QUEUE_TYPE-Enumerationswerte fest:
- CriticalWorkQueue
- DelayedWorkQueue
Bei einem Benutzermodusaufruf verweist dieser Parameter auf einen vom Aufrufer angegebenen Kontext für die APC-Routine.

[out] IoStatusBlock

Zeiger auf eine IO_STATUS_BLOCK-Struktur, die die endgültige status und Informationen zum Vorgang enthält. Für erfolgreiche Aufrufe, die Daten zurückgeben, wird die Anzahl der in Buffer geschriebenen Bytes in IoStatusBlock-Information> angegeben.

[in] CompletionFilter

Bitmaske von Vorgängen, die dazu führen, dass der Treiber benachrichtigt wird. Geben Sie mindestens eins der folgenden Flags an:

Wert	Bedeutung
REG_NOTIFY_CHANGE_NAME	Benachrichtigen Sie den Aufrufer, wenn ein Unterschlüssel hinzugefügt oder gelöscht wird.
REG_NOTIFY_CHANGE_ATTRIBUTES	Benachrichtigen Sie den Aufrufer über Änderungen an den Attributen des Schlüssels, z. B. die Sicherheitsbeschreibungsinformationen.
REG_NOTIFY_CHANGE_LAST_SET	Benachrichtigen Sie den Aufrufer über Änderungen an einem Wert des Schlüssels. Dies kann das Hinzufügen oder Löschen eines Werts oder das Ändern eines vorhandenen Werts umfassen. (Der Aufrufer erhält keine Benachrichtigung, wenn der in den Schlüssel geschriebene neue Wert mit dem vorherigen Wert des Schlüssels übereinstimmt.)
REG_NOTIFY_CHANGE_SECURITY	Benachrichtigen Sie den Aufrufer über Änderungen am Sicherheitsdeskriptor des Schlüssels.

[in] WatchTree

True gibt an, dass der Treiber über Änderungen an allen Unterschlüsseln des angegebenen Schlüssels benachrichtigt wird. Bei FALSE wird der Treiber nur bei Änderungen am angegebenen Schlüssel benachrichtigt.

[out, optional] Buffer

Reserviert. Geben Sie NULL an.

[in] BufferSize

Reserviert. Geben Sie null an.

[in] Asynchronous

False gibt die Routine erst zurück, wenn das angegebene Ereignis eintritt. Wenn TRUE, gibt die Routine sofort zurück.

Rückgabewert

Die ZwNotifyChangeKey-Routine gibt STATUS_SUCCESS bei Erfolg oder andernfalls den entsprechenden NTSTATUS-Wert zurück. Wenn der Aufrufer TRUE für den Asynchronous-Parameter angibt und das Ereignis noch nicht aufgetreten ist, gibt die Routine STATUS_PENDING zurück.

Hinweise

Wenn der Aufruf der ZwNotifyChangeKey-Funktion im Benutzermodus erfolgt, sollten Sie den Namen "NtNotifyChangeKey" anstelle von "ZwNotifyChangeKey" verwenden.

Bei Aufrufen von Kernelmodustreibern können sich die NtXxx - und ZwXxx-Versionen einer Windows Native System Services-Routine anders verhalten, wie sie Eingabeparameter verarbeiten und interpretieren. Weitere Informationen zur Beziehung zwischen den Nt Xxx- und ZwXxx-Versionen einer Routine finden Sie unter Verwenden von Nt- und Zw-Versionen der systemeigenen Systemdienstroutinen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000
Zielplattform	Universell
Header	ntifs.h (include Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)

Weitere Informationen