RegNotifyChangeKeyValue

The RegNotifyChangeKeyValue function notifies the caller about changes to the attributes or contents of a specified registry key. Note that the function does not notify the caller if the specified key is deleted.

LONG RegNotifyChangeKeyValue(
  HKEY hKey,             // handle to key to watch
  BOOL bWatchSubtree,    // subkey notification option
  DWORD dwNotifyFilter,  // changes to be reported
  HANDLE hEvent,         // handle to event to be signaled
  BOOL fAsynchronous     // asynchronous reporting option
);

Parameters

hKey

[in] Handle to a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_CONFIG
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

bWatchSubtree

[in] Specifies a flag that indicates whether to report changes in the specified key and all of its subkeys or only in the specified key. If this parameter is TRUE, the function reports changes in the key and its subkeys. If the parameter is FALSE, the function reports changes only in the key.

dwNotifyFilter

[in] Specifies a set of flags that control which changes should be reported. This parameter can be a combination of the following values.

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.

hEvent

[in] Handle to an event. If the fAsynchronous parameter is TRUE, the function returns immediately and changes are reported by signaling this event. If fAsynchronous is FALSE, hEvent is ignored.

fAsynchronous

[in] Specifies a flag that indicates how the function reports changes. If this parameter is TRUE, the function returns immediately and reports changes by signaling the specified event. When this parameter is FALSE, the function does not return until a change has occurred.

If hEvent does not specify a valid event, the fAsynchronous parameter cannot be TRUE.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in Winerror.h. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

Remarks

If the key identified by the hKey parameter is closed, the event is signaled. This means that an application should not depend on the key being open after returning from a wait operation on the event.

If the thread that called RegNotifyChangeKeyValue exits, the event is signaled. When the event is signaled, RegNotifyChangeKeyValue ends its monitoring of the key value. If you want to monitor further changes in the value of the key, call RegNotifyChangeKeyValue again.

RegNotifyChangeKeyValue does not work with remote handles. If RegNotifyChangeKeyValue is called with an hKey value that is a remote handle, it returns ERROR_INVALID_HANDLE.

Windows 98: No registry subkey or value name can exceed 255 characters.

If this function is called more than once with different values for the bWatchSubtree and dwNotifyFilter parameters, the changed parameter values will be ignored on subsequent calls. If you want to call RegNotifyChangeKeyValue again with different values for these parameters, you must first close the key handle hKey by calling CloseHandle, then reopen the key handle by calling RegOpenKeyEx.

The following program illustrates how to use RegNotifyChangeKeyValue.

#include <stdio.h>
#include <windows.h>

void main(int argc, char *argv[])
{
DWORD  dwFilter = REG_NOTIFY_CHANGE_NAME |
                  REG_NOTIFY_CHANGE_ATTRIBUTES |
                  REG_NOTIFY_CHANGE_LAST_SET |
                  REG_NOTIFY_CHANGE_SECURITY; 

HANDLE hEvent;
HKEY   hMainKey;
HKEY   hKey;
LONG   lErrorCode;

// Display the usage error message.
if (argc != 3) 
{
    printf("Usage: notify [HKLM/HKU/HKCU/HKCR/HCC] [subkey]\n");
    return;
}

// Convert parameters to appropriate handles.
if (strcmp("HKLM", argv[1]) == 0)
   hMainKey = HKEY_LOCAL_MACHINE;
else if (strcmp("HKU", argv[1]) == 0)
   hMainKey = HKEY_USERS;
else if (strcmp("HKCU", argv[1]) == 0)
   hMainKey = HKEY_CURRENT_USER;
else if (strcmp("HKCR", argv[1]) == 0)
   hMainKey = HKEY_CLASSES_ROOT;
else if (strcmp("HCC", argv[1]) == 0)
   hMainKey = HKEY_CURRENT_CONFIG;
else 
{
    printf("Usage: notify [HKLM/HKU/HKCU/HKCR/HCC] [subkey]\n");
    return;
}

// Open a key.
lErrorCode = RegOpenKeyEx(hMainKey, argv[2], 0, KEY_NOTIFY, &hKey);
if (lErrorCode != ERROR_SUCCESS)
   printf("Error in RegOpenKeyEx.\n");

// Create an event.
hEvent = CreateEvent(NULL, TRUE, FALSE, NULL);
if (hEvent == NULL)
    printf("Error in CreateEvent.\n");

// Watch the registry key for a change of value.
lErrorCode = RegNotifyChangeKeyValue(hKey, 
                                     TRUE, 
                                     dwFilter, 
                                     hEvent, 
                                     TRUE);
if (lErrorCode != ERROR_SUCCESS)
   printf("Error in RegNotifyChangeKeyValue.\n");

// Wait for an event to occur.
if (WaitForSingleObject(hEvent, INFINITE) == WAIT_FAILED)
   printf("Error in WaitForSingleObject.\n");

// Close the key.
lErrorCode = RegCloseKey(hKey);
if (lErrorCode != ERROR_SUCCESS)
   printf("Error in RegCloseKey.\n");

// Close the handle.
if (!CloseHandle(hEvent))
   printf("Error in CloseHandle.\n");
}

Requirements

  Windows NT/2000: Requires Windows NT 3.1 or later.
  Windows 95/98: Requires Windows 98.
  Header: Declared in Winreg.h; include Windows.h.
  Library: Use Advapi32.lib.

See Also

Registry Overview, Registry Functions, RegDeleteKey, RegEnumKey, RegEnumKeyEx, RegEnumValue, RegQueryInfoKey, RegQueryValue, RegQueryValueEx