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

Подпрограмма FltAllocateContext выделяет структуру контекста для указанного типа контекста.

Синтаксис

NTSTATUS FLTAPI FltAllocateContext(
  [in]  PFLT_FILTER      Filter,
  [in]  FLT_CONTEXT_TYPE ContextType,
  [in]  SIZE_T           ContextSize,
  [in]  POOL_TYPE        PoolType,
  [out] PFLT_CONTEXT     *ReturnedContext
);

Параметры

[in] Filter

Непрозрачный указатель фильтра для вызывающего объекта. Этот параметр является обязательным и не может иметь значение NULL.

[in] ContextType

Значение FLT_CONTEXT_TYPE , указывающее тип контекста для выделения. ContextType может иметь один из следующих вариантов:

[in] ContextSize

Размер (в байтах) части контекста, определенной драйвером минифильтра. Значение должно быть больше нуля и меньше или равно MAXUSHORT; Для контекстов фиксированного размера значение должно быть меньше или равно размеру , указанному в структуре FLT_CONTEXT_REGISTRATION . Минифильтр использует эту часть контекста для хранения сведений контекста, относящихся к самому себе. FltMgr рассматривает эту часть структуры контекста как непрозрачную. Этот параметр является обязательным и не может быть равен нулю.

[in] PoolType

Тип пула для выделения. Этот параметр является обязательным и должен иметь один из следующих значений. Подробное описание каждого типа см. в POOL_TYPE . Дополнительные сведения см. в разделе "Примечания".

[out] ReturnedContext

Указатель на переменную, выделенную вызывающим объектом, которая получает адрес вновь выделенного контекста. Вызывающий объект отвечает за вызов FltReleaseContext , чтобы освободить этот контекст, когда он больше не нужен.

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

Функция FltAllocateContext возвращает STATUS_SUCCESS или соответствующее значение NTSTATUS , например одно из следующих значений:

Комментарии

Дополнительные сведения о контекстах см. в разделе О контекстах минифильтра.

FltAllocateContext выделяет контекст указанного типа из указанного пула. Начиная с Windows 11, обнуляется ли память, на которую указывает ReturnedContext:

• Память гарантированно будет обнуляться для контекстов переменного размера.
• Содержимое памяти определяется реализацией для контекстов фиксированного размера, выделенных функцией обратного вызова, предоставляемой вызывающим объектом.
• В противном случае нельзя предположить, что память будет обнуляться для контекстов фиксированного размера из-за поведения списка lookaside. То есть запись, возвращаемая из списка lookaside, может не быть обнуляема, если это память, которая ранее была освобождена для списка lookaside, а не для нового выделения.

Перед Windows 11 содержимое возвращаемого контекста не обнуляется.

Установка параметра PoolType для недопустимого значения может привести к непредвиденному поведению, например к обходу списков lookaside, что приведет к потере преимуществ производительности списков lookaside. Для контекстов, имеющих функцию обратного вызова ContextAllocateCallback , поведение из-за недопустимого poolType зависит от реализации.

После выделения контекста его можно задать для объекта , передав указатель ReturnedContext в соответствующую подпрограмму set-context из следующей таблицы.

Когда драйвер минифильтра вызывает FltRegisterFilter из своей подпрограммы DriverEntry , он должен зарегистрировать каждый тип контекста, который он использует. Дополнительные сведения см. в справочнике по структуре FLT_CONTEXT_REGISTRATION и в разделе Регистрация типов контекста.

FltAllocateContext не инициализирует содержимое части структуры контекста, относящаяся к драйверу минифильтра.

Чтобы получить контекст для объекта, вызовите FltGetContexts или соответствующую подпрограмму get-context из следующей таблицы.

Контексты считаются ссылочными, и при успешном возвращении из FltAllocateContext контекст, на который указывает ReturnedContext , инициализирован с числом ссылок 1. Контекст освобождается автоматически, когда его количество ссылок достигает нуля. Чтобы увеличить количество ссылок в контексте, вызовите FltReferenceContext.

Чтобы уменьшать количество ссылок в контексте, вызовите FltReleaseContext.

Так как контексты считаются ссылочными, удалять их обычно не требуется. Чтобы явно удалить контекст, вызовите FltDeleteContext или соответствующую процедуру delete-context из следующей таблицы.

Требования

См. также раздел

FLT_CONTEXT_REGISTRATION

FltCloseSectionForDataScan

FltCreateSectionForDataScan

FltDeleteContext

FltDeleteFileContext

FltDeleteInstanceContext

FltDeleteStreamContext

FltDeleteStreamHandleContext

FltDeleteTransactionContext

FltDeleteVolumeContext

FltGetContexts

FltGetFileContext

FltGetInstanceContext

FltGetSectionContext

FltGetStreamContext

FltGetStreamHandleContext

FltGetTransactionContext

FltGetVolumeContext

FltReferenceContext

FltRegisterFilter

FltReleaseContext

FltSetFileContext

FltSetInstanceContext

FltSetStreamContext

FltSetStreamHandleContext

FltSetTransactionContext

FltSetVolumeContext