NtNotifyChangeMultipleKeys function (winternl.h)

Article
02/22/2024

[This function may be changed or removed from Windows without further notice. ]

Requests notification when a registry key or any of its subkeys changes.

Syntax

__kernel_entry NTSTATUS NtNotifyChangeMultipleKeys(
  [in]            HANDLE               MasterKeyHandle,
  [in, optional]  ULONG                Count,
  [in, optional]  OBJECT_ATTRIBUTES [] SubordinateObjects,
  [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] MasterKeyHandle

A handle to an open key. The handle must be opened with the KEY_NOTIFY access right.

[in, optional] Count

The number of subkeys under the key specified by the MasterKeyHandle parameter. This parameter must be 1.

[in, optional] SubordinateObjects

Pointer to an array of OBJECT_ATTRIBUTES structures, one for each subkey. This array can contain one OBJECT_ATTRIBUTES structure.

[in, optional] Event

A handle to an event created by the caller. If Event is not NULL, the caller waits until the operation succeeds, at which time the event is signaled.

[in, optional] ApcRoutine

A pointer to an asynchronous procedure call (APC) function supplied by the caller. If ApcRoutine is not NULL, the specified APC function executes after the operation completes.

[in, optional] ApcContext

A pointer to a context supplied by the caller for its APC function. This value is passed to the APC function when it is executed. The Asynchronous parameter must be TRUE. If ApcContext is specified, the Event parameter must be NULL.

[out] IoStatusBlock

A 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 the Buffer parameter is supplied in the Information member of the IO_STATUS_BLOCK structure.

[in] CompletionFilter

A bitmap of operations that trigger notification. This parameter can be 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.
REG_NOTIFY_CHANGE_SECURITY	Notify the caller of changes to the security descriptor of the key.

[in] WatchTree

If this parameter is TRUE, the caller is notified about changes to all subkeys of the specified key. If this parameter is FALSE, the caller is notified only about changes to the specified key.

[out, optional] Buffer

Reserved for system use. This parameter must be NULL.

[in] BufferSize

Reserved for system use. This parameter must be zero.

[in] Asynchronous

If this parameter is TRUE, the function returns immediately. If this parameter is FALSE, the function does not return until the specified event occurs.

Return value

Returns an NTSTATUS or error code.

If the Asynchronous parameter is TRUE and the specified event has not yet occurred, the function returns STATUS_PENDING.

The forms and significance of NTSTATUS error codes are listed in the Ntstatus.h header file available in the WDK, and are described in the WDK documentation.

Remarks

This function has no associated header file. You can also use the LoadLibrary and GetProcAddress functions to dynamically link to Ntdll.dll.

Requirements

Requirement	Value
Target Platform	Windows
Header	winternl.h
Library	ntdll.lib
DLL	ntdll.dll