FsRtlAllocateExtraCreateParameter 函式 (ntifs.h)

發行項
02/26/2024

FsRtlAllocateExtraCreateParameter 例程會為額外的 create 參數配置記憶體， (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。刪除 FsRtlAllocateExtraCreateParameter 例程 () 建立的 ECP 結構時，會呼叫清除回呼例程。如果清除回呼例程不適用，請將此參數設定為 NULL 。

[in] PoolTag

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

[out] EcpContext

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

傳回值

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

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

備註

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

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

規格需求

需求	值
最低支援的用戶端	FsRtlAllocateExtraCreateParameter 例程可從 Windows Vista 開始提供。
目標平台	Universal
標頭	ntifs.h (包含 Ntifs.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	<= APC_LEVEL