Функция ZwNotifyChangeKey (ntifs.h)

Подпрограмма ZwNotifyChangeKey позволяет драйверу запрашивать уведомление при изменении раздела реестра.

Синтаксис

NTSYSAPI NTSTATUS ZwNotifyChangeKey(
  [in]            HANDLE           KeyHandle,
  [in, optional]  HANDLE           Event,
  [in, optional]  PIO_APC_ROUTINE  ApcRoutine,
  [in, optional]  PVOID            ApcContext,
  [out]           PIO_STATUS_BLOCK IoStatusBlock,
  [in]            ULONG            CompletionFilter,
  [in]            BOOLEAN          WatchTree,
  [out, optional] PVOID            Buffer,
  [in]            ULONG            BufferSize,
  [in]            BOOLEAN          Asynchronous
);

Параметры

[in] KeyHandle

Обработайте ключ, чтобы зарегистрировать подпрограмму уведомления. Этот дескриптор создается с помощью успешного вызова ZwCreateKey или ZwOpenKey. Вызывающий объект должен иметь указанный KEY_NOTIFY доступ.

[in, optional] Event

Необязательный дескриптор создаваемого вызывающего события, который должен быть задан в состоянии Signaled после завершения операции. Если не значение NULL, вызывающий объект помещается в состояние ожидания до тех пор, пока операция не завершится успешно, в то время как событие задается в состояние Signaled.

[in, optional] ApcRoutine

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

• Для вызова режима ядра задайте для этого параметра указатель на структуру WORK_QUEUE_ITEM

[in, optional] ApcContext

Указатель на передачу в качестве аргумента в подпрограмму APC, на которую ApcRoutine. Этот аргумент требуется, если ApcRoutine не равно NULL, и его необходимо привести к типу PVOID. В противном случае, если ApcRoutine имеет значение NULL, задайте для этого параметра значение NULL.

Значение этого параметра зависит от того, вызывается ли подпрограмма из режима ядра или из пользовательского режима:

• Для вызова режима ядра задайте для этого параметра одно из следующих значений перечисления WORK_QUEUE_TYPE:

  • CriticalWorkQueue
  • DelayedWorkQueue

• Для вызова в пользовательском режиме этот параметр указывает на заданный вызывающим контекст для подпрограммы APC.

[out] IoStatusBlock

Указатель на структуру IO_STATUS_BLOCK, содержащую окончательное состояние и сведения об операции. Для успешных вызовов, возвращающих данные, число байтов, записанных в буфер буфера, предоставляется в IoStatusBlock—>information.

[in] CompletionFilter

Битовые маски операций, которые вызывают уведомление драйвера. Укажите один или несколько следующих флагов:

[in] WatchTree

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

[out, optional] Buffer

Скрытный. Укажите ЗНАЧЕНИЕ NULL.

[in] BufferSize

Скрытный. Укажите ноль.

[in] Asynchronous

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

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

Подпрограмма ZwNotifyChangeKey возвращает STATUS_SUCCESS при успешном выполнении или соответствующее значение NTSTATUS в противном случае. Если вызывающий объект задает ЗНАЧЕНИЕ TRUE для параметра асинхронной, и событие еще не произошло, подпрограмма возвращает STATUS_PENDING.

Замечания

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

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

Это однократное уведомление. После изменения реестра необходимо снова вызвать ZwNotifyChangeKey , чтобы продолжить мониторинг.

Перед вызовом этой процедуры ключ необходимо открыть с помощью KEY_NOTIFY доступа.

Для асинхронной операции (асинхронная = TRUE):

• Если задано событие , он будет сигнализировать при возникновении изменений. Если событие равно NULL, то KeyHandle имеет состояние Signaled.
• Если указан ApcRoutine , он будет вызываться с ApcContext и IoStatusBlock.
• Если ни указано, сам KeyHandle становится сигнальным.

Для синхронной операции (асинхронная = FALSE):

• Блоки вызовов до тех пор, пока не произойдет изменение.
• Параметры события, ApcRoutine и ApcContext игнорируются.

Сеанс уведомлений заканчивается при закрытии KeyHandle .

Примечание. Параметр CompletionFilter и WatchTree задаются при первом вызове и применяются ко всем последующим вызовам с помощью одного и того же KeyHandle. Эти параметры игнорируются при последующих вызовах.

Уведомления реестра удерживают дескриптор, который предотвращает операции выгрузки hive (например , RegUnloadKey) до закрытия. В настоящее время нет механизма для драйвера, чтобы иметь уведомление, которое не будет блокировать RegUnloadKey. Драйверы могут попытаться заранее отменить уведомления, когда отслеживаемый процесс или сеанс пользователя завершается, чтобы избежать блокировки допустимых операций управления hive.

Если вызов функции ZwNotifyChangeKey происходит в пользовательском режиме, следует использовать имя "NtNotifyChangeKey" вместо "ZwNotifyChangeKey".

Для вызовов драйверов в режиме ядра NtXxx и ZwXxx версии подпрограммы Windows Native System Services могут вести себя по-разному в том, как они обрабатывают и интерпретируют входные параметры. Дополнительные сведения о связи между NtXxx и ZwXxx версиями подпрограммы см. в разделе Using Nt and Zw Versions of the Native System Services Routines.

Требования

См. также

IO_STATUS_BLOCK

WORK_QUEUE_ITEM

WORK_QUEUE_TYPE

ZwCreateKey

ZwOpenKey