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