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;對於固定大小的內容，必須小於或等於 FLT_CONTEXT_REGISTRATION 結構中指定的 Size。小型篩選會使用內容中的這個部分來維護本身特有的內容資訊。 FltMgr 會將此部分的內容結構視為不透明。這是必要參數，不能為零。

[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 結構中指定的 Size。
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 指向的記憶體是否相依如下：

對於可變大小的內容，記憶體保證為零。
記憶體內容是針對呼叫端提供的回呼函式所配置的固定大小內容所定義的實作。
否則，由於外觀清單行為，無法假設固定大小內容的記憶體為零。也就是說，如果從 lookaside 清單傳回的專案是先前釋放至 lookaside 清單的記憶體，而不是新的配置，則可能不會將它歸零。

在 Windows 11 之前，傳回內容的內容不會為零。

將 PoolType 設定為無效值可能會導致非預期的行為，例如造成略過 lookaside 列表，因而遺失 lookaside 列表的效能優點。對於具有 ContextAllocateCallback 回呼函式的內容，由於 poolType 無效而造成行為與實作相依。

配置內容之後，即可在對象上設定它，方法是從下表將 returnedContext 指標傳遞給適當的 set-context 例程。

內容類型	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成功傳回時，ReturnedCon text 所指向的內容已初始化為具有 1 的參考計數。當內容的參考計數達到零時，會自動釋放內容。若要在內容上遞增參考計數，請呼叫 FltReferenceContext。

若要遞減內容上的參考計數，請呼叫 FltReleaseContext。

因為內容是參考計數，所以通常不需要刪除它們。若要明確刪除內容，請從下表呼叫 FltDeleteContext 或適當的 delete-context 例程。

內容類型	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