Функция RegNotifyChangeKeyValue (winreg.h)

Уведомляет вызывающий объект об изменениях атрибутов или содержимого указанного раздела реестра.

Syntax

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

Parameters

[in] hKey

Дескриптор открытого раздела реестра. Этот дескриптор возвращается функцией RegCreateKeyEx или RegOpenKeyEx . Он также может быть одним из следующих предопределенных ключей:

HKEY_CLASSES_ROOT, HKEY_CURRENT_CONFIG, HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE, HKEY_USERS.

Этот параметр должен быть локальным дескриптором. Если RegNotifyChangeKeyValue вызывается с удаленным дескриптором, он возвращает ERROR_INVALID_HANDLE.

Ключ должен быть открыт с помощью права доступа KEY_NOTIFY. Дополнительные сведения см. в разделе "Безопасность и права доступа к разделу реестра".

[in] bWatchSubtree

Если этот параметр имеет значение TRUE, функция сообщает об изменении указанного ключа и его вложенных ключей. Если параметр имеет значение FALSE, функция сообщает об изменении только указанного ключа.

[in] dwNotifyFilter

Значение, указывающее изменения, которые следует сообщить. Этот параметр может быть одним или несколькими из следующих значений.

[in, optional] hEvent

Дескриптор события. Если параметр fAsynchronous имеет значение TRUE, функция возвращается немедленно и сообщает об изменениях, сигналив об этом событии. Если fAsynchronous имеет значение FALSE, hEvent игнорируется.

[in] fAsynchronous

Если этот параметр имеет значение TRUE, функция возвращается немедленно и сообщает об изменениях, сигналив указанному событию. Если этот параметр имеет значение FALSE, функция не возвращается до тех пор, пока не произошло изменение.

Если hEvent не указывает допустимое событие, параметр fAsynchronous не может иметь значение TRUE.

Возвращаемое значение

Если функция выполнена успешно, возвращаемое значение ERROR_SUCCESS.

Если функция завершается ошибкой, возвращаемое значение представляет собой ненулевой код ошибки, определенный в Winerror.h. Функцию FormatMessage можно использовать с флагом FORMAT_MESSAGE_FROM_SYSTEM для получения универсального описания ошибки.

Замечания

Эта функция обнаруживает одно изменение. После того как вызывающий объект получает событие уведомления, он должен снова вызвать функцию, чтобы получить следующее уведомление.

Если указанный ключ закрыт, событие сигнализирует. Это означает, что приложение не должно зависеть от ключа, открытого после возвращения из операции ожидания события.

Флаг REG_NOTIFY_THREAD_AGNOSTIC, представленный в Windows 8, позволяет использовать потоки RegNotifyChangeKeyValue для потоков ThreadPool.

Если поток, который называется RegNotifyChangeKeyValue , завершает работу, событие сигнализирует. Чтобы продолжить мониторинг дополнительных изменений в значении ключа, снова вызовите RegNotifyChangeKeyValue из другого потока.

За исключением вызовов RegNotifyChangeKeyValue с набором REG_NOTIFY_THREAD_AGNOSTIC , эта функция должна вызываться в постоянных потоках. Если вызывающий поток находится из пула потоков и не является постоянным, событие сигнализирует каждый раз, когда поток завершается, а не только при изменении реестра. Чтобы обеспечить точные результаты, запустите пул потоков в постоянном потоке с помощью функции SetThreadpoolCallbackPersistent или создайте собственный поток с помощью функции CreateThread . (Для API исходного пула потоков укажите WT_EXECUTEINPERSISTENTTHREAD с помощью функции QueueUserWorkItem .)

Эта функция не должна вызываться несколько раз с одинаковым значением для hKey , но разные значения для параметров bWatchSubtree и dwNotifyFilter . Функция завершится успешно, но изменения будут игнорироваться. Изменение
Сначала необходимо закрыть дескриптор ключа, вызвав RegCloseKey, повторно открыть дескриптор ключа, вызвав RegOpenKeyEx, а затем вызвать RegNotifyChangeKeyValue с новыми параметрами.

Каждый раз, когда процесс вызывает RegNotifyChangeKeyValue с одним набором параметров, он устанавливает другую операцию ожидания, создавая утечку ресурсов. Поэтому убедитесь, что вы не вызываете RegNotifyChangeKeyValue с теми же параметрами до завершения предыдущей операции ожидания.

Дополнительные сведения о мониторинге операций реестра см. в разделе "Реестр".

Windows XP/2000: When RegNotifyChangeKeyValue вызывается для определенного дескриптора ключа, уведомления об изменениях происходят до тех пор, пока дескриптор ключа действителен. Это приводит к немедленному возвращению второго вызова RegNotifyChangeKeyValue , если любые изменения происходят в промежуточном периоде между первым и вторым вызовами. Если функция используется асинхронно, переданный дескриптор событий будет немедленно сигнализировать, если изменения происходят в промежуточном режиме.

Examples

В следующей программе показано, как использовать 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;
   }
}

Требования

См. также

RegCloseKey

RegDeleteKey

RegEnumKeyEx

RegEnumValue

RegQueryInfoKey

RegQueryValueEx

Функции реестра