FsRtlAllocateExtraCreateParameter 函式（ntifs.h）

發行項
12/21/2024

FsRtlAllocateExtraCreateParameter 例程會為額外的建立參數（ECP）內容結構配置記憶體，併產生該結構的指標。

語法

NTSTATUS FsRtlAllocateExtraCreateParameter(
  [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] EcpType

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

[in] SizeOfContext

內容結構的大小，以位元組為單位。

[in] Flags

定義集區配置選項。下列說明當一或多個列出的旗標值使用位 OR 運算結合 Flags 參數時，如何配置集區：

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

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

[in, optional] CleanupCallback

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

[in] PoolTag

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

[out] EcpContext

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

傳回值

FltAllocateExtraCreateParameter 會傳回狀態代碼，例如下列其中一項：

傳回碼	描述
STATUS_INSUFFICIENT_RESOURCES	FsRtlAllocateExtraCreateParameter 無法配置足夠的記憶體給 ECP 結構。在這裡情況下，EcpContextNULL。
STATUS_SUCCESS	已成功配置 ECP 結構。在此情況下，會在ecpContext 參數傳回已配置結構的指標。

言論

根據預設，FsRtlAllocateExtraCreateParameter 例程會配置分頁記憶體集區給 ECP 內容結構。如果使用FSRTL_ALLOCATE_ECP_FLAG_NONPAGED_POOL位掩碼，如 Flags 參數中所述，則會配置非分頁記憶體集區。配置此集區並初始化 ECP 內容結構之後，FltInsertExtraCreateParameter 例程會用來將 ECP 內容結構（ECP 清單元素）插入 ECP 清單結構（ECP_LIST）。

如果呼叫端配置ECP_LIST，且一或多個 ECP 用於呼叫 IoCreateFileEx，則先前的描述是正確的。在此情況下，系統不會釋放任何 ECP，因此呼叫者可以使用相同的 ECP 集合，對 IoCreateFileEx 進行多個呼叫。不過，如果在處理IRP_MJ_CREATE要求時，文件系統或文件系統篩選驅動程式將ECP附加至現有或新建立的ECP_LIST，則IRP完成時，會自動清除此ECP。因此，篩選驅動程式不需要清除動態新增的ECP。這可讓篩選驅動程式的 ECP 在重新分析點之間正確傳播，此程式可能需要產生多個IRP_MJ_CREATE要求。

要求

要求	價值
最低支援的用戶端	FsRtlAllocateExtraCreateParameter 例程可從 Windows Vista 開始使用。
目標平臺	普遍
標頭	ntifs.h （include Ntifs.h）
連結庫	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL