ZwNotifyChangeKey-Funktion (ntifs.h)

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

Behandeln Sie den Schlüssel, um eine Benachrichtigungsroutine zu registrieren. Dieses Handle wird durch einen erfolgreichen Aufruf von ZwCreateKey oder ZwOpenKeyerstellt. Der Aufrufer muss KEY_NOTIFY Zugriff angegeben haben.

[in, optional] Event

Optionaler Handle für ein vom Aufrufer erstelltes Ereignis, das auf den Signalzustand festgelegt werden soll, wenn der Vorgang abgeschlossen ist. Wenn nicht NULL, wird der Aufrufer in einen Wartezustand versetzt, bis der Vorgang erfolgreich ist, zu dem zeitpunkt, zu dem das Ereignis auf den Zustand "Signaled" festgelegt ist.

[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.

• Legen Sie für einen Kernelmodusaufruf diesen Parameter auf einen Zeiger auf eine WORK_QUEUE_ITEM-Struktur fest.

[in, optional] ApcContext

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

Die Bedeutung dieses Parameters hängt davon ab, ob die Routine aus dem Kernelmodus oder vom 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

Zeigen Sie auf eine IO_STATUS_BLOCK Struktur, die den endgültigen Status und Informationen zum Vorgang enthält. Bei erfolgreichen Aufrufen, die Daten zurückgeben, wird die Anzahl der in Buffer geschriebenen Bytes in IoStatusBlock-->Informationangegeben.

[in] CompletionFilter

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

[in] WatchTree

Wenn TRUE, wird der Treiber über Änderungen an allen Unterschlüsseln des angegebenen Schlüssels benachrichtigt. Wenn FALSE, wird der Treiber nur für Änderungen am angegebenen Schlüssel benachrichtigt.

[out, optional] Buffer

Reserviert. Geben Sie NULL an.

[in] BufferSize

Reserviert. Geben Sie Null an.

[in] Asynchronous

Wenn FALSE, wird die Routine erst zurückgegeben, wenn das angegebene Ereignis auftritt. Wenn WAHR, wird die Routine sofort zurückgegeben.

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 parameter Asynchronous angibt und das Ereignis noch nicht aufgetreten ist, gibt die Routine STATUS_PENDING zurück.

Bemerkungen

ZwNotifyChangeKey überwacht einen Registrierungsschlüssel auf Änderungen und benachrichtigt den Aufrufer, wenn Änderungen vorgenommen werden.

Die Routine überwacht den angegebenen Schlüssel (und optional seine Unterstruktur) auf Änderungen basierend auf den CompletionFilter-Flags . Wenn eine Änderung auftritt, benachrichtigt das System den Aufrufer über Ereignissignalisierung, APC-Rückruf oder synchrone Vervollständigung.

Dies ist eine einmalige Benachrichtigung. Nachdem eine Registrierungsänderung die Benachrichtigung ausgelöst hat, müssen Sie ZwNotifyChangeKey erneut aufrufen, um die Überwachung fortzusetzen.

Der Schlüssel muss mit KEY_NOTIFY Zugriff geöffnet werden, bevor diese Routine aufgerufen wird.

Für asynchronen Vorgang (asynchron = TRUE):

• Wenn ereignis angegeben wird, wird es signalisiert, wenn Änderungen auftreten. Wenn das Ereignis NULL ist, wird KeyHandle auf den Signalzustand festgelegt.
• Wenn ApcRoutine angegeben ist, wird sie mit ApcContext und IoStatusBlock aufgerufen.
• Wenn keines angegeben ist, wird der KeyHandle selbst signalierbar.

Für synchronen Vorgang (asynchron = FALSE):

• Der Aufruf blockiert, bis eine Änderung erfolgt.
• Ereignis-, ApcRoutine- und ApcContext-Parameter werden ignoriert.

Die Benachrichtigungssitzung endet, wenn KeyHandle geschlossen wird.

Hinweis: CompletionFilter und WatchTree werden für den ersten Aufruf festgelegt und gelten für alle nachfolgenden Aufrufe mit demselben KeyHandle. Diese Parameter werden bei nachfolgenden Aufrufen ignoriert.

Registrierungsbenachrichtigungen enthalten Handles, die strukturieren Unload-Vorgänge (z. B. RegUnloadKey) bis zum Schließen verhindern. Derzeit gibt es keinen Mechanismus für einen Treiber, um eine Benachrichtigung zu erhalten, die RegUnloadKey nicht blockiert. Treiber können versuchen, Benachrichtigungen proaktiv abzubrechen, wenn der überwachte Prozess oder die Benutzersitzung endet, um zu verhindern, dass legitime Strukturverwaltungsvorgänge blockiert werden.

Wenn der Aufruf der ZwNotifyChangeKey--Funktion im Benutzermodus auftritt, 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 behandeln und interpretieren. Weitere Informationen zur Beziehung zwischen den NtXxx und ZwXxx- Versionen einer Routine finden Sie unter Using Nt and Zw Versions of the Native System Services Routines.

Anforderungen

Siehe auch

IO_STATUS_BLOCK

WORK_QUEUE_ITEM

WORK_QUEUE_TYPE

ZwCreateKey-

ZwOpenKey-