RegNotifyChangeKeyValue, fonction (winreg.h)

Avertit l’appelant des modifications apportées aux attributs ou au contenu d’une clé de Registre spécifiée.

Syntaxe

LSTATUS RegNotifyChangeKeyValue(
  [in]           HKEY   hKey,
  [in]           BOOL   bWatchSubtree,
  [in]           DWORD  dwNotifyFilter,
  [in, optional] HANDLE hEvent,
  [in]           BOOL   fAsynchronous
);

Paramètres

[in] hKey

Handle vers une clé de Registre ouverte. Ce handle est retourné par la fonction RegCreateKeyEx ou RegOpenKeyEx . Il peut également s’agir de l’une des clés prédéfinies suivantes :

HKEY_CLASSES_ROOT, HKEY_CURRENT_CONFIG, HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE, HKEY_USERS.

Ce paramètre doit être un handle local. Si RegNotifyChangeKeyValue est appelé avec un handle distant, il retourne ERROR_INVALID_HANDLE.

La clé doit avoir été ouverte avec le droit d’accès KEY_NOTIFY. Pour plus d’informations, consultez La sécurité des clés de Registre et les droits d’accès.

[in] bWatchSubtree

Si ce paramètre a la valeur TRUE, la fonction signale les modifications apportées à la clé spécifiée et à ses sous-clés. Si le paramètre est FALSE, la fonction signale les modifications uniquement dans la clé spécifiée.

[in] dwNotifyFilter

Valeur qui indique les modifications qui doivent être signalées. Ce paramètre peut prendre l’une ou plusieurs des valeurs suivantes.

[in, optional] hEvent

Handle vers un événement. Si le paramètre fAsynchronous a la valeur TRUE, la fonction retourne immédiatement et les modifications sont signalées en signalant cet événement. Si fAsynchronous a la valeur FALSE, hEvent est ignoré.

[in] fAsynchronous

Si ce paramètre a la valeur TRUE, la fonction retourne immédiatement et signale les modifications en signalant l’événement spécifié. Si ce paramètre est FALSE, la fonction ne retourne pas tant qu’une modification n’a pas eu lieu.

Si hEvent ne spécifie pas d’événement valide, le paramètre fAsynchronous ne peut pas être TRUE.

Valeur renvoyée

Si la fonction réussit, la valeur de retour est ERROR_SUCCESS.

Si la fonction échoue, la valeur de retour est un code d’erreur différent de zéro défini dans Winerror.h. Vous pouvez utiliser la fonction FormatMessage avec l’indicateur FORMAT_MESSAGE_FROM_SYSTEM pour obtenir une description générique de l’erreur.

Remarques

Cette fonction détecte une seule modification. Une fois que l’appelant reçoit un événement de notification, il doit appeler à nouveau la fonction pour recevoir la notification suivante.

Si la clé spécifiée est fermée, l’événement est signalé. Cela signifie qu’une application ne doit pas dépendre de la clé ouverte après le retour d’une opération d’attente sur l’événement.

L’indicateur REG_NOTIFY_THREAD_AGNOSTIC introduit dans Windows 8 permet d’utiliser RegNotifyChangeKeyValue pour les threads ThreadPool.

Si le thread appelé RegNotifyChangeKeyValue s’arrête , l’événement est signalé. Pour continuer à surveiller des modifications supplémentaires dans la valeur de la clé, appelez RegNotifyChangeKeyValue à nouveau à partir d’un autre thread.

À l’exception des appels RegNotifyChangeKeyValue avec REG_NOTIFY_THREAD_AGNOSTIC set, cette fonction doit être appelée sur des threads persistants. Si le thread appelant provient d’un pool de threads et qu’il n’est pas persistant, l’événement est signalé chaque fois que le thread se termine, pas seulement lorsqu’il existe une modification du Registre. Pour garantir des résultats précis, exécutez le travail du pool de threads dans un thread persistant à l’aide de la fonction SetThreadpoolCallbackPersistent , ou créez votre propre thread à l’aide de la fonction CreateThread . (Pour l’API de pool de threads d’origine, spécifiez WT_EXECUTEINPERSISTENTTHREAD à l’aide de la fonction QueueUserWorkItem .)

Cette fonction ne doit pas être appelée plusieurs fois avec la même valeur pour la clé hKey , mais des valeurs différentes pour les paramètres bWatchSubtree et dwNotifyFilter . La fonction réussit, mais les modifications seront ignorées. Pour modifier le
surveillez les paramètres, vous devez d’abord fermer le handle de clé en appelant RegCloseKey, rouvrir le handle de clé en appelant RegOpenKeyEx, puis appeler RegNotifyChangeKeyValue avec les nouveaux paramètres.

Chaque fois qu’un processus appelle RegNotifyChangeKeyValue avec le même ensemble de paramètres, il établit une autre opération d’attente, créant une fuite de ressources. Par conséquent, vérifiez que vous n’appelez pas RegNotifyChangeKeyValue avec les mêmes paramètres tant que l’opération d’attente précédente n’est pas terminée.

Pour surveiller plus en détail les opérations de Registre, consultez Registre.

Windows XP/2000 : When RegNotifyChangeKeyValue est appelé pour un handle de clé particulier, les notifications de modification se produisent tant que le handle de clé est valide. Cela entraîne un deuxième appel à RegNotifyChangeKeyValue immédiatement, si des modifications se produisent dans l’intervalle entre les premiers et deuxième appels. Si la fonction est utilisée de façon asynchrone, le handle d’événement transmis est signalé immédiatement si des modifications se produisent dans l’intervalle.

Exemples

Le programme suivant montre comment utiliser 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;
   }
}

Exigences

Voir aussi

RegCloseKey

RegDeleteKey

RegEnumKeyEx

RegEnumValue

RegQueryInfoKey

RegQueryValueEx

Fonctions de Registre