Função RegNotifyChangeKeyValue (winreg.h)

Notifica o chamador sobre alterações nos atributos ou conteúdo de uma chave do Registro especificada.

Sintaxe

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

Parâmetros

[in] hKey

Um identificador para uma chave aberta do Registro. Esse identificador é retornado pela função RegCreateKeyEx ou RegOpenKeyEx . Também pode ser uma das seguintes chaves predefinidas:

HKEY_CLASSES_ROOTHKEY_CURRENT_CONFIGHKEY_CURRENT_USERHKEY_LOCAL_MACHINEHKEY_USERS Esse parâmetro deve ser um identificador local. Se RegNotifyChangeKeyValue for chamado com um identificador remoto, ele retornará ERROR_INVALID_HANDLE.

A chave deve ter sido aberta com o KEY_NOTIFY direito de acesso. Para obter mais informações, consulte Segurança de Chave do Registro e Direitos de Acesso.

[in] bWatchSubtree

Se esse parâmetro for TRUE, a função relatará alterações na chave especificada e em suas subchaves. Se o parâmetro for FALSE, a função relatará alterações somente na chave especificada.

[in] dwNotifyFilter

Um valor que indica as alterações que devem ser relatadas. Esse parâmetro pode usar um dos valores a seguir.

[in, optional] hEvent

Um identificador para um evento. Se o parâmetro fAsynchronous for TRUE, a função retornará imediatamente e as alterações serão relatadas sinalizando esse evento. Se fAsynchronous for FALSE, hEvent será ignorado.

[in] fAsynchronous

Se esse parâmetro for TRUE, a função retornará imediatamente e relatará alterações sinalizando o evento especificado. Se esse parâmetro for FALSE, a função não retornará até que ocorra uma alteração.

Se hEvent não especificar um evento válido, o parâmetro fAsynchronous não poderá ser TRUE.

Valor retornado

Se a função obtiver êxito, o valor retornado será ERROR_SUCCESS.

Se a função falhar, o valor de retorno será o código de erro diferente de zero definido em Winerror.h. Você pode usar a função FormatMessage com o sinalizador FORMAT_MESSAGE_FROM_SYSTEM para obter uma descrição genérica do erro.

Comentários

Essa função detecta uma única alteração. Depois que o chamador receber um evento de notificação, ele deverá chamar a função novamente para receber a próxima notificação.

Se a chave especificada for fechada, o evento será sinalizado. Isso significa que um aplicativo não deve depender da chave estar aberta após retornar de uma operação de espera no evento.

O sinalizador REG_NOTIFY_THREAD_AGNOSTIC introduzido no Windows 8 permite o uso de RegNotifyChangeKeyValue para threads do ThreadPool.

Se o thread chamado RegNotifyChangeKeyValue for encerrado, o evento será sinalizado. Para continuar monitorando alterações adicionais no valor da chave, chame RegNotifyChangeKeyValue novamente de outro thread.

Com exceção das chamadas RegNotifyChangeKeyValue com REG_NOTIFY_THREAD_AGNOSTIC definido, essa função deve ser chamada em threads persistentes. Se o thread de chamada for de um pool de threads e não for persistente, o evento será sinalizado sempre que o thread for encerrado, não apenas quando houver uma alteração no Registro. Para garantir resultados precisos, execute o trabalho do pool de threads em um thread persistente usando a função SetThreadpoolCallbackPersistent ou crie seu próprio thread usando a função CreateThread . (Para a API do pool de threads original, especifique WT_EXECUTEINPERSISTENTTHREAD usando a função QueueUserWorkItem .)

Essa função não deve ser chamada várias vezes com o mesmo valor para o hKey , mas valores diferentes para os parâmetros bWatchSubtree e dwNotifyFilter . A função terá êxito, mas as alterações serão ignoradas. Para alterar a
watch parâmetros, primeiro você deve fechar o identificador de chave chamando RegCloseKey, reabrir o identificador de chave chamando RegOpenKeyEx e, em seguida, chamar RegNotifyChangeKeyValue com os novos parâmetros.

Sempre que um processo chama RegNotifyChangeKeyValue com o mesmo conjunto de parâmetros, ele estabelece outra operação de espera, criando um vazamento de recursos. Portanto, marcar que você não está chamando RegNotifyChangeKeyValue com os mesmos parâmetros até que a operação de espera anterior seja concluída.

Para monitorar as operações do Registro com mais detalhes, consulte Registro.

Windows XP/2000: Quando RegNotifyChangeKeyValue é chamado para um identificador de chave específico, as notificações de alteração ocorrem desde que o identificador de chave seja válido. Isso faz com que uma segunda chamada para RegNotifyChangeKeyValue retorne imediatamente, se ocorrerem alterações nesse ínterim entre a primeira e a segunda chamadas. Se a função estiver sendo usada de forma assíncrona, o identificador de evento passado será sinalizado imediatamente se ocorrerem alterações nesse ínterim.

Exemplos

O programa a seguir ilustra como 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

Confira também

Regclosekey

RegDeleteKey

RegEnumKeyEx

RegEnumValue

RegQueryInfoKey

Regqueryvalueex

Funções do Registro