FltAllocateContext 함수(fltkernel.h)

아티클
02/06/2025

FltAllocateContext 루틴은 지정된 컨텍스트 형식에 대한 컨텍스트 구조를 할당합니다.

통사론

NTSTATUS FLTAPI FltAllocateContext(
  [in]  PFLT_FILTER      Filter,
  [in]  FLT_CONTEXT_TYPE ContextType,
  [in]  SIZE_T           ContextSize,
  [in]  POOL_TYPE        PoolType,
  [out] PFLT_CONTEXT     *ReturnedContext
);

매개 변수

[in] Filter

호출자에 대한 불투명 필터 포인터입니다. 이 매개 변수는 필수이며 NULL 수 없습니다.

[in] ContextType

할당할 컨텍스트의 형식을 나타내는 FLT_CONTEXT_TYPE 값입니다. ContextType 다음 중 하나일 수 있습니다.

값	의미
FLT_VOLUME_CONTEXT(0x0001)	볼륨 컨텍스트를 할당합니다.
FLT_INSTANCE_CONTEXT(0x0002)	인스턴스 컨텍스트를 할당합니다.
FLT_FILE_CONTEXT(0x0004)	파일 컨텍스트를 할당합니다.
FLT_STREAM_CONTEXT(0x0008)	스트림 컨텍스트를 할당합니다.
FLT_STREAMHANDLE_CONTEXT(0x0010)	스트림 핸들 컨텍스트를 할당합니다.
FLT_TRANSACTION_CONTEXT(0x0020)	트랜잭션 컨텍스트를 할당합니다.
FLT_SECTION_CONTEXT(0x0040)	섹션 컨텍스트를 할당합니다. Windows 8부터 사용할 수 있습니다.

[in] ContextSize

미니 필터 드라이버에서 정의한 컨텍스트 부분의 크기(바이트)입니다. MAXUSHORT 0보다 크고작거나 같아야 합니다. 고정 크기 컨텍스트의 경우 FLT_CONTEXT_REGISTRATION 구조에 지정된 크기 작거나 같아야 합니다. 미니 필터는 컨텍스트의 이 부분을 사용하여 자체와 관련된 컨텍스트 정보를 유지 관리합니다. FltMgr 컨텍스트 구조의 이 부분을 불투명하게 처리합니다. 이 매개 변수는 필수이며 0일 수 없습니다.

[in] PoolType

할당할 풀의 형식입니다. 이 매개 변수는 필수이며 다음 중 하나여야 합니다. 각 형식에 대한 자세한 설명은 POOL_TYPE 참조하세요. 자세한 내용은 비고를 참조하세요.

값	의미
NonPagedPool	페이지가 아닌 시스템 메모리입니다. ContextType FLT_VOLUME_CONTEXT 경우 PoolType NonPagedPool 합니다.
PagedPool	페이지 가능한 시스템 메모리입니다.
NonPagedPoolNx	NX(실행 안 됨) 비페이징 풀입니다.

[out] ReturnedContext

새로 할당된 컨텍스트의 주소를 받는 호출자 할당 변수에 대한 포인터입니다. 호출자는 더 이상 필요하지 않은 경우 FltReleaseContext 호출하여 이 컨텍스트를 해제할 책임이 있습니다.

반환 값

FltAllocateContext 다음 중 하나와 같이 STATUS_SUCCESS 또는 적절한 NTSTATUS 값을 반환합니다.

반환 코드	묘사
STATUS_FLT_CONTEXT_ALLOCATION_NOT_FOUND	필터 등록 시 지정된 형식의 컨텍스트에 대한 할당 정보가 제공되지 않았습니다. 또는 고정 크기 컨텍스트의 경우 요청된 ContextSize 지정된 ContextType대한 FLT_CONTEXT_REGISTRATION 구조에 지정된 크기보다 큽니다.
STATUS_FLT_DELETING_OBJECT	Filter 매개 변수에 지정된 미니 필터 드라이버가 삭제되고 있습니다. 오류 코드입니다.
STATUS_INSUFFICIENT_RESOURCES	FltAllocateContext 풀 할당 오류가 발생했습니다. 오류 코드입니다.
STATUS_INVALID_BUFFER_SIZE	ContextSizeMAXUSHORT초과할 수 없습니다. 오류 코드입니다.
STATUS_INVALID_PARAMETER	ContextType 또는 ContextSize 매개 변수에 잘못된 값이 지정되었습니다. 오류 코드입니다.
STATUS_NOT_SUPPORTED	파일 시스템은 스트림별 컨텍스트를 지원하지 않습니다. 오류 코드입니다.

발언

컨텍스트에 대한 자세한 내용은 미니 필터 컨텍스트 정보참조하세요.

FltAllocateContext 지정된 풀에서 지정된 형식의 컨텍스트를 할당합니다. Windows 11부터 ReturnedContext 가리키는 메모리가 0인지 여부는 다음과 같습니다.

가변 크기 컨텍스트의 경우 메모리가 0으로 보장됩니다.
메모리 콘텐츠는 호출자 제공 콜백 함수에 의해 할당된 고정 크기 컨텍스트에 대해 구현 정의됩니다.
그렇지 않으면 lookaside 목록 동작으로 인해 고정 크기 컨텍스트에 대해 메모리가 0으로 간주될 수 없습니다. 즉, lookaside 목록에서 반환된 항목이 새 할당이 아닌 이전에 lookaside 목록으로 해제된 메모리인 경우 0이 되지 않을 수 있습니다.

Windows 11 이전에는 반환된 컨텍스트의 내용이 0이 아닙니다.

PoolType 잘못된 값으로 설정하면 lookaside 목록이 무시되는 등의 예기치 않은 동작이 발생하여 lookaside 목록의 성능 이점이 손실될 수 있습니다. ContextAllocateCallback 콜백 함수가 있는 컨텍스트의 경우 잘못된 PoolType 인한 동작은 구현에 따라 달라집니다.

컨텍스트가 할당된 후 다음 표의 적절한 set-context 루틴에 ReturnedContext 포인터를 전달하여 개체에 설정할 수 있습니다.

컨텍스트 형식	Set-Context 루틴
FLT_FILE_CONTEXT	fltSetFileContext(Windows Vista부터 시작)
FLT_INSTANCE_CONTEXT	fltSetInstanceContext
FLT_SECTION_CONTEXT	FltCreateSectionForDataScan(Windows 8부터)
FLT_STREAM_CONTEXT	fltSetStreamContext
FLT_STREAMHANDLE_CONTEXT	fltSetStreamHandleContext
FLT_TRANSACTION_CONTEXT	fltSetTransactionContext(Windows Vista부터 시작)
FLT_VOLUME_CONTEXT	FltSetVolumeContext

미니 필터 드라이버가 DriverEntry 루틴에서 FltRegisterFilter 호출하는 경우 사용하는 각 컨텍스트 형식을 등록해야 합니다. 자세한 내용은 FLT_CONTEXT_REGISTRATION 구조체에 대한 참조 항목과 컨텍스트 형식 등록참조하세요.

FltAllocateContext 미니 필터 드라이버와 관련된 컨텍스트 구조 부분의 내용을 초기화하지 않습니다.

개체의 컨텍스트를 얻으려면 다음 표에서 FltGetContexts 또는 적절한 get-context 루틴을 호출합니다.

컨텍스트 형식	Get-Context 루틴
FLT_FILE_CONTEXT	fltGetFileContext(Windows Vista부터 시작)
FLT_INSTANCE_CONTEXT	fltGetInstanceContext
FLT_SECTION_CONTEXT	FltGetSectionContext(Windows 8부터)
FLT_STREAM_CONTEXT	fltGetStreamContext
FLT_STREAMHANDLE_CONTEXT	fltGetStreamHandleContext
FLT_TRANSACTION_CONTEXT	FltGetTransactionContext(Windows Vista부터 시작)
FLT_VOLUME_CONTEXT	fltGetVolumeContext

컨텍스트는 참조 계산되며 FltAllocateContext성공적으로 반환되면 ReturnedContext 가리키는 컨텍스트가 1의 참조 수를 가지도록 초기화되었습니다. 컨텍스트는 참조 수가 0에 도달하면 자동으로 해제됩니다. 컨텍스트에서 참조 수를 증가하려면 FltReferenceContext호출합니다.

컨텍스트에서 참조 수를 줄이려면 FltReleaseContext호출합니다.

컨텍스트는 참조 계산되므로 일반적으로 컨텍스트를 삭제할 필요가 없습니다. 컨텍스트를 명시적으로 삭제하려면 다음 표에서 FltDeleteContext 또는 적절한 삭제 컨텍스트 루틴을 호출합니다.

컨텍스트 형식	Delete-Context 루틴
FLT_FILE_CONTEXT	FltDeleteFileContext(Windows Vista부터 시작)
FLT_INSTANCE_CONTEXT	FltDeleteInstanceContext
FLT_SECTION_CONTEXT	FltCloseSectionForDataScan(Windows 8부터)
FLT_STREAM_CONTEXT	fltDeleteStreamContext
FLT_STREAMHANDLE_CONTEXT	FltDeleteStreamHandleContext
FLT_TRANSACTION_CONTEXT	FltDeleteTransactionContext(Windows Vista부터 시작)
FLT_VOLUME_CONTEXT	FltDeleteVolumeContext