NtNotifyChangeKey - NtDoc

Native API online documentation, based on the System Informer (formerly Process Hacker) phnt headers 
#ifndef _NTREGAPI_H

/**
 * Notifies of changes to a registry key.
 *
 * @param KeyHandle Handle to the registry key.
 * @param Event Optional handle to an event to be signaled.
 * @param ApcRoutine Optional APC routine to be called.
 * @param ApcContext Optional context for the APC routine.
 * @param IoStatusBlock Pointer to an IO status block.
 * @param CompletionFilter Filter for the types of changes to notify.
 * @param WatchTree Whether to watch the entire tree.
 * @param Buffer Optional buffer for change data.
 * @param BufferSize Size of the buffer.
 * @param Asynchronous Whether the operation is asynchronous.
 * @return NTSTATUS Successful or errant status.
 */
NTSYSCALLAPI
NTSTATUS
NTAPI
NtNotifyChangeKey(
    _In_ HANDLE KeyHandle,
    _In_opt_ HANDLE Event,
    _In_opt_ PIO_APC_ROUTINE ApcRoutine,
    _In_opt_ PVOID ApcContext,
    _Out_ PIO_STATUS_BLOCK IoStatusBlock,
    _In_ ULONG CompletionFilter,
    _In_ BOOLEAN WatchTree,
    _Out_writes_bytes_opt_(BufferSize) PVOID Buffer,
    _In_ ULONG BufferSize,
    _In_ BOOLEAN Asynchronous
    );

#endif

View code on GitHub
#ifndef _NTZWAPI_H

NTSYSCALLAPI
NTSTATUS
NTAPI
ZwNotifyChangeKey(
    _In_ HANDLE KeyHandle,
    _In_opt_ HANDLE Event,
    _In_opt_ PIO_APC_ROUTINE ApcRoutine,
    _In_opt_ PVOID ApcContext,
    _Out_ PIO_STATUS_BLOCK IoStatusBlock,
    _In_ ULONG CompletionFilter,
    _In_ BOOLEAN WatchTree,
    _Out_writes_bytes_opt_(BufferSize) PVOID Buffer,
    _In_ ULONG BufferSize,
    _In_ BOOLEAN Asynchronous
    );

#endif

View code on GitHub
// ntifs.h

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

View the official Windows Driver Kit DDI reference

NtDoc

No description available.

Edit description on GitHub

Windows Driver Kit DDI reference (nf-ntifs-zwnotifychangekey)

ZwNotifyChangeKey function

Description

The ZwNotifyChangeKey routine allows a driver to request notification when a registry key changes.

Parameters

KeyHandle [in]

Handle to the key to register a notification routine for. This handle is created by a successful call to ZwCreateKey or ZwOpenKey. The caller must have specified KEY_NOTIFY access.

Event [in, optional]

Optional handle to a caller-created event to be set to the Signaled state when the operation completes. If not NULL, the caller is placed into a wait state until the operation succeeds, at which time the event is set to the Signaled state.

ApcRoutine [in, optional]

Pointer to a caller-supplied APC routine to run after the operation completes. This parameter is optional and can be NULL.

ApcContext [in, optional]

Pointer to pass as an argument to the APC routine that ApcRoutine points to. This argument is required if ApcRoutine isn't NULL, and must be cast to type PVOID. Otherwise, if ApcRoutine is NULL, set this parameter to NULL, too.

The meaning of this parameter depends on whether the routine is called from kernel mode or from user mode:

IoStatusBlock [out]

Pointer to an IO_STATUS_BLOCK structure that contains the final status and information about the operation. For successful calls that return data, the number of bytes written to Buffer is supplied in IoStatusBlock->Information.

CompletionFilter [in]

Bitmask of operations that cause the driver to be notified. Specify one or more of the following flags:

Value Meaning
REG_NOTIFY_CHANGE_NAME Notify the caller if a subkey is added or deleted.
REG_NOTIFY_CHANGE_ATTRIBUTES Notify the caller of changes to the attributes of the key, such as the security descriptor information.
REG_NOTIFY_CHANGE_LAST_SET Notify the caller of changes to a value of the key. This can include adding or deleting a value, or changing an existing value. (The caller receives no notification if the new value written to the key matches the previous value of the key.)
REG_NOTIFY_CHANGE_SECURITY Notify the caller of changes to the security descriptor of the key.

WatchTree [in]

If TRUE, the driver is notified about changes to all subkeys of the specified key. If FALSE, the driver is only notified for changes to the specified key.

Buffer [out, optional]

Reserved. Specify NULL.

BufferSize [in]

Reserved. Specify zero.

Asynchronous [in]

If FALSE, the routine does not return until the specified event occurs. If TRUE, the routine returns immediately.

Return value

The ZwNotifyChangeKey routine returns STATUS_SUCCESS on success, or the appropriate NTSTATUS value otherwise. If the caller specifies TRUE for the Asynchronous parameter, and the event has not yet occurred, the routine returns STATUS_PENDING.

Remarks

ZwNotifyChangeKey monitors a registry key for changes and notifies the caller when modifications occur.

The routine monitors the specified key (and optionally its subtree) for changes based on the CompletionFilter flags. When a change occurs, the system notifies the caller via event signaling, APC callback, or synchronous completion.

This is a one-time notification. After a registry change triggers the notification, you must call ZwNotifyChangeKey again to continue monitoring.

The key must be opened with KEY_NOTIFY access before calling this routine.

For asynchronous operation (Asynchronous = TRUE):

For synchronous operation (Asynchronous = FALSE):

The notification session ends when KeyHandle is closed.

Note: CompletionFilter and WatchTree are set on the first call and apply to all subsequent calls using the same KeyHandle. These parameters are ignored on subsequent calls.

Registry notifications hold handles that will prevent hive unload operations (such as RegUnloadKey) until closed. Currently, there is no mechanism for a driver to have a notification that won’t block RegUnloadKey. Drivers can try to proactively cancel notifications when the monitored process or user session ends to avoid blocking legitimate hive management operations.

If the call to the ZwNotifyChangeKey function occurs in user mode, you should use the name "NtNotifyChangeKey" instead of "ZwNotifyChangeKey".

For calls from kernel-mode drivers, the NtXxx and ZwXxx versions of a Windows Native System Services routine can behave differently in the way that they handle and interpret input parameters. For more information about the relationship between the NtXxx and ZwXxx versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.

See also

IO_STATUS_BLOCK

WORK_QUEUE_ITEM

WORK_QUEUE_TYPE

ZwCreateKey

ZwOpenKey

View the official Windows Driver Kit DDI reference

Edit description on GitHub

NTinternals.net (undocumented.ntinternals.net)

This function is documented in Windows Driver Kit.

See also

Edit description on GitHub