Функция 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 может иметь один из следующих вариантов:
| Значение | Значение |
|---|---|
| FLT_VOLUME_CONTEXT (0x0001) | Выделение контекста тома. |
| FLT_INSTANCE_CONTEXT (0x0002) | Выделение контекста экземпляра. |
| FLT_FILE_CONTEXT (0x0004) | Выделение контекста файла. |
| FLT_STREAM_CONTEXT (0x0008) | Выделение контекста потока. |
| FLT_STREAMHANDLE_CONTEXT (0x0010) | Выделение контекста дескриптора потока. |
| FLT_TRANSACTION_CONTEXT (0x0020) | Выделение контекста транзакции. |
| FLT_SECTION_CONTEXT (0x0040) | Выделение контекста раздела. Доступно начиная с Windows 8. |
[in] ContextSize
Размер (в байтах) части контекста, определенной драйвером минифильтра. Значение должно быть больше нуля и меньше или равно MAXUSHORT; Для контекстов фиксированного размера значение должно быть меньше или равно размеру , указанному в структуре FLT_CONTEXT_REGISTRATION . Минифильтр использует эту часть контекста для хранения сведений контекста, относящихся к самому себе. FltMgr рассматривает эту часть структуры контекста как непрозрачную. Этот параметр является обязательным и не может быть равен нулю.
[in] PoolType
Тип пула для выделения. Этот параметр является обязательным и должен иметь один из следующих значений. Подробное описание каждого типа см. в POOL_TYPE . Дополнительные сведения см. в разделе "Примечания".
| Значение | Значение |
|---|---|
| NonPagedPool | Системная память, не доступная к страницам. Параметр PoolType должен иметь значение NonPagedPool, если contextType имеет FLT_VOLUME_CONTEXT. |
| PagedPool | Страничной системной памяти. |
| NonPagedPoolNx | Пул без выполнения (NX). |
[out] ReturnedContext
Указатель на переменную, выделенную вызывающим объектом, которая получает адрес вновь выделенного контекста. Вызывающий объект отвечает за вызов FltReleaseContext , чтобы освободить этот контекст, когда он больше не нужен.
Возвращаемое значение
Функция FltAllocateContext возвращает STATUS_SUCCESS или соответствующее значение NTSTATUS , например одно из следующих значений:
| Код возврата | Описание |
|---|---|
| STATUS_FLT_CONTEXT_ALLOCATION_NOT_FOUND | Сведения о выделении для контекста указанного типа не были предоставлены во время регистрации фильтра. Или для контекстов фиксированного размера запрошенный ContextSize больше размера , указанного в структуре FLT_CONTEXT_REGISTRATION для указанного ContextType. |
| STATUS_FLT_DELETING_OBJECT | Драйвер минифильтра, указанный в параметре Filter , сносится. Это код ошибки. |
| STATUS_INSUFFICIENT_RESOURCES | FltAllocateContext столкнулся с ошибкой выделения пула. Это код ошибки. |
| STATUS_INVALID_BUFFER_SIZE | ContextSize не может быть больше MAXUSHORT. Это код ошибки. |
| STATUS_INVALID_PARAMETER | Для параметра ContextType или ContextSize указано недопустимое значение. Это код ошибки. |
| STATUS_NOT_SUPPORTED | Файловая система не поддерживает контексты каждого потока. Это код ошибки. |
Комментарии
Дополнительные сведения о контекстах см. в разделе О контекстах минифильтра.
FltAllocateContext выделяет контекст указанного типа из указанного пула. Начиная с Windows 11, обнуляется ли память, на которую указывает ReturnedContext:
- Память гарантированно будет обнуляться для контекстов переменного размера.
- Содержимое памяти определяется реализацией для контекстов фиксированного размера, выделенных функцией обратного вызова, предоставляемой вызывающим объектом.
- В противном случае нельзя предположить, что память будет обнуляться для контекстов фиксированного размера из-за поведения списка lookaside. То есть запись, возвращаемая из списка lookaside, может не быть обнуляема, если это память, которая ранее была освобождена для списка lookaside, а не для нового выделения.
Перед Windows 11 содержимое возвращаемого контекста не обнуляется.
Установка параметра PoolType для недопустимого значения может привести к непредвиденному поведению, например к обходу списков lookaside, что приведет к потере преимуществ производительности списков lookaside. Для контекстов, имеющих функцию обратного вызова ContextAllocateCallback , поведение из-за недопустимого poolType зависит от реализации.
После выделения контекста его можно задать для объекта , передав указатель ReturnedContext в соответствующую подпрограмму set-context из следующей таблицы.
| Тип контекста | Подпрограмма Set-Context |
|---|---|
| FLT_FILE_CONTEXT | FltSetFileContext (начиная с Windows Vista) |
| FLT_INSTANCE_CONTEXT | FltSetInstanceContext |
| FLT_SECTION_CONTEXT | FltCreateSectionForDataScan (начиная с Windows 8) |
| FLT_STREAM_CONTEXT | FltSetStreamContext |
| FLT_STREAMHANDLE_CONTEXT | FltSetStreamHandleContext |
| FLT_TRANSACTION_CONTEXT | FltSetTransactionContext (начиная с Windows Vista) |
| FLT_VOLUME_CONTEXT | FltSetVolumeContext |
Когда драйвер минифильтра вызывает FltRegisterFilter из своей подпрограммы DriverEntry , он должен зарегистрировать каждый тип контекста, который он использует. Дополнительные сведения см. в справочнике по структуре FLT_CONTEXT_REGISTRATION и в разделе Регистрация типов контекста.
FltAllocateContext не инициализирует содержимое части структуры контекста, относящаяся к драйверу минифильтра.
Чтобы получить контекст для объекта, вызовите FltGetContexts или соответствующую подпрограмму get-context из следующей таблицы.
| Тип контекста | Подпрограмма Get-Context |
|---|---|
| FLT_FILE_CONTEXT | FltGetFileContext (начиная с Windows Vista) |
| FLT_INSTANCE_CONTEXT | FltGetInstanceContext |
| FLT_SECTION_CONTEXT | FltGetSectionContext (начиная с Windows 8) |
| FLT_STREAM_CONTEXT | FltGetStreamContext |
| FLT_STREAMHANDLE_CONTEXT | FltGetStreamHandleContext |
| FLT_TRANSACTION_CONTEXT | FltGetTransactionContext (начиная с Windows Vista ) |
| FLT_VOLUME_CONTEXT | FltGetVolumeContext |
Контексты считаются ссылочными, и при успешном возвращении из FltAllocateContext контекст, на который указывает ReturnedContext , инициализирован с числом ссылок 1. Контекст освобождается автоматически, когда его количество ссылок достигает нуля. Чтобы увеличить количество ссылок в контексте, вызовите FltReferenceContext.
Чтобы уменьшать количество ссылок в контексте, вызовите FltReleaseContext.
Так как контексты считаются ссылочными, удалять их обычно не требуется. Чтобы явно удалить контекст, вызовите FltDeleteContext или соответствующую процедуру delete-context из следующей таблицы.
| Тип контекста | Подпрограмма Delete-Context |
|---|---|
| FLT_FILE_CONTEXT | FltDeleteFileContext (начиная с Windows Vista) |
| FLT_INSTANCE_CONTEXT | FltDeleteInstanceContext |
| FLT_SECTION_CONTEXT | FltCloseSectionForDataScan (начиная с Windows 8) |
| FLT_STREAM_CONTEXT | FltDeleteStreamContext |
| FLT_STREAMHANDLE_CONTEXT | FltDeleteStreamHandleContext |
| FLT_TRANSACTION_CONTEXT | FltDeleteTransactionContext (начиная с Windows Vista) |
| FLT_VOLUME_CONTEXT | FltDeleteVolumeContext |
Требования
| Требование | Значение |
|---|---|
| Целевая платформа | Универсальное |
| Верхняя часть | fltkernel.h (включая Fltkernel.h) |
| Библиотека | FltMgr.lib |
| DLL | Fltmgr.sys |
| IRQL | <= APC_LEVEL |