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

Vedi anche

Regclosekey

RegDeleteKey

RegEnumKeyEx

RegEnumValue

RegQueryInfoKey

Regqueryvalueex

Funzioni del Registro di sistema