FltAllocateContext 함수(fltkernel.h)

아티클
03/15/2024

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)	instance 컨텍스트를 할당합니다.
FLT_FILE_CONTEXT(0x0004)	파일 컨텍스트를 할당합니다.
FLT_STREAM_CONTEXT(0x0008)	스트림 컨텍스트를 할당합니다.
FLT_STREAMHANDLE_CONTEXT(0x0010)	스트림 핸들 컨텍스트를 할당합니다.
FLT_TRANSACTION_CONTEXT(0x0020)	트랜잭션 컨텍스트를 할당합니다.
FLT_SECTION_CONTEXT(0x0040)	섹션 컨텍스트를 할당합니다. Windows 8 시작해서 사용할 수 있습니다.

[in] ContextSize

미니필터 드라이버에서 정의한 컨텍스트 부분의 크기(바이트)입니다. 0보다 크고 MAXUSHORT보다 작거나 같아야 합니다. 고정 크기 컨텍스트의 경우 는 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	ContextSize 는 MAXUSHORT보다 클 수 없습니다. 오류 코드입니다.
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