Funzione ZwNotifyChangeKey (ntifs.h)

Articolo
12/22/2024

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.

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

Valore	Significato
REG_NOTIFY_CHANGE_NAME	Notificare al chiamante se viene aggiunta o eliminata una sottochiave.
REG_NOTIFY_CHANGE_ATTRIBUTES	Notificare al chiamante le modifiche apportate agli attributi della chiave, ad esempio le informazioni sul descrittore di sicurezza.
REG_NOTIFY_CHANGE_LAST_SET	Notificare al chiamante le modifiche apportate a un valore della chiave. Ciò può includere l'aggiunta o l'eliminazione di un valore o la modifica di un valore esistente. Il chiamante non riceve alcuna notifica se il nuovo valore scritto nella chiave corrisponde al valore precedente della chiave.
REG_NOTIFY_CHANGE_SECURITY	Notificare al chiamante le modifiche apportate al descrittore di sicurezza della chiave.

[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

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

Requisito	Valore
client minimo supportato	Windows 2000
piattaforma di destinazione	Universale
intestazione	ntifs.h (include Ntifs.h)
libreria	NtosKrnl.lib
dll	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
regole di conformità DDI	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)

Vedere anche

Condividi tramite