Функция 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 | Драйвер минифильтра, указанный в параметре фильтра , отключается. Это код ошибки. |
| 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 |
|---|---|
| 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 |
|---|---|
| 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 |
|---|---|
| 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 (include Fltkernel.h) |
| библиотеки | FltMgr.lib |
| DLL | Fltmgr.sys |
| IRQL | <= APC_LEVEL |