FltAllocateExtraCreateParameterList 函式（fltkernel.h）

發行項
02/06/2025

FltAllocateExtraCreateParameterList 例程會為額外的建立參數（ECP）清單結構配置分頁集區內存，併產生該結構的指標。

語法

NTSTATUS FLTAPI FltAllocateExtraCreateParameterList(
  [in]  PFLT_FILTER                  Filter,
  [in]  FSRTL_ALLOCATE_ECPLIST_FLAGS Flags,
  [out] PECP_LIST                    *EcpList
);

參數

[in] Filter

迷你篩選驅動程式的不透明篩選指標。此指標會唯一識別迷你篩選驅動程式，只要載入迷你篩選驅動程式，就會維持不變。

[in] Flags

定義集區配置選項。如果FSRTL_ALLOCATE_ECPLIST_FLAG_CHARGE_QUOTA旗標與 Flags 參數搭配使用位 OR 作業，則例程配置的任何集區都會針對目前進程的記憶體配額收費。

[out] EcpList

接收初始化之 ECP 清單結構的指標。如果例程無法配置足夠的集區，*EcpList 將會 NULL，而且例程會傳回狀態代碼STATUS_INSUFFICIENT_RESOURCES。

傳回值

FltAllocateExtraCreateParameterList 可以傳回下列其中一個值：

傳回碼	描述
STATUS_INSUFFICIENT_RESOURCES	FltAllocateExtraCreateParameterList 無法配置足夠的記憶體給 ECP 清單結構。在這裡情況下，EcpList 將會 NULL*。
STATUS_SUCCESS	ECP 清單結構已成功配置和初始化。在此情況下，初始化清單結構的指標會在 *EcpList 參數中傳回。

言論

作系統是否自動釋放 FltAllocateExtraCreateParameterList 配置的記憶體取決於呼叫 fltAllocateExtraCreateParameterList 時，如下列情況所示：

呼叫端可以叫用 FltAllocateExtraCreateParameterList 來配置ECP_LIST，並在呼叫端叫用 FltCreateFileEx2 例程之前新增一或多個 ECP 內容結構。在此情況下，作系統不會釋放任何 ECP 內容結構。因此，呼叫端可以對具有相同 ECP 集合的 FltCreateFileEx2 進行多個呼叫。當呼叫端使用 ECP_LIST 完成時，呼叫端必須呼叫 FltFreeExtraCreateParameterList 例程，以釋放ECP_LIST。
當文件系統篩選驅動程式處理 IRP_MJ_CREATE 要求時，文件系統篩選驅動程式可以呼叫 FltInsertExtraCreateParameter，將 ECP 附加至現有的ECP_LIST。如果ECP_LIST不存在，呼叫端必須呼叫 FltAllocateExtraCreateParameterList 以建立ECP_LIST。在此情況下，建立作業完成時，I/O 管理員會自動清除ECP_LIST和 ECP 內容結構。這可讓篩選驅動程式的ECP在重新分析點的處理中正確傳播。此程式可能需要產生多個IRP_MJ_CREATE要求。

如果FSRTL_ALLOCATE_ECPLIST_FLAG_CHARGE_QUOTA旗標與 Flags 參數搭配使用，則會配置一般可分頁集區。否則，會使用內部查閱清單來配置可分頁集區。

ECP_LIST 結構

ECP_LIST是作系統所宣告的不透明結構。 ECP_LIST包含額外的建立參數（ECP）專案清單。

FltAllocateExtraCreateParameterList 例程必須用來配置 ECP_LIST 結構的記憶體。作系統不會自動釋放由 FltAllocateExtraCreateParameterList 配置的記憶體;呼叫 FltFreeExtraCreateParameterList 例程，才能明確解除分配。請注意，呼叫 fltFreeExtraCreateParameterList 時，會自動釋放任何剩餘的 ECP 清單元素。

PECP_LIST數據類型是用來宣告類型ECP_LIST變數的指標。

語法

struct ECP_LIST {
  ;      // Reserved.
};

ECP_LIST 結構會在 Ntifs.h 中宣告（包括 Ntifs.h）。

要求

要求	價值
最低支援的用戶端	從 Windows Vista 開始，即可使用此例程。
目標平臺	普遍
標頭	fltkernel.h （包括 Fltkernel.h）
連結庫	FltMgr.lib
IRQL	<= APC_LEVEL