Функция FltAllocateExtraCreateParameter (fltkernel.h)

Статья
08/07/2023

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

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

FSRTL_ALLOCATE_ECP_FLAG_NONPAGED_POOL — будет выделен нестраничный пул. Если это значение флага не используется, будет выделен выстраивный пул.
FSRTL_ALLOCATE_ECPLIST_FLAG_CHARGE_QUOTA — плата за все пулы, выделенные этой подпрограммой, будет взиматься по квоте памяти текущего процесса.

Если используется несколько флагов, будут возникать все эффекты, связанные со значениями используемых флагов.

[in, optional] CleanupCallback

Необязательный указатель на определяемую минифильтром процедуру обратного вызова очистки типа PFSRTL_EXTRA_CREATE_PARAMETER_CLEANUP_CALLBACK. Подпрограмма обратного вызова очистки вызывается при удалении структуры ECP (созданной подпрограммой FltAllocateExtraCreateParameter ). Задайте для этого параметра значение NULL , если подпрограмма обратного вызова очистки неприменима.

[in] PoolTag

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

[out] EcpContext

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

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

FltAllocateExtraCreateParameter может возвращать одно из следующих значений:

Код возврата	Описание
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 будет уничтожен.

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

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	fltkernel.h (включая Fltkernel.h)
Библиотека	FltMgr.lib
IRQL	<= APC_LEVEL