Funzione ZwNotifyChangeKey (ntifs.h)

La routine ZwNotifyChangeKey consente a un driver di richiedere la notifica quando viene modificata una chiave del Registro di sistema.

Sintassi

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
);

Parametri

[in] KeyHandle

Handle per la chiave per cui registrare una routine di notifica. Questo handle viene creato da una chiamata riuscita a ZwCreateKey o ZwOpenKey. Il chiamante deve avere specificato KEY_NOTIFY accesso.

[in, optional] Event

Handle facoltativo per un evento creato dal chiamante da impostare sullo stato Segnalato al termine dell'operazione. Se non NULL, il chiamante viene inserito in uno stato di attesa fino a quando l'operazione non riesce, al momento in cui l'evento viene impostato sullo stato Segnalato.

[in, optional] ApcRoutine

Puntatore a una routine APC fornita dal chiamante da eseguire al termine dell'operazione. Questo parametro è facoltativo e può essere NULL.

• Per una chiamata in modalità kernel, impostare questo parametro su un puntatore a uno struct WORK_QUEUE_ITEM

[in, optional] ApcContext

Puntatore a cui passare come argomento la routine APC a cui ApcRoutine punta. Questo argomento è obbligatorio se ApcRoutine non è NULL e deve essere eseguito il cast al tipo PVOID. In caso contrario, se ApcRoutine è NULL, impostare anche questo parametro su NULL.

Il significato di questo parametro dipende dal fatto che la routine venga chiamata dalla modalità kernel o dalla modalità utente:

• Per una chiamata in modalità kernel, impostare questo parametro su uno dei valori di enumerazione WORK_QUEUE_TYPE seguenti:

  • CriticalWorkQueue
  • DelayedWorkQueue

• Per una chiamata in modalità utente, questo parametro punta a un contesto specificato dal chiamante per la routine APC.

[out] IoStatusBlock

Puntatore a una struttura IO_STATUS_BLOCK che contiene lo stato finale e le informazioni sull'operazione. Per le chiamate riuscite che restituiscono dati, il numero di byte scritti in buffer viene fornito in IoStatusBlock->Information.

[in] CompletionFilter

Maschera di bit delle operazioni che causano la notifica del driver. Specificare uno o più flag seguenti:

[in] WatchTree

Se TRUE, il driver riceve una notifica sulle modifiche apportate a tutte le sottochiavi della chiave specificata. Se FALSE, il driver riceve una notifica solo per le modifiche apportate alla chiave specificata.

[out, optional] Buffer

Riservato. Specificare NULL.

[in] BufferSize

Riservato. Specificare zero.

[in] Asynchronous

Se FALSE, la routine non restituisce fino a quando non si verifica l'evento specificato. Se TRUE, la routine restituisce immediatamente.

Valore restituito

La routine ZwNotifyChangeKey restituisce STATUS_SUCCESS in caso di esito positivo o il valore NTSTATUS appropriato in caso contrario. Se il chiamante specifica TRUE per il parametro asincrono e l'evento non si è ancora verificato, la routine restituisce STATUS_PENDING.

Osservazioni

ZwNotifyChangeKey monitora una chiave del Registro di sistema per le modifiche e invia una notifica al chiamante quando si verificano modifiche.

La routine monitora la chiave specificata (e facoltativamente il relativo sottoalbero) per le modifiche in base ai flag CompletionFilter . Quando si verifica una modifica, il sistema invia una notifica al chiamante tramite segnalazione di eventi, callback APC o completamento sincrono.

Si tratta di una notifica una tantum. Dopo che una modifica del Registro di sistema attiva la notifica, è necessario chiamare di nuovo ZwNotifyChangeKey per continuare il monitoraggio.

La chiave deve essere aperta con KEY_NOTIFY accesso prima di chiamare questa routine.

Per l'operazione asincrona (Asincrona = TRUE):

• Se si specifica Event , verrà segnalato quando si verificano modifiche. Se Event è NULL, KeyHandle viene impostato sullo stato Segnalato.
• Se si specifica ApcRoutine , verrà chiamato con ApcContext e IoStatusBlock.
• Se nessuno dei due elementi viene specificato, keyHandle diventa segnalabile.

Per l'operazione sincrona (Asincrona = FALSE):

• La chiamata si blocca fino a quando non si verifica una modifica.
• I parametri Event, ApcRoutine e ApcContext vengono ignorati.

La sessione di notifica termina quando KeyHandle viene chiuso.

Nota: CompletionFilter e WatchTree vengono impostati nella prima chiamata e si applicano a tutte le chiamate successive che usano lo stesso KeyHandle. Questi parametri vengono ignorati nelle chiamate successive.

Le notifiche del Registro di sistema contengono handle che impediranno operazioni di scaricamento hive (ad esempio RegUnloadKey) fino alla chiusura. Attualmente, non esiste alcun meccanismo per un driver per avere una notifica che non blocca RegUnloadKey. I driver possono provare ad annullare in modo proattivo le notifiche quando termina il processo monitorato o la sessione utente per evitare di bloccare le operazioni di gestione legittime di Hive.

Se la chiamata alla funzione ZwNotifyChangeKey si verifica in modalità utente, è necessario usare il nome "NtNotifyChangeKey" anziché "ZwNotifyChangeKey".

Per le chiamate da driver in modalità kernel, le NtXxx e ZwXxx versioni di una routine di Windows Native System Services possono comportarsi in modo diverso nel modo in cui gestiscono e interpretano i parametri di input. Per altre informazioni sulla relazione tra le versioni NtXxx e ZwXxx di una routine, vedere Using Nt and Zw Versions of the Native System Services Routines.

Fabbisogno

Vedere anche

IO_STATUS_BLOCK

WORK_QUEUE_ITEM

WORK_QUEUE_TYPE

ZwCreateKey

ZwOpenKey