Partager via


Fonction RegNotifyChangeKeyValue (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 d’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_ROOTHKEY_CURRENT_CONFIGHKEY_CURRENT_USER HKEY_LOCAL_MACHINEHKEY_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 Sécurité de la clé de Registre et 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 a la valeur FALSE, la fonction signale uniquement les modifications apportées à la clé spécifiée.

[in] dwNotifyFilter

Valeur qui indique les modifications à signaler. Ce paramètre peut prendre une ou plusieurs des valeurs suivantes.

Valeur Signification
REG_NOTIFY_CHANGE_NAME
0x00000001L
Informez l’appelant si une sous-clé est ajoutée ou supprimée.
REG_NOTIFY_CHANGE_ATTRIBUTES
0x00000002L
Informez l’appelant des modifications apportées aux attributs de la clé, telles que les informations de descripteur de sécurité.
REG_NOTIFY_CHANGE_LAST_SET
0x00000004L
Informez l’appelant des modifications apportées à une valeur de la clé. Cela peut inclure l’ajout ou la suppression d’une valeur, ou la modification d’une valeur existante.
REG_NOTIFY_CHANGE_SECURITY
0x00000008L
Informez l’appelant des modifications apportées au descripteur de sécurité de la clé.
REG_NOTIFY_THREAD_AGNOSTIC
0x100000000L
Indique que la durée de vie de l’inscription ne doit pas être liée à la durée de vie du thread qui émet l’appel RegNotifyChangeKeyValue .
Note Cette valeur d’indicateur est uniquement prise en charge dans Windows 8 et versions ultérieures.
 

[in, optional] hEvent

Handle d’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 a la valeur 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 retourné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 a reçu un événement de notification, il doit appeler à nouveau la fonction pour recevoir la notification suivante.

Note Sur Windows NT, Windows 2000 et Windows XP, l’appel de RegNotifyChangeKeyValue pour un handle de clé particulier entraîne la poursuite des notifications de modification tant que le handle de clé est valide. Cela entraîne le retour immédiat d’un deuxième appel à RegNotifyChangeKeyValue , si des modifications se sont produites pendant la période intermédiaire entre le premier et le deuxième appel. Si l’API est utilisée de manière asynchrone, le handle d’événement passé est immédiatement signalé si des modifications intermédiaires se sont produites.
 
Cette fonction ne peut pas être utilisée pour détecter les modifications apportées au Registre résultant de l’utilisation de la fonction RegRestoreKey .

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 l’ouverture de la clé 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 qui a appelé RegNotifyChangeKeyValue se ferme, l’événement est signalé. Pour continuer à surveiller les modifications supplémentaires apportées à la valeur de la clé, appelez à nouveau RegNotifyChangeKeyValue à partir d’un autre thread.

À l’exception des appels RegNotifyChangeKeyValue avec REG_NOTIFY_THREAD_AGNOSTIC défini, cette fonction doit être appelée sur les 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 en cas de 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 du 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 sont ignorées. Pour modifier l'élément suivant
watch 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, case activée 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 du Registre, consultez Registre.

Windows XP/2000 : Lorsque RegNotifyChangeKeyValue est appelé pour un handle de clé particulier, des notifications de modification se produisent tant que le handle de clé est valide. Cela entraîne le retour immédiat d’un deuxième appel à RegNotifyChangeKeyValue , si des modifications se produisent entre le premier et le deuxième appel. Si la fonction est utilisée de manière asynchrone, le handle d’événement passé est immédiatement signalé 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;
   }
}

Configuration requise

   
Client minimal pris en charge Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge Windows 2000 Server [applications de bureau uniquement]
Plateforme cible Windows
En-tête winreg.h (inclure Windows.h)
Bibliothèque Advapi32.lib
DLL Advapi32.dll

Voir aussi

RegCloseKey

RegDeleteKey

RegEnumKeyEx

RegEnumValue

RegQueryInfoKey

RegQueryValueEx

Fonctions du Registre