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

Статья
12/20/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:

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.

[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 битовая маска используется, как описано в параметре флагов , выделяется нестраничный пул памяти. После выделения этого пула инициализации структуры контекста ECP подпрограмма FltInsertExtraCreateParameter используется для вставки структуры контекста ECP (элемента списка ECP) в структуру списка ECP (ECP_LIST).

Если вызывающий объект выделяет ECP_LIST и один или несколько ECP используются в вызове IoCreateFileEx, предыдущее описание правильно. В этом случае система не освобождает ни один из ECP, поэтому вызывающий объект может выполнять несколько вызовов для IoCreateFileEx с одинаковым набором ECP. Однако если драйвер фильтра файловой системы или файловой системы подключает ECP к существующей или недавно созданной ECP_LIST при обработке запроса IRP_MJ_CREATE, этот ECP автоматически очищается после завершения IRP. В результате драйвер фильтра не должен очищать ЕЦП, которые добавляются динамически. Это позволяет правильно распространять ЕЦП драйвера фильтра по точкам повторного анализа, что может потребовать создания нескольких IRP_MJ_CREATE запросов.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Подпрограмма FsRtlAllocateExtraCreateParameter доступна начиная с Windows Vista.
целевая платформа	Всеобщий
заголовка	ntifs.h (include Ntifs.h)
библиотеки	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL