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.
[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.
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 |