RegNotifyChangeKeyValue-Funktion (winreg.h)

Benachrichtigt den Aufrufer über Änderungen an den Attributen oder Inhalten eines angegebenen Registrierungsschlüssels.

Syntax

LSTATUS RegNotifyChangeKeyValue(
  [in]           HKEY   hKey,
  [in]           BOOL   bWatchSubtree,
  [in]           DWORD  dwNotifyFilter,
  [in, optional] HANDLE hEvent,
  [in]           BOOL   fAsynchronous
);

Parameter

[in] hKey

Ein Handle zu einem geöffneten Registrierungsschlüssel. Dieses Handle wird von der RegCreateKeyEx - oder RegOpenKeyEx-Funktion zurückgegeben. Es kann auch einer der folgenden vordefinierten Schlüssel sein:

HKEY_CLASSES_ROOT, HKEY_CURRENT_CONFIG, HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE, HKEY_USERS.

Dieser Parameter muss ein lokales Handle sein. Wenn RegNotifyChangeKeyValue mit einem Remotehandle aufgerufen wird, wird ERROR_INVALID_HANDLE zurückgegeben.

Der Schlüssel muss mit dem KEY_NOTIFY Zugriffsrecht geöffnet worden sein. Weitere Informationen finden Sie unter Registry Key Security and Access Rights.

[in] bWatchSubtree

Wenn dieser Parameter WAHR ist, meldet die Funktion Änderungen am angegebenen Schlüssel und den zugehörigen Unterschlüsseln. Wenn der Parameter FALSCH ist, ändert sich die Funktion nur im angegebenen Schlüssel.

[in] dwNotifyFilter

Ein Wert, der die Änderungen angibt, die gemeldet werden sollen. Dieser Parameter kann einen der folgenden Werte annehmen.

[in, optional] hEvent

Ein Handle für ein Ereignis. Wenn der fAsynchronous-ParameterWAHR ist, gibt die Funktion sofort zurück, und Änderungen werden durch Signalisieren dieses Ereignisses gemeldet. Wenn "fAsynchronous" FALSCH ist, wird "hEvent" ignoriert.

[in] fAsynchronous

Wenn dieser Parameter WAHR ist, gibt die Funktion sofort zurück und meldet Änderungen, indem das angegebene Ereignis signalisiert wird. Wenn dieser Parameter FALSCH ist, wird die Funktion erst zurückgegeben, wenn eine Änderung aufgetreten ist.

Wenn hEvent kein gültiges Ereignis angibt, kann der fAsynchronous-Parameter nicht TRUE sein.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ERROR_SUCCESS.

Wenn die Funktion fehlschlägt, ist der Rückgabewert ein nichtzero-Fehlercode, der in Winerror.h definiert ist. Sie können die FormatMessage-Funktion mit dem FORMAT_MESSAGE_FROM_SYSTEM Flag verwenden, um eine generische Beschreibung des Fehlers zu erhalten.

Bemerkungen

Diese Funktion erkennt eine einzelne Änderung. Nachdem der Aufrufer ein Benachrichtigungsereignis empfängt, sollte die Funktion erneut aufgerufen werden, um die nächste Benachrichtigung zu erhalten.

Wenn der angegebene Schlüssel geschlossen ist, wird das Ereignis signalisiert. Dies bedeutet, dass eine Anwendung nicht davon abhängig sein sollte, dass der Schlüssel geöffnet wird, nachdem sie von einem Wartevorgang für das Ereignis zurückgegeben wurde.

Das in Windows 8 eingeführte flag REG_NOTIFY_THREAD_AGNOSTIC ermöglicht die Verwendung von RegNotifyChangeKeyValue für ThreadPool-Threads.

Wenn der Thread, der RegNotifyChangeKeyValue beendet, wird das Ereignis signalisiert. Rufen Sie RegNotifyChangeKeyValue erneut aus einem anderen Thread auf, um weitere Änderungen im Wert des Schlüssels zu überwachen.

Mit Ausnahme von RegNotifyChangeKeyValue-Aufrufen mit REG_NOTIFY_THREAD_AGNOSTIC Satz muss diese Funktion für persistente Threads aufgerufen werden. Wenn der aufrufende Thread aus einem Threadpool stammt und es nicht dauerhaft ist, wird das Ereignis jedes Mal signalisiert, wenn der Thread beendet wird, nicht nur, wenn eine Registrierungsänderung vorhanden ist. Um genaue Ergebnisse sicherzustellen, führen Sie den Threadpool in einem beständigen Thread mithilfe der SetThreadpoolCallbackPersistent-Funktion aus, oder erstellen Sie ihren eigenen Thread mithilfe der CreateThread-Funktion . (Geben Sie für die ursprüngliche Threadpool-API WT_EXECUTEINPERSISTENTTHREAD mithilfe der QueueUserWorkItem-Funktion an.)

Diese Funktion sollte nicht mehrmals mit demselben Wert für den hKey aufgerufen werden, sondern verschiedene Werte für die Parameter bWatchSubtree und dwNotifyFilter . Die Funktion wird erfolgreich ausgeführt, die Änderungen werden jedoch ignoriert. So ändern Sie die
watch parameters, you must first close the key handle by calling RegCloseKey, reopen the key handle by calling RegOpenKeyEx, and then call RegNotifyChangeKeyValue with the new parameters.

Jedes Mal, wenn ein Prozess RegNotifyChangeKeyValue mit demselben Satz von Parametern aufruft, wird ein weiterer Wartevorgang eingerichtet, wodurch ein Ressourcenverlust entsteht. Überprüfen Sie daher, dass Sie RegNotifyChangeKeyValue nicht mit denselben Parametern aufrufen, bis der vorherige Wartevorgang abgeschlossen ist.

Weitere Informationen zum Überwachen von Registrierungsvorgängen finden Sie unter "Registrierung".

Windows XP/2000: When RegNotifyChangeKeyValue wird für ein bestimmtes Schlüsselhandle aufgerufen, Änderungsbenachrichtigungen treten so lange auf, wie der Tastenziehpunkt gültig ist. Dies bewirkt, dass ein zweiter Aufruf von RegNotifyChangeKeyValue sofort zurückgegeben wird, wenn Änderungen zwischen dem ersten und dem zweiten Aufruf vorgenommen werden. Wenn die Funktion asynchron verwendet wird, wird das übergebene Ereignishandle sofort signalisiert, wenn änderungen in der Zwischenzeit auftreten.

Beispiele

Das folgende Programm veranschaulicht die Verwendung von RegNotifyChangeKeyValue.

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

//void main(int argc, char *argv[])
void __cdecl _tmain(int argc, TCHAR *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) 
   {
      _tprintf(TEXT("Usage: notify [HKLM|HKU|HKCU|HKCR|HCC] [<subkey>]\n"));
      return;
   }

   // Convert parameters to appropriate handles.
   if (_tcscmp(TEXT("HKLM"), argv[1]) == 0) hMainKey=HKEY_LOCAL_MACHINE;
   else if(_tcscmp(TEXT("HKU"), argv[1]) == 0) hMainKey=HKEY_USERS;
   else if(_tcscmp(TEXT("HKCU"), argv[1]) == 0) hMainKey=HKEY_CURRENT_USER;
   else if(_tcscmp(TEXT("HKCR"), argv[1]) == 0) hMainKey=HKEY_CLASSES_ROOT;
   else if(_tcscmp(TEXT("HCC"), argv[1]) == 0) hMainKey=HKEY_CURRENT_CONFIG;
   else 
   {
      _tprintf(TEXT("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)
   {
      _tprintf(TEXT("Error in RegOpenKeyEx (%d).\n"), lErrorCode);
      return;
   }

   // Create an event.
   hEvent = CreateEvent(NULL, TRUE, FALSE, NULL);
   if (hEvent == NULL)
   {
      _tprintf(TEXT("Error in CreateEvent (%d).\n"), GetLastError());
      return;
   }

   // Watch the registry key for a change of value.
   lErrorCode = RegNotifyChangeKeyValue(hKey, 
                                        TRUE, 
                                        dwFilter, 
                                        hEvent, 
                                        TRUE);
   if (lErrorCode != ERROR_SUCCESS)
   {
      _tprintf(TEXT("Error in RegNotifyChangeKeyValue (%d).\n"), lErrorCode);
      return;
   }

   // Wait for an event to occur.
   _tprintf(TEXT("Waiting for a change in the specified key...\n"));
   if (WaitForSingleObject(hEvent, INFINITE) == WAIT_FAILED)
   {
      _tprintf(TEXT("Error in WaitForSingleObject (%d).\n"), GetLastError());
      return;
   }
   else _tprintf(TEXT("\nChange has occurred.\n"));

   // Close the key.
   lErrorCode = RegCloseKey(hKey);
   if (lErrorCode != ERROR_SUCCESS)
   {
      _tprintf(TEXT("Error in RegCloseKey (%d).\n"), GetLastError());
      return;
   }
   
   // Close the handle.
   if (!CloseHandle(hEvent))
   {
      _tprintf(TEXT("Error in CloseHandle.\n"));
      return;
   }
}

Requirements

Siehe auch

RegCloseKey

RegDeleteKey

RegEnumKeyEx

RegEnumValue

RegQueryInfoKey

RegQueryValueEx

Registrierungsfunktionen