Поделиться через


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

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

Синтаксис

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

Параметры

[in] hKey

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

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

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

[in] bWatchSubtree

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

[in] dwNotifyFilter

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

Значение Значение
REG_NOTIFY_CHANGE_NAME
0x00000001L
Уведомите вызывающего абонента о добавлении или удалении подраздела.
REG_NOTIFY_CHANGE_ATTRIBUTES
0x00000002L
Уведомлять вызывающего объекта об изменениях в атрибутах ключа, таких как сведения о дескрипторове безопасности.
REG_NOTIFY_CHANGE_LAST_SET
0x00000004L
Уведомите вызывающий объект об изменениях в значении ключа. Это может включать добавление или удаление значения, а также изменение существующего значения.
REG_NOTIFY_CHANGE_SECURITY
0x00000008L
Уведомите вызывающий объект об изменениях в дескрипторе безопасности ключа.
REG_NOTIFY_THREAD_AGNOSTIC
0x10000000L
Указывает, что время существования регистрации не должно быть привязано к времени существования потока, выполняющего вызов RegNotifyChangeKeyValue .
Примечание Это значение флага поддерживается только в Windows 8 и более поздних версиях.
 

[in, optional] hEvent

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

[in] fAsynchronous

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

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

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

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

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

Комментарии

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

Примечание В Windows NT, Windows 2000 и Windows XP вызов RegNotifyChangeKeyValue для определенного дескриптора ключа приводит к тому, что уведомления об изменениях будут появляться до тех пор, пока дескриптор ключа действителен. Это приводит к тому, что второй вызов RegNotifyChangeKeyValue возвращается немедленно, если в промежуточный период между первым и вторым вызовами произошли какие-либо изменения. Если API используется асинхронно, переданный дескриптор события будет немедленно сигнализировать, если произошли какие-либо промежуточные изменения.
 
Эту функцию нельзя использовать для обнаружения изменений в реестре, которые возникают в результате использования функции RegRestoreKey .

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

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

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

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

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

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

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

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

Примеры

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

Требования

   
Минимальная версия клиента Windows 2000 Professional [только классические приложения]
Минимальная версия сервера Windows 2000 Server [только классические приложения]
Целевая платформа Windows
Header winreg.h (включая Windows.h)
Библиотека Advapi32.lib
DLL Advapi32.dll

См. также раздел

RegCloseKey

RegDeleteKey

RegEnumKeyEx

RegEnumValue

RegQueryInfoKey

RegQueryValueEx

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