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

작업이 완료될 때 신호됨 상태로 설정될 호출자가 만든 이벤트에 대한 선택적 핸들입니다. NULL이 아닌 경우 호출자는 작업이 성공할 때까지 대기 상태로 전환되며, 이때 이벤트가 Signaled 상태로 설정됩니다.

[in, optional] ApcRoutine

작업이 완료된 후 실행할 호출자 제공 APC 루틴에 대한 포인터입니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다.

• 커널 모드 호출의 경우 이 매개 변수를 WORK_QUEUE_ITEM 구조체에 대한 포인터로 설정합니다.

[in, optional] ApcContext

ApcRoutine 가리키는 APC 루틴에 인수로 전달하는 포인터입니다. 이 인수는 ApcRoutine NULL이 아니고 PVOID 형식으로 캐스팅해야 하는 경우에 필요합니다. 그렇지 않은 경우 ApcRoutine NULL이면 이 매개 변수도 NULL로 설정합니다.

이 매개 변수의 의미는 루틴이 커널 모드에서 호출되는지 아니면 사용자 모드에서 호출되는지에 따라 달라집니다.

• 커널 모드 호출의 경우 이 매개 변수를 다음 WORK_QUEUE_TYPE 열거형 값 중 하나로 설정합니다.

  • CriticalWorkQueue
  • DelayedWorkQueue

• 사용자 모드 호출의 경우 이 매개 변수는 APC 루틴에 대해 호출자가 지정한 컨텍스트를 가리킵니다.

[out] IoStatusBlock

작업에 대한 최종 상태 및 정보를 포함하는 IO_STATUS_BLOCK 구조체에 대한 포인터입니다. 데이터를 반환하는 성공적인 호출의 경우 Buffer 기록된 바이트 수가 IoStatusBlock->Information제공됩니다.

[in] CompletionFilter

드라이버에 알림을 표시하는 작업의 비트 마스크입니다. 다음 플래그 중 하나 이상을 지정합니다.

[in] WatchTree

TRUE이면 지정된 키의 모든 하위 키에 대한 변경 내용에 대한 알림이 드라이버에 표시됩니다. FALSE이면 지정된 키에 대한 변경 내용에 대해서만 드라이버에 알림이 표시됩니다.

[out, optional] Buffer

예약. NULL을 지정합니다.

[in] BufferSize

예약. 0을 지정합니다.

[in] Asynchronous

FALSE이면 지정된 이벤트가 발생할 때까지 루틴이 반환되지 않습니다. TRUE이면 루틴이 즉시 반환됩니다.

반환 값

ZwNotifyChangeKey 루틴은 성공에 대한 STATUS_SUCCESS 반환하거나, 그렇지 않으면 적절한 NTSTATUS 값을 반환합니다. 호출자가 비동기 매개 변수에 대해 TRUE를 지정하고 이벤트가 아직 발생하지 않은 경우 루틴은 STATUS_PENDING 반환합니다.

발언

ZwNotifyChangeKey 는 레지스트리 키에서 변경 내용을 모니터링하고 수정이 발생할 때 호출자에게 알깁니다.

루틴은 CompletionFilter 플래그에 따라 변경 내용을 위해 지정된 키(및 선택적으로 해당 하위 트리)를 모니터링합니다. 변경이 발생하면 시스템은 이벤트 신호, APC 콜백 또는 동기 완료를 통해 호출자에게 알릴 수 있습니다.

일회성 알림입니다. 레지스트리 변경으로 인해 알림이 트리거되면 ZwNotifyChangeKey 를 다시 호출하여 모니터링을 계속해야 합니다.

이 루틴을 호출하기 전에 KEY_NOTIFY 액세스 권한으로 키를 열어야 합니다.

비동기 작업의 경우(비동기 = TRUE):

• Event를 지정하면 변경이 발생할 때 신호가 전송됩니다. 이벤트가 NULL이면 KeyHandle이 Signaled 상태로 설정됩니다.
• ApcRoutine이 지정된 경우 ApcContext 및 IoStatusBlock을 사용하여 호출됩니다.
• 둘 다 지정하지 않으면 KeyHandle 자체가 신호를 보낼 수 있게 됩니다.

동기 작업의 경우(비동기 = FALSE):

• 호출은 변경이 발생할 때까지 차단됩니다.
• 이벤트, ApcRoutine 및 ApcContext 매개 변수는 무시됩니다.

KeyHandle을 닫으면 알림 세션이 종료됩니다.

참고: CompletionFilter 및 WatchTree 는 첫 번째 호출에서 설정되며 동일한 KeyHandle을 사용하여 모든 후속 호출에 적용됩니다. 이러한 매개 변수는 후속 호출에서 무시됩니다.

레지스트리 알림에는 Hive 언로드 작업(예: RegUnloadKey)이 닫히기 전까지 방지되는 핸들이 있습니다. 현재 드라이버가 RegUnloadKey를 차단하지 않는 알림을 가질 수 있는 메커니즘은 없습니다. 드라이버는 모니터링되는 프로세스 또는 사용자 세션이 종료될 때 알림을 사전에 취소하여 합법적인 Hive 관리 작업을 차단하지 않도록 할 수 있습니다.

ZwNotifyChangeKey 함수에 대한 호출이 사용자 모드에서 발생하는 경우 "ZwNotifyChangeKey" 대신 "NtNotifyChangeKey" 이름을 사용해야 합니다.

커널 모드 드라이버의 호출의 경우 NtXxx 및 ZwXxx 버전의 Windows Native System Services 루틴은 입력 매개 변수를 처리하고 해석하는 방식으로 다르게 동작할 수 있습니다. NtXxx ZwXxx 루틴 버전 간의 관계에 대한 자세한 내용은 네이티브 시스템 서비스 루틴Nt 및 Zw 버전 사용 참조하세요.

요구 사항

참고 항목

IO_STATUS_BLOCK

WORK_QUEUE_ITEM

WORK_QUEUE_TYPE

ZwCreateKey

ZwOpenKey