This topic has not yet been rated - Rate this topic

ZwNotifyChangeKey routine

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

Syntax


NTSTATUS 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_opt_  PVOID Buffer,
  _In_       ULONG BufferSize,
  _In_       BOOLEAN Asynchronous
);

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]

Handle to a caller-created event. 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]

The meaning of this parameter depends on whether the routine is called from kernel mode or from user mode. For a kernel-mode call, this parameter points to a caller-allocated WORK_QUEUE_ITEM structure that the caller has initialized. This structure specifies a worker routine to run after the requested registry operation is completed. The parameter value must be cast to type PIO_APC_ROUTINE. For a user-mode call, this parameter points to a caller-supplied APC routine that is run after the operation is completed. This parameter is optional and can be NULL.

ApcContext [in, optional]

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

The parameter value must be cast to type PVOID. For a user-mode call, this parameter points to a caller-specified context for the APC routine. This value is passed to the APC routine when it is run.

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:

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

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

Requirements