Funzione RegNotifyChangeKeyValue (winreg.h)
Notifica al chiamante le modifiche apportate agli attributi o al contenuto di una chiave del Registro di sistema specificata.
Sintassi
LSTATUS RegNotifyChangeKeyValue(
[in] HKEY hKey,
[in] BOOL bWatchSubtree,
[in] DWORD dwNotifyFilter,
[in, optional] HANDLE hEvent,
[in] BOOL fAsynchronous
);
Parametri
[in] hKey
Handle per una chiave del Registro di sistema aperta. Questo handle viene restituito dalla funzione RegCreateKeyEx o RegOpenKeyEx . Può anche essere una delle chiavi predefinite seguenti:
HKEY_CLASSES_ROOTHKEY_CURRENT_CONFIG HKEY_CURRENT_USERHKEY_LOCAL_MACHINE HKEY_USERS Questo parametro deve essere un handle locale. Se RegNotifyChangeKeyValue viene chiamato con un handle remoto, restituisce ERROR_INVALID_HANDLE.
La chiave deve essere stata aperta con il diritto di accesso KEY_NOTIFY. Per altre informazioni, vedere Sicurezza e diritti di accesso delle chiavi del Registro di sistema.
[in] bWatchSubtree
Se questo parametro è TRUE, la funzione segnala le modifiche nella chiave specificata e nelle relative sottochiavi. Se il parametro è FALSE, la funzione segnala solo le modifiche nella chiave specificata.
[in] dwNotifyFilter
Valore che indica le modifiche da segnalare. Questo parametro può essere uno o più dei valori seguenti.
[in, optional] hEvent
Handle per un evento. Se il parametro fAsynchronous è TRUE, la funzione restituisce immediatamente e le modifiche vengono segnalate segnalando questo evento. Se fAsynchronous è FALSE, hEvent viene ignorato.
[in] fAsynchronous
Se questo parametro è TRUE, la funzione restituisce immediatamente e segnala le modifiche segnalando l'evento specificato. Se questo parametro è FALSE, la funzione non restituisce fino a quando non viene apportata una modifica.
Se hEvent non specifica un evento valido, il parametro fAsynchronous non può essere TRUE.
Valore restituito
Se la funzione ha esito positivo, il valore restituito viene ERROR_SUCCESS.
Se la funzione ha esito negativo, il valore restituito è un codice di errore diverso da zero definito in Winerror.h. È possibile usare la funzione FormatMessage con il flag FORMAT_MESSAGE_FROM_SYSTEM per ottenere una descrizione generica dell'errore.
Commenti
Questa funzione rileva una singola modifica. Dopo che il chiamante riceve un evento di notifica, deve chiamare di nuovo la funzione per ricevere la notifica successiva.
Se la chiave specificata viene chiusa, l'evento viene segnalato. Ciò significa che un'applicazione non deve dipendere dalla chiave aperta dopo la restituzione da un'operazione di attesa sull'evento.
Il flag REG_NOTIFY_THREAD_AGNOSTIC introdotto in Windows 8 consente l'uso di RegNotifyChangeKeyValue per i thread ThreadPool.
Se il thread che ha chiamato RegNotifyChangeKeyValue viene chiuso, l'evento viene segnalato. Per continuare a monitorare altre modifiche nel valore della chiave, chiamare di nuovo RegNotifyChangeKeyValue da un altro thread.
Ad eccezione delle chiamate RegNotifyChangeKeyValue con REG_NOTIFY_THREAD_AGNOSTIC impostato, questa funzione deve essere chiamata su thread persistenti. Se il thread chiamante proviene da un pool di thread e non è persistente, l'evento viene segnalato ogni volta che il thread termina, non solo quando viene apportata una modifica al Registro di sistema. Per garantire risultati accurati, eseguire il lavoro del pool di thread in un thread permanente usando la funzione SetThreadpoolCallbackPersistent oppure creare un thread personalizzato usando la funzione CreateThread . Per l'API del pool di thread originale, specificare WT_EXECUTEINPERSISTENTTHREAD usando la funzione QueueUserWorkItem .
Questa funzione non deve essere chiamata più volte con lo stesso valore per hKey , ma valori diversi per i parametri bWatchSubtree e dwNotifyFilter . La funzione avrà esito positivo, ma le modifiche verranno ignorate. Per modificare il
watch parametri, è prima necessario chiudere l'handle di chiave chiamando RegCloseKey, riaprire l'handle di chiave chiamando RegOpenKeyEx e quindi chiamare RegNotifyChangeKeyValue con i nuovi parametri.
Ogni volta che un processo chiama RegNotifyChangeKeyValue con lo stesso set di parametri, stabilisce un'altra operazione di attesa, creando una perdita di risorse. Verificare pertanto di non chiamare RegNotifyChangeKeyValue con gli stessi parametri fino al completamento dell'operazione di attesa precedente.
Per monitorare le operazioni del Registro di sistema in modo più dettagliato, vedere Registro di sistema.
Windows XP/2000: Quando RegNotifyChangeKeyValue viene chiamato per un handle di chiave specifico, le notifiche di modifica vengono eseguite finché l'handle della chiave è valido. In questo modo viene restituita immediatamente una seconda chiamata a RegNotifyChangeKeyValue , se si verificano modifiche nel frattempo tra la prima e la seconda chiamata. Se la funzione viene usata in modo asincrono, l'handle di eventi passato verrà segnalato immediatamente se si verificano modifiche nel frattempo.
Esempio
Il programma seguente illustra come usare 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;
}
}
Requisiti
| Client minimo supportato | Windows 2000 Professional [solo app desktop] |
| Server minimo supportato | Windows 2000 Server [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | winreg.h (include Windows.h) |
| Libreria | Advapi32.lib |
| DLL | Advapi32.dll |