Función RegNotifyChangeKeyValue (winreg.h)

Notifica al autor de la llamada los cambios 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
);

Parameters

[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_CONFIG, HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE, HKEY_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 claves 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 solo los cambios 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 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.

Observaciones

Esta función detecta un único cambio. Después de que el autor de la llamada reciba 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 se abra 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 el subproceso que llamó a RegNotifyChangeKeyValue se cierra, se señala el evento. Para continuar 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 de llamada procede 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
Los parámetros watch, primero debe cerrar el identificador de clave mediante una llamada a RegCloseKey, volver a abrir el identificador de clave llamando 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 está llamando 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: When RegNotifyChangeKeyValue se llama a para un identificador de clave determinado, se producen notificaciones de cambio siempre que el identificador de clave sea válido. Esto hace que una segunda llamada a RegNotifyChangeKeyValue se devuelva inmediatamente, si se producen cambios en el intervalo entre las llamadas primera y segunda. Si la función se usa de forma asincrónica, el identificador de eventos pasado se indicará inmediatamente si se producen cambios en el intervalo.

Examples

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

Consulte también

RegCloseKey

RegDeleteKey

RegEnumKeyEx

RegEnumValue

RegQueryInfoKey

RegQueryValueEx

Funciones del Registro