Función RegNotifyChangeKeyValue (winreg.h)
Notifica al autor de la llamada los cambios realizados en los atributos o el contenido de una clave del Registro especificada.
Sintaxis
LSTATUS RegNotifyChangeKeyValue(
[in] HKEY hKey,
[in] BOOL bWatchSubtree,
[in] DWORD dwNotifyFilter,
[in, optional] HANDLE hEvent,
[in] BOOL fAsynchronous
);
Parámetros
[in] hKey
Identificador de una clave del Registro abierta. La función RegCreateKeyEx o RegOpenKeyEx devuelve este identificador. También puede ser una de las siguientes claves predefinidas:
HKEY_CLASSES_ROOT HKEY_CURRENT_CONFIGHKEY_CURRENT_USERHKEY_LOCAL_MACHINEHKEY_USERS Este parámetro debe ser un identificador local. Si se llama a RegNotifyChangeKeyValue con un identificador remoto, devuelve ERROR_INVALID_HANDLE.
La clave debe haberse abierto con el derecho de acceso KEY_NOTIFY. Para obtener más información, consulte Derechos de acceso y seguridad de clave del Registro.
[in] bWatchSubtree
Si este parámetro es TRUE, la función notifica los cambios en la clave especificada y sus subclaves. Si el parámetro es FALSE, la función notifica los cambios solo en la clave especificada.
[in] dwNotifyFilter
Valor que indica los cambios que se deben notificar. Este parámetro puede ser uno o más de los siguientes valores.
[in, optional] hEvent
Identificador de un evento. Si el parámetro fAsynchronous es TRUE, la función devuelve inmediatamente y los cambios se notifican mediante la señalización de este evento. Si fAsynchronous es FALSE, se omite hEvent .
[in] fAsynchronous
Si este parámetro es TRUE, la función devuelve inmediatamente e informa de los cambios mediante la señalización del evento especificado. Si este parámetro es FALSE, la función no devuelve hasta que se ha producido un cambio.
Si hEvent no especifica un evento válido, el parámetro fAsynchronous no puede ser TRUE.
Valor devuelto
Si la función se ejecuta correctamente, el valor devuelto es ERROR_SUCCESS.
Si la función no se ejecuta correctamente, el valor devuelto es un código de error distinto de cero definido en Winerror.h. Puede usar la función FormatMessage con la marca FORMAT_MESSAGE_FROM_SYSTEM para obtener una descripción genérica del error.
Comentarios
Esta función detecta un único cambio. Una vez que el autor de la llamada recibe un evento de notificación, debe llamar a la función de nuevo para recibir la siguiente notificación.
Si se cierra la clave especificada, se señala el evento. Esto significa que una aplicación no debe depender de que la clave esté abierta después de volver de una operación de espera en el evento.
La marca REG_NOTIFY_THREAD_AGNOSTIC introducida en Windows 8 permite el uso de RegNotifyChangeKeyValue para subprocesos threadPool.
Si se cierra el subproceso que llamó a RegNotifyChangeKeyValue , se señala el evento . Para seguir supervisando los cambios adicionales en el valor de la clave, llame a RegNotifyChangeKeyValue de nuevo desde otro subproceso.
A excepción de las llamadas RegNotifyChangeKeyValue con REG_NOTIFY_THREAD_AGNOSTIC establecido, se debe llamar a esta función en subprocesos persistentes. Si el subproceso que realiza la llamada es de un grupo de subprocesos y no es persistente, el evento se señala cada vez que finaliza el subproceso, no solo cuando se produce un cambio en el registro. Para garantizar resultados precisos, ejecute el grupo de subprocesos en un subproceso persistente mediante la función SetThreadpoolCallbackPersistent o cree su propio subproceso mediante la función CreateThread . (Para la API del grupo de subprocesos original, especifique WT_EXECUTEINPERSISTENTTHREAD mediante la función QueueUserWorkItem ).
No se debe llamar a esta función varias veces con el mismo valor para hKey , pero valores diferentes para los parámetros bWatchSubtree y dwNotifyFilter . La función se realizará correctamente, pero se omitirán los cambios. Para cambiar el
watch parámetros, primero debe cerrar el identificador de clave mediante una llamada a RegCloseKey, volver a abrir el identificador de clave mediante una llamada a RegOpenKeyEx y, a continuación, llamar a RegNotifyChangeKeyValue con los nuevos parámetros.
Cada vez que un proceso llama a RegNotifyChangeKeyValue con el mismo conjunto de parámetros, establece otra operación de espera, creando una fuga de recursos. Por lo tanto, compruebe que no llama a RegNotifyChangeKeyValue con los mismos parámetros hasta que se haya completado la operación de espera anterior.
Para supervisar las operaciones del Registro con más detalle, consulte Registro.
Windows XP/2000: Cuando se llama a RegNotifyChangeKeyValue para un identificador de clave determinado, las notificaciones de cambio se producen siempre y cuando el identificador de clave sea válido. Esto hace que una segunda llamada a RegNotifyChangeKeyValue devuelva inmediatamente, si se producen cambios provisionales entre la primera y la segunda llamada. Si la función se usa de forma asincrónica, el identificador de eventos pasado se señalará inmediatamente si se producen cambios en el intermedio.
Ejemplos
En el siguiente programa se muestra cómo usar 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;
}
}
Requisitos
| Cliente mínimo compatible | Windows 2000 Professional [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows 2000 Server [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | winreg.h (incluye Windows.h) |
| Library | Advapi32.lib |
| Archivo DLL | Advapi32.dll |