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
| Cliente mínimo com suporte | Windows 2000 Professional [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows 2000 Server [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | winreg.h (inclua Windows.h) |
| Biblioteca | Advapi32.lib |
| DLL | Advapi32.dll |