ZwNotifyChangeKey function (ntifs.h)

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

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

Parameters

[in] KeyHandle

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.

[in, optional] Event

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.

[in, optional] ApcRoutine

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

[in, optional] ApcContext

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:

• For a kernel-mode call, set this parameter to one of the following WORK_QUEUE_TYPE enumeration values:

  • CriticalWorkQueue
  • DelayedWorkQueue

• For a user-mode call, this parameter points to a caller-specified context for the APC routine.

[out] IoStatusBlock

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.

[in] CompletionFilter

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

[in] WatchTree

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.

[out, optional] Buffer

Reserved. Specify NULL.

[in] BufferSize

Reserved. Specify zero.

[in] Asynchronous

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

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.

Requirements

See also

IO_STATUS_BLOCK

WORK_QUEUE_ITEM

WORK_QUEUE_TYPE

ZwCreateKey

ZwOpenKey