Freigeben über


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 für einen 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_ROOTHKEY_CURRENT_CONFIGHKEY_CURRENT_USERHKEY_LOCAL_MACHINEHKEY_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 Zugriffsrecht KEY_NOTIFY geöffnet worden sein. Weitere Informationen finden Sie unter Sicherheit und Zugriffsrechte für Registrierungsschlüssel.

[in] bWatchSubtree

Wenn dieser Parameter TRUE ist, meldet die Funktion Änderungen am angegebenen Schlüssel und seinen Unterschlüsseln. Wenn der Parameter FALSE ist, meldet die Funktion nur Änderungen im angegebenen Schlüssel.

[in] dwNotifyFilter

Ein -Wert, der die Änderungen angibt, die gemeldet werden sollen. Dieser Parameter kann einen oder mehrere der folgenden Werte aufweisen.

Wert Bedeutung
REG_NOTIFY_CHANGE_NAME
0x00000001L
Benachrichtigen Sie den Aufrufer, wenn ein Unterschlüssel hinzugefügt oder gelöscht wird.
REG_NOTIFY_CHANGE_ATTRIBUTES
0x00000002L
Benachrichtigen Sie den Aufrufer über Änderungen an den Attributen des Schlüssels, z. B. die Sicherheitsbeschreibungsinformationen.
REG_NOTIFY_CHANGE_LAST_SET
0x00000004L
Benachrichtigen Sie den Aufrufer über Änderungen an einem Wert des Schlüssels. Dies kann das Hinzufügen oder Löschen eines Werts oder das Ändern eines vorhandenen Werts umfassen.
REG_NOTIFY_CHANGE_SECURITY
0x00000008L
Benachrichtigen Sie den Aufrufer über Änderungen am Sicherheitsdeskriptor des Schlüssels.
REG_NOTIFY_THREAD_AGNOSTIC
0x10000000L
Gibt an, dass die Lebensdauer der Registrierung nicht an die Lebensdauer des Threads gebunden sein darf, der den RegNotifyChangeKeyValue-Aufruf ausgibt.
Hinweis Dieser Flagwert wird nur in Windows 8 und höher unterstützt.
 

[in, optional] hEvent

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

[in] fAsynchronous

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

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

Rückgabewert

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

Wenn die Funktion fehlschlägt, ist der Rückgabewert ein in Winerror.h definierter Fehlercode ungleich null. Sie können die FormatMessage-Funktion mit dem flag FORMAT_MESSAGE_FROM_SYSTEM verwenden, um eine generische Beschreibung des Fehlers abzurufen.

Hinweise

Diese Funktion erkennt eine einzelne Änderung. Nachdem der Aufrufer ein Benachrichtigungsereignis empfangen hat, sollte er die Funktion erneut aufrufen, um die nächste Benachrichtigung zu erhalten.

Hinweis Unter Windows NT, Windows 2000 und Windows XP führt der Aufruf von RegNotifyChangeKeyValue für ein bestimmtes Schlüsselhandle dazu, dass Änderungsbenachrichtigungen weiterhin auftreten, solange das Schlüsselhandle gültig ist. Dies bewirkt, dass ein zweiter Aufruf von RegNotifyChangeKeyValue sofort zurückgegeben wird, wenn in der Zwischenperiode zwischen dem ersten und dem zweiten Aufruf Änderungen aufgetreten sind. Wenn die API asynchron verwendet wird, wird das übergebene Ereignishandle sofort signalisiert, wenn Zwischenänderungen aufgetreten sind.
 
Diese Funktion kann nicht verwendet werden, um Änderungen an der Registrierung zu erkennen, die sich aus der Verwendung der RegRestoreKey-Funktion ergeben.

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 REG_NOTIFY_THREAD_AGNOSTIC-Flag ermöglicht die Verwendung von RegNotifyChangeKeyValue für ThreadPool-Threads.

Wenn der Thread, der RegNotifyChangeKeyValue aufgerufen hat , beendet wird, wird das Ereignis signalisiert. Um weitere Änderungen am Wert des Schlüssels zu überwachen, rufen Sie RegNotifyChangeKeyValue erneut aus einem anderen Thread auf.

Mit Ausnahme von RegNotifyChangeKeyValue-Aufrufen mit festgelegtem REG_NOTIFY_THREAD_AGNOSTIC muss diese Funktion für persistente Threads aufgerufen werden. Wenn der aufrufende Thread aus einem Threadpool stammt und nicht persistent ist, wird das Ereignis jedes Mal signalisiert, wenn der Thread beendet wird, nicht nur, wenn eine Registrierungsänderung vorliegt. Um genaue Ergebnisse sicherzustellen, führen Sie die Threadpoolarbeit in einem persistenten Thread aus, indem Sie die SetThreadpoolCallbackPersistent-Funktion verwenden, oder erstellen Sie einen eigenen Thread mit 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 mit unterschiedlichen Werten für die Parameter bWatchSubtree und dwNotifyFilter . Die Funktion ist erfolgreich, aber die Änderungen werden ignoriert. Zu änderndes Merkmal
watch Parametern müssen Sie zuerst das Schlüsselhandle schließen, indem Sie RegCloseKey aufrufen, das Schlüsselhandle erneut öffnen, indem Sie RegOpenKeyEx aufrufen, und dann RegNotifyChangeKeyValue mit den neuen Parametern aufrufen.

Jedes Mal, wenn ein Prozess RegNotifyChangeKeyValue mit demselben Parametersatz aufruft, wird ein weiterer Wartevorgang eingerichtet, wodurch ein Ressourcenverlust entsteht. Vergewissern Sie sich daher, dass Sie RegNotifyChangeKeyValue erst mit denselben Parametern aufrufen, wenn der vorherige Wartevorgang abgeschlossen ist.

Informationen zum Überwachen von Registrierungsvorgängen im Detail finden Sie unter Registrierung.

Windows XP/2000: Wenn RegNotifyChangeKeyValue für ein bestimmtes Schlüsselhandle aufgerufen wird, erfolgen Änderungsbenachrichtigungen, solange das Schlüsselhandle gültig ist. Dies führt dazu, dass ein zweiter Aufruf von RegNotifyChangeKeyValue sofort zurückgegeben wird, wenn zwischen dem ersten und dem zweiten Aufruf Änderungen auftreten. Wenn die Funktion asynchron verwendet wird, wird das übergebene Ereignishandle sofort signalisiert, wenn in der Zwischenzeit Änderungen 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;
   }
}

Anforderungen

   
Unterstützte Mindestversion (Client) Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows 2000 Server [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile winreg.h (Windows.h einschließen)
Bibliothek Advapi32.lib
DLL Advapi32.dll

Weitere Informationen

RegCloseKey

RegDeleteKey

RegEnumKeyEx

RegEnumValue

RegQueryInfoKey

RegQueryValueEx

Registrierungsfunktionen