FltCbdqInitialize 함수(fltkernel.h)

아티클
02/06/2025

FltCbdqInitialize는 미니 필터 드라이버의 콜백 데이터 큐 디스패치 테이블을 초기화합니다.

통사론

NTSTATUS FLTAPI FltCbdqInitialize(
  [in]      PFLT_INSTANCE                                 Instance,
  [in, out] PFLT_CALLBACK_DATA_QUEUE                      Cbdq,
  [in]      PFLT_CALLBACK_DATA_QUEUE_INSERT_IO            CbdqInsertIo,
  [in]      PFLT_CALLBACK_DATA_QUEUE_REMOVE_IO            CbdqRemoveIo,
  [in]      PFLT_CALLBACK_DATA_QUEUE_PEEK_NEXT_IO         CbdqPeekNextIo,
  [in]      PFLT_CALLBACK_DATA_QUEUE_ACQUIRE              CbdqAcquire,
  [in]      PFLT_CALLBACK_DATA_QUEUE_RELEASE              CbdqRelease,
  [in]      PFLT_CALLBACK_DATA_QUEUE_COMPLETE_CANCELED_IO CbdqCompleteCanceledIo
);

매개 변수

[in] Instance

콜백 데이터 큐를 초기화할 인스턴스에 대한 불투명 인스턴스 포인터입니다.

[in, out] Cbdq

미니 필터 드라이버에서 할당한 콜백 데이터 큐에 대한 포인터입니다.

[in] CbdqInsertIo

호출자가 제공한 삽입 콜백 루틴에 대한 포인터입니다. 필터 관리자는 이 루틴을 호출하여 지정된 콜백 데이터 구조를 큐에 삽입합니다. 이 루틴은 다음과 같이 선언됩니다.

typedef NTSTATUS
(*PFLT_CALLBACK_DATA_QUEUE_INSERT_IO)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _In_ PFLT_CALLBACK_DATA Cbd,
      _In_opt_ PVOID InsertContext
      );

Cbdq

미니 필터 드라이버의 취소 안전 콜백 데이터 큐에 대한 포인터입니다. 이 큐는 FltCbdqInitialize호출하여 초기화되어야 합니다.

도심

큐에 삽입할 콜백 데이터 구조에 대한 포인터입니다.

InsertContext

FltCbdqInsertIoInsertContext 매개 변수로 전달된 컨텍스트 정보 포인터입니다.

[in] CbdqRemoveIo

호출자 제공 제거 콜백 루틴에 대한 포인터입니다. 필터 관리자는 이 루틴을 호출하여 큐에서 지정된 콜백 데이터 구조를 제거합니다. 이 루틴은 다음과 같이 선언됩니다.

typedef VOID
(*PFLT_CALLBACK_DATA_QUEUE_REMOVE_IO)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _In_ PFLT_CALLBACK_DATA Cbd
      );

Cbdq

미니 필터 드라이버의 취소 안전 콜백 데이터 큐에 대한 포인터입니다. 이 큐는 FltCbdqInitialize호출하여 초기화되어야 합니다.

도심

큐에서 제거할 콜백 데이터 구조에 대한 포인터입니다.

[in] CbdqPeekNextIo

호출자가 제공한 피킹 콜백 루틴에 대한 포인터입니다. Filter Manager는 이 함수를 호출하여 큐의 PeekContext 일치하는 다음 I/O 작업에 대한 포인터를 가져옵니다. 또는 Cbd NULL 경우 큐에서 일치하는 첫 번째 I/O 작업에 대한 포인터를 가져옵니다. 미니 필터 드라이버는 PeekContext 의미를 완전히 정의하고 I/O 작업이 지정된 PeekContext일치하는 시기를 정의합니다. 이 루틴은 다음과 같이 선언됩니다.

typedef PFLT_CALLBACK_DATA
(*PFLT_CALLBACK_DATA_QUEUE_PEEK_NEXT_IO)(
      _In_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _In_opt_ PFLT_CALLBACK_DATA Cbd,
      _In_opt_ PVOID PeekContext
      );

Cbdq

미니 필터 드라이버의 취소 안전 콜백 데이터 큐에 대한 포인터입니다. 이 큐는 FltCbdqInitialize호출하여 초기화되어야 합니다.

도심

PeekContext 일치 항목 검색을 시작하기 위해 큐의 위치를 표시하는 콜백 데이터 구조에 대한 포인터입니다. Cbd NULL 경우 검색은 큐의 머리에서 시작됩니다.

PeekContext

FltCbdqRemoveNextIoPeekContext 매개 변수로 전달된 컨텍스트 정보 포인터입니다.

[in] CbdqAcquire

호출자가 제공한 큐 잠금 콜백 루틴 획득에 대한 포인터입니다. 필터 관리자는 큐에서 항목을 삽입하거나 제거하기 전에 이 루틴을 호출하여 큐에 대한 잠금을 획득합니다. 이 루틴은 다음과 같이 선언됩니다.

typedef VOID
(*PFLT_CALLBACK_DATA_QUEUE_ACQUIRE)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _Out_opt_ PKIRQL Irql
      );

Cbdq

미니 필터 드라이버의 취소 안전 콜백 데이터 큐에 대한 포인터입니다. 이 큐는 FltCbdqInitialize호출하여 초기화되어야 합니다.

Irql

현재 IRQL을 수신하는 시스템 제공 변수에 대한 포인터입니다. 동일한 변수가 해당 CbdqRelease 루틴에 전달됩니다.

[in] CbdqRelease

호출자가 제공한 릴리스 큐 잠금 콜백 루틴에 대한 포인터입니다. 필터 관리자는 이 루틴을 호출하여 해당 CbdqAcquire 루틴을 호출하여 얻은 잠금을 해제합니다. 이 루틴은 다음과 같이 선언됩니다.

typedef VOID
(*PFLT_CALLBACK_DATA_QUEUE_RELEASE)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _In_opt_ KIRQL Irql
      );

Cbdq

미니 필터 드라이버의 취소 안전 콜백 데이터 큐에 대한 포인터입니다. 이 큐는 FltCbdqInitialize호출하여 초기화되어야 합니다.

Irql

해당 CbdqAcquire 루틴에 대한 Irql 매개 변수로 현재 IRQL을 수신한 것과 동일한 시스템 제공 변수입니다.

[in] CbdqCompleteCanceledIo

호출자가 제공한 취소 루틴에 대한 포인터입니다. 필터 관리자는 이 루틴을 호출하여 미니 필터 드라이버에 신호를 보내 취소된 I/O 작업을 완료합니다. 이 루틴은 다음과 같이 선언됩니다.

typedef VOID
(*PFLT_CALLBACK_DATA_QUEUE_COMPLETE_CANCELED_IO)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _Inout_ PFLT_CALLBACK_DATA Cbd
      );

Cbdq

미니 필터 드라이버의 취소 안전 콜백 데이터 큐에 대한 포인터입니다. 이 큐는 FltCbdqInitialize호출하여 초기화되어야 합니다.

도심

취소된 I/O 작업의 콜백 데이터 구조에 대한 포인터입니다.

반환 값

FltCbdqInitialize STATUS_SUCCESS 또는 적절한 NTSTATUS 값을 반환합니다.

발언

새로 초기화된 콜백 데이터 큐는 활성화된 상태입니다. 즉, 콜백 데이터 구조 항목을 큐에 삽입할 수 있습니다. FltCbdqDisable 호출하여 큐를 사용하지 않도록 설정하고 FltCbdqEnable호출하여 다시 활성화할 수 있습니다.

미니 필터 드라이버는 FltCbdqXxx 루틴을 사용하여 IRP 기반 I/O 작업에 대한 콜백 데이터 큐를 구현할 수 있습니다. 미니 필터 드라이버는 이러한 루틴을 사용하여 큐를 취소로부터 안전하게 만들 수 있습니다. 시스템은 미니 필터 드라이버에 대한 I/O 취소를 투명하게 처리합니다.

FltCbdqXxx 루틴은 IRP 기반 I/O 작업에만 사용할 수 있습니다. 지정된 콜백 데이터 구조가 IRP 기반 I/O 작업을 나타내는지 여부를 확인하려면 FLT_IS_IRP_OPERATION 매크로를 사용합니다.

미니 필터 드라이버는 큐에 대한 내부 구현을 사용할 수 있습니다. 필터 관리자는 FltCbdqInitialize제공하는 디스패치 루틴 집합을 통해서만 미니 필터 드라이버의 큐 구현과 상호 작용합니다.

시스템은 필요에 따라 큐를 자동으로 잠그고 잠금을 해제합니다. 미니 필터 드라이버는 CbdqInsertIo, CbdqRemoveIo및 CbdqPeekNextIo 루틴 내에 잠금을 구현하지 않습니다.

미니 필터 드라이버는 운영 체제의 동기화 기본 형식을 CbdqAcquire 잠금 메커니즘으로 사용하고 스핀 잠금, 뮤텍스 개체또는 리소스 변수같은 CbdqRelease 루틴을 사용할 수 있습니다. 미니 필터 드라이버가 큐를 보호하기 위해 뮤텍스 또는 리소스가 아닌 스핀 잠금을 사용하는 경우 IRQL <= DISPATCH_LEVEL FltCbdqXxx 루틴을 호출할 수 있습니다. 뮤텍스 또는 리소스를 사용하는 경우 FltCbdqInitialize제외한 이러한 루틴을 호출할 때 미니 필터 드라이버가 IRQL <= APC_LEVEL 실행되어야 합니다.

미니 필터 드라이버는 큐를 직접 조작하지 않습니다. 대신 fltCbdqInsertIo , FltCbdqRemoveIo및 FltCbdqRemoveNextIo 호출하여 콜백 데이터 구조를 추가하거나 제거합니다. 이러한 루틴은 다시 fltCbdqInitialize를위해 미니 필터 드라이버가 제공한 콜백 함수를 호출합니다.

미니 필터 드라이버는 다음과 같이 큐 루틴을 구현해야 합니다.

Cbdq 루틴	이행
CbdqInsertIo	지정된 콜백 데이터 구조를 큐에 삽입합니다.
CbdqRemoveIo	큐에서 지정된 콜백 데이터 구조를 제거합니다.
CbdqPeekNextIo	이 루틴을 사용하면 시스템이 큐에서 PeekContext 일치하는 콜백 데이터 구조를 반복할 수 있습니다. Cbd = CbdPeekNextIo(Cbdq, NULL, PeekContext) 큐의 첫 번째 일치 항목을 반환해야합니다. 및 CbdqPeekNextIo(Cbdq, Cbd, PeekContext) 큐에서 지정된 콜백 데이터 구조 후 다음 일치 항목을 반환해야합니다. 미니 필터 드라이버는 PeekContext 의미를 완전히 정의하고 콜백 데이터 구조가 PeekContext 값과 일치하는 시기를 정의합니다.
CbdqAcquire	이 루틴은 다른 스레드가 액세스할 수 없도록 큐를 잠급니다. 미니 필터 드라이버는 잠금 메커니즘을 사용하여 큐를 잠글 수 있습니다. 미니 필터 드라이버가 KeAcquireSpinLock 루틴을 사용하는 경우 미니 필터 드라이버는 루틴의 Irql 매개 변수가 가리키는 메모리 위치를 사용하여 IRQL을 저장할 수 있습니다. 그렇지 않으면 미니 필터 드라이버는 해당 매개 변수를 무시할 수 있습니다.
CbdqRelease	이 루틴은 CbdqAcquire의해 만들어진 큐의 잠금을 해제해야합니다. 미니 필터 드라이버가 스핀 잠금을 사용하고 CbdqAcquireIrql 매개 변수에서 IRQL 값을 반환하는 경우 시스템은 CbdqReleaseIrql 매개 변수에 해당 값을 전달합니다. 미니 필터 드라이버는 IRQL을 사용하여 KeReleaseSpinLock호출하여 스핀 잠금의 잠금을 해제할 수 있습니다. 그렇지 않으면 미니 필터 드라이버는 Irql 매개 변수를 무시할 수 있습니다.
CbdqCompleteCanceledIo	이 루틴은 취소된 I/O 작업을 완료해야 합니다. 일반적으로 미니 필터 드라이버는 FltCompletePendedPreOperation(데이터, FLT_PREOP_COMPLETE, NULL)만 호출할 수 있습니다. 미니 필터 드라이버는 콜백 데이터 구조를 큐에서 제거 할 필요가 없습니다 - 필터 관리자는 CbdqCompleteCanceledIo호출하기 전에 큐의 CbdqRemoveIo 자동으로 호출합니다.