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.

Valore Significato
REG_NOTIFY_CHANGE_NAME
0x00000001L
Notificare al chiamante se una sottochiave viene aggiunta o eliminata.
REG_NOTIFY_CHANGE_ATTRIBUTES
0x00000002L
Notificare al chiamante le modifiche apportate agli attributi della chiave, ad esempio le informazioni sul descrittore di sicurezza.
REG_NOTIFY_CHANGE_LAST_SET
0x00000004L
Notificare al chiamante le modifiche apportate a un valore della chiave. Ciò può includere l'aggiunta o l'eliminazione di un valore o la modifica di un valore esistente.
REG_NOTIFY_CHANGE_SECURITY
0x00000008L
Notificare al chiamante le modifiche apportate al descrittore di sicurezza della chiave.
REG_NOTIFY_THREAD_AGNOSTIC
0x10000000L
Indica che la durata della registrazione non deve essere associata alla durata del thread che esegue la chiamata RegNotifyChangeKeyValue .
Nota Questo valore di flag è supportato solo in Windows 8 e versioni successive.
 

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

Nota In Windows NT, Windows 2000 e Windows XP che chiama RegNotifyChangeKeyValue per un handle di chiave specifico, le notifiche di modifica continuano a verificarsi finché l'handle della chiave è valido. In questo modo viene restituita immediatamente una seconda chiamata a RegNotifyChangeKeyValue , se sono state apportate modifiche nel periodo provvisorio tra la prima e la seconda chiamata. Se l'API viene usata in modo asincrono, l'handle di eventi passato verrà segnalato immediatamente se sono state apportate modifiche provvisorie.
 
Questa funzione non può essere usata per rilevare le modifiche apportate al Registro di sistema risultante dall'uso della funzione RegRestoreKey .

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

Vedi anche

Regclosekey

RegDeleteKey

RegEnumKeyEx

RegEnumValue

RegQueryInfoKey

Regqueryvalueex

Funzioni del Registro di sistema