FltCbdqInitialize 함수(fltkernel.h)

아티클
08/07/2023

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

콜백 데이터 큐를 초기화할 instance 대한 불투명 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

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

[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

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

[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

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