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

Version

Available starting with Windows 2000.

Header

Ntifs.h (include Ntifs.h)

Library

Ntoskrnl.lib

IRQL

PASSIVE_LEVEL

DDI compliance rules

PowerIrpDDis, HwStorPortProhibitedDDIs

See also

IO_STATUS_BLOCK
ZwCreateKey
ZwOpenKey
WORK_QUEUE_ITEM
WORK_QUEUE_TYPE

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft