FltAllocateExtraCreateParameterList 函式 (fltkernel.h)

發行項
03/01/2024

FltAllocateExtraCreateParameterList 例程會為額外的建立參數配置分頁集區內存， (ECP) 列表結構，併產生該結構的指標。

語法

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

參數

[in] Filter

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

[in] Flags

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

[out] EcpList

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

傳回值

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

傳回碼	Description
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型別變數的指標。

Syntax

struct ECP_LIST {
  ;      // Reserved.
};

ECP_LIST 結構是在 Ntifs.h 中宣告， (包括 Ntifs.h) 。

規格需求

需求	值
最低支援的用戶端	此例程從 Windows Vista 開始可供使用。
目標平台	Universal
標頭	fltkernel.h (包含 Fltkernel.h)
程式庫	FltMgr.lib
IRQL	<= APC_LEVEL