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

Статья
06.02.2025

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

Определяет параметры выделения пула. В следующем описано, как пул будет выделен, если одно или несколько перечисленных значений флагов объединяются с параметром флагов с помощью побитовой операции 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

Указывает тег пула для выделенной памяти. Дополнительные сведения см. в параметр е тега тега 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. В результате драйвер фильтра не должен очищать ЕЦП, которые добавляются динамически. Это позволяет правильно распространять ЕЦП драйвера фильтра по точкам повторного анализа, что может потребовать создания нескольких IRP_MJ_CREATE запросов.

Требования

Требование	Ценность
целевая платформа	Всеобщий
заголовка	fltkernel.h (include Fltkernel.h)
библиотеки	FltMgr.lib
IRQL	<= APC_LEVEL