Функция FsRtlAllocateExtraCreateParameter (ntifs.h)

Статья
08/07/2023

Подпрограмма 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

Определяет параметры выделения пула. Ниже описывается выделение пула при объединении одного или нескольких значений перечисленных флагов с параметром Flags с помощью побитовой операции OR:

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

Указывает тег пула для выделенной памяти. Дополнительные сведения см. в разделе Параметр Tagобъекта ExAllocatePoolWithTag.

[out] EcpContext

Получает указатель на выделенную структуру контекста ECP. Если подпрограмме не удалось выделить достаточный пул, значение, указываемое EcpContext , будет иметь значение NULL , а FsRtlAllocateExtraCreateParameter вернет код состояния STATUS_INSUFFICIENT_RESOURCES.

Возвращаемое значение

FltAllocateExtraCreateParameter возвращает код состояния, например один из следующих:

Код возврата	Описание
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, поэтому вызывающий объект может выполнять несколько вызовов IoCreateFileEx с одинаковым набором ECP. Однако если драйвер фильтра файловой системы или файловой системы подключает ECP к существующему или только что созданному ECP_LIST при обработке запроса IRP_MJ_CREATE, этот ECP автоматически очищается по завершении IRP. В результате драйверу фильтра не нужно очищать динамически добавляемые ESP. Это позволяет правильно распространять ECP драйвера фильтра по точкам повторного анализа . Процесс, который может потребовать создания нескольких запросов IRP_MJ_CREATE.

Требования

Требование	Значение
Минимальная версия клиента	Подпрограмма FsRtlAllocateExtraCreateParameter доступна начиная с Windows Vista.
Целевая платформа	Универсальное
Верхняя часть	ntifs.h (включая Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL