FltAllocateExtraCreateParameter 函式 (fltkernel.h)

發行項
02/26/2024

FltAllocateExtraCreateParameter 例程會為使用者定義的額外建立參數配置分頁記憶體集區， (ECP) 內容結構，併產生該結構的指標。

語法

NTSTATUS FLTAPI FltAllocateExtraCreateParameter(
  [in]           PFLT_FILTER                                    Filter,
  [in]           LPCGUID                                        EcpType,
  [in]           ULONG                                          SizeOfContext,
  [in]           FSRTL_ALLOCATE_ECP_FLAGS                       Flags,
  [in, optional] PFSRTL_EXTRA_CREATE_PARAMETER_CLEANUP_CALLBACK CleanupCallback,
  [in]           ULONG                                          PoolTag,
  [out]          PVOID                                          *EcpContext
);

參數

[in] Filter

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

[in] EcpType

使用者定義 GUID 的指標，指出 ECP 內容結構的型別。如需詳細資訊，請參閱在驅動程式中使用 GUID 。

[in] SizeOfContext

使用者定義內容結構的大小，以位元組為單位。

[in] Flags

定義集區配置選項。下列描述當一或多個列出的旗標值使用位 OR 作業與 Flags 參數結合時，如何配置集區：

FSRTL_ALLOCATE_ECP_FLAG_NONPAGED_POOL - 將會配置非分頁集區。如果未使用此旗標值，則會配置分頁集區。
FSRTL_ALLOCATE_ECPLIST_FLAG_CHARGE_QUOTA - 此例程配置的所有集區都會根據目前進程的記憶體配額收費。

如果使用多個旗標，則會發生與已使用旗標值相關聯的所有效果。

[in, optional] CleanupCallback

類型為 PFSRTL_EXTRA_CREATE_PARAMETER_CLEANUP_CALLBACK 之迷你篩選定義的清除回呼例程的選擇性指標。刪除 FltAllocateExtraCreateParameter 例程) 所建立的 ECP 結構 (時，會呼叫清除回呼例程。如果清除回呼例程不適用，請將此參數設定為 NULL 。

[in] PoolTag

指定已配置記憶體的集區標籤。如需詳細資訊，請參閱 ExAllocatePoolWithTag 的 Tag 參數。

[out] EcpContext

接收已配置 ECP 內容結構的指標。如果例程無法配置足夠的集區， *EcpContext 會是 NULL ，而例程會傳回狀態代碼STATUS_INSUFFICIENT_RESOURCES。

傳回值

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

傳回碼	Description
STATUS_INSUFFICIENT_RESOURCES	FltAllocateExtraCreateParameter 無法為 ECP 結構配置足夠的記憶體。在此情況下， EcpContext 會是 NULL。
STATUS_SUCCESS	已成功配置 ECP 結構。在此情況下，會在 EcpContext 參數中傳回配置結構的指標。

備註

根據預設， FltAllocateExtraCreateParameter 例程會為使用者定義的 ECP 內容結構配置分頁記憶體集區。如果使用FSRTL_ALLOCATE_ECP_FLAG_NONPAGED_POOL位掩碼，如上所述，則會配置非分頁記憶體集區。配置此集區並初始化 ECP 內容結構之後， FltInsertExtraCreateParameter 例程會用來將 ECP 內容結構 (ECP 清單元素) 插入 ECP 清單結構， (ECP 清單) 。

操作系統不會自動釋放 FltAllocateExtraCreateParameter 例程所配置的記憶體集區。此記憶體集區最終必須使用下列其中一種方法來釋放：

呼叫 FltRemoveExtraCreateParameter 例程，從 ECP 清單中移除 ECP 內容結構，然後呼叫 FltFreeExtraCreateParameter 例程以釋放 ECP 內容結構本身。 ECP 清單仍然存在。
呼叫 FltFreeExtraCreateParameterList 例程 - 這會釋放 ECP 清單，包括 (ECP 內容結構) 的任何清單元素。 ECP 清單已終結。

不過，如果在處理IRP_MJ_CREATE要求時，文件系統或文件系統篩選驅動程式將ECP附加至現有或新建立的ECP_LIST，則IRP完成時會自動清除此ECP。因此，篩選驅動程式不需要清除動態新增的ECP。這可讓篩選驅動程式的ECP正確地傳播到重新分析點，也就是可能需要產生多個IRP_MJ_CREATE要求的程式。