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)	配置實例內容。
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 值，例如下列其中一項：

傳回碼	Description
STATUS_FLT_CONTEXT_ALLOCATION_NOT_FOUND	在篩選註冊時，未提供指定型別內容的配置資訊。或者，對於固定大小的內容，要求的ContextSize大於指定之ContextTypeFLT_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	從 Windows Vista) 開始的 FltSetFileContext (
FLT_INSTANCE_CONTEXT	FltSetInstanceContext
FLT_SECTION_CONTEXT	FltCreateSectionForDataScan (從 Windows 8) 開始
FLT_STREAM_CONTEXT	FltSetStreamContext
FLT_STREAMHANDLE_CONTEXT	FltSetStreamHandleContext
FLT_TRANSACTION_CONTEXT	從 Windows Vista) 開始的 FltSetTransactionContext (
FLT_VOLUME_CONTEXT	FltSetVolumeContext

當迷你篩選驅動程式從其 DriverEntry 例程呼叫 FltRegisterFilter 時，它必須註冊它所使用的每個內容類型。如需詳細資訊，請參閱 FLT_CONTEXT_REGISTRATION 結構的參考專案，以及註冊內容類型。

FltAllocateContext 不會初始化迷你篩選驅動程式專屬內容結構部分的內容。

若要取得對象的內容，請從下表呼叫 FltGetContexts 或適當的 get-context 例程。

內容類型	Get-Context 例程
FLT_FILE_CONTEXT	從 Windows Vista) 開始的 FltGetFileContext (
FLT_INSTANCE_CONTEXT	FltGetInstanceContext
FLT_SECTION_CONTEXT	FltGetSectionContext (從 Windows 8) 開始
FLT_STREAM_CONTEXT	FltGetStreamContext
FLT_STREAMHANDLE_CONTEXT	FltGetStreamHandleContext
FLT_TRANSACTION_CONTEXT	從 Windows Vista ) 開始的 FltGetTransactionContext (
FLT_VOLUME_CONTEXT	FltGetVolumeContext

內容會進行參考計數，而且從 FltAllocateContext 成功傳回時， ReturnedContext 所指向的內容已初始化為參考計數為 1。當內容參考計數達到零時，會自動釋放內容。若要遞增內容上的參考計數，請呼叫 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