Функция FltCreateSectionForDataScan (fltkernel.h)
Подпрограмма FltCreateSectionForDataScan создает объект раздела для файла. При необходимости диспетчер фильтров может синхронизировать ввод-вывод с созданным разделом.
Синтаксис
NTSTATUS FLTAPI FltCreateSectionForDataScan(
[in] PFLT_INSTANCE Instance,
[in] PFILE_OBJECT FileObject,
[in] PFLT_CONTEXT SectionContext,
[in] ACCESS_MASK DesiredAccess,
[in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
[in, optional] PLARGE_INTEGER MaximumSize,
[in] ULONG SectionPageProtection,
[in] ULONG AllocationAttributes,
[in] ULONG Flags,
[out] PHANDLE SectionHandle,
[out] PVOID *SectionObject,
[out, optional] PLARGE_INTEGER SectionFileSize
);
Параметры
[in] Instance
Указатель непрозрачного экземпляра для экземпляра драйвера минифильтра, контекст которого требуется извлечь.
[in] FileObject
Объект file для открытого файла. Объект section будет подкреплен указанным файлом. Этот параметр является обязательным и не может иметь значение NULL.
[in] SectionContext
Указатель на ранее выделенный контекст раздела.
[in] DesiredAccess
Тип доступа к объекту section в виде одного или нескольких следующих флагов ACCESS_MASK .
| Flag | Разрешает вызывающему объекту |
|---|---|
| SECTION_MAP_READ | Чтение представлений раздела. |
| SECTION_MAP_WRITE | Запись представлений раздела. |
| SECTION_QUERY | Запросите объект section для получения сведений о разделе. Драйверы должны установить этот флаг. |
| SECTION_ALL_ACCESS | Все действия, определенные предыдущими флагами, а также действия, определенные STANDARD_RIGHTS_REQUIRED. Дополнительные сведения о STANDARD_RIGHTS_REQUIRED см. в разделе ACCESS_MASK. |
[in, optional] ObjectAttributes
Указатель на необязательную структуру OBJECT_ATTRIBUTES , указывающую имя объекта и другие атрибуты. Используйте макрос InitializeObjectAttributes для инициализации этой структуры.
[in, optional] MaximumSize
Этот параметр зарезервирован для использования в будущем.
[in] SectionPageProtection
Защита, размещаемая на каждой странице раздела. Укажите одно из следующих значений. Этот параметр является обязательным и не может быть равен нулю.
| Flag | Значение |
|---|---|
| PAGE_READONLY | Обеспечивает доступ только для чтения к зафиксированной области страниц. Попытка записи в зафиксированный регион приводит к нарушению доступа. Если система проводит различие между доступом только для чтения и доступом на выполнение, попытка выполнить код в зафиксированном регионе приведет к нарушению доступа. |
| PAGE_READWRITE | Обеспечивает доступ как на чтение, так и на запись к зафиксированной области страниц. |
[in] AllocationAttributes
Битовые маски флагов SEC_XXX определяют атрибуты выделения раздела. Укажите одно или несколько из следующих значений. Этот параметр является обязательным и не может быть равен нулю.
| Flag | Значение |
|---|---|
| SEC_COMMIT | Выделяет физическое хранилище в памяти или в файле подкачки на диске для всех страниц раздела. Это параметр по умолчанию. Обратите внимание, что этот флаг является обязательным и не может быть пропущен. |
| SEC_FILE | Файл, указанный параметром FileObject , является сопоставленным файлом. |
[in] Flags
Этот параметр зарезервирован для использования в будущем.
[out] SectionHandle
Указатель на переменную, выделенную вызывающим объектом, которая получает непрозрачный дескриптор раздела. По умолчанию дескриптор раздела является пользовательским дескриптором. Если вызывающему объекту требуется дескриптор ядра, он должен передать указатель на инициализированную структуру OBJECT_ATTRIBUTES в параметре ObjectAttributes с установленным флагом OBJ_KERNEL_HANDLE.
[out] SectionObject
Указатель на переменную, выделенную вызывающим объектом, которая получает непрозрачный указатель на объект section.
[out, optional] SectionFileSize
Указатель на переменную, выделенную вызывающим объектом, которая получает размер файла в байтах на момент создания объекта section. Этот параметр является необязательным и может иметь значение NULL.
Возвращаемое значение
FltCreateSectionForDataScan возвращает STATUS_SUCCESS или соответствующее значение NTSTATUS, например одно из следующих значений.
| Код возврата | Описание |
|---|---|
| STATUS_END_OF_FILE | Размер файла, указанного параметром FileObject , равен нулю. |
| STATUS_FILE_LOCK_CONFLICT | Файл, указанный параметром FileObject , заблокирован. |
| STATUS_INSUFFICIENT_RESOURCES | FltCreateSectionForDataScan обнаружил сбой выделения пула. |
| STATUS_INVALID_FILE_FOR_SECTION | Файл, указанный параметром FileObject , не поддерживает разделы. |
| STATUS_INVALID_PARAMETER | Минифильтр не зарегистрирован. |
| STATUS_INVALID_PARAMETER_8 | Недопустимое значение, указанное для параметра SectionPageProtection . |
| STATUS_INVALID_PARAMETER_9 | Вызывающий объект указал недопустимое значение для параметра AllocationAttributes . |
| STATUS_NOT_SUPPORTED | Том, подключенный к этому экземпляру, не поддерживает контексты разделов. |
| STATUS_PRIVILEGE_NOT_HELD | Вызывающий объект не имеет необходимых привилегий для создания объекта раздела с доступом, указанным в параметре DesiredAccess . |
| STATUS_FILE_IS_A_DIRECTORY | Файл, указанный параметром FileObject , является каталогом. |
| STATUS_FLT_CONTEXT_ALREADY_DEFINED | Экземпляр фильтра, указанный параметром Instance , уже имеет открытый раздел для потока. Поддерживается только один раздел на поток и, следовательно, для каждого экземпляра. |
Комментарии
Перед вызовом FltCreateSectionForDataScan минифильтр должен сначала зарегистрировать свой том для сканирования данных, вызвав FltRegisterForDataScan. Как и в случае с другими элементами контекста фильтра, SectionContext сначала выделяется с помощью FltAllocateContext.
FltCreateSectionForDataScan вставляет дескриптор к объекту (SectionHandle) в таблицу дескрипторов процесса для потока, в который вызывается FltCreateSectionForDataScan .
Дескрипторами могут быть пользовательские дескрипторы или дескрипторы ядра. Дескриптор, созданный с OBJ_KERNEL_HANDLE задан в структуре OBJECT_ATTRIBUTES , на которую указывает ObjectAttributes , является дескриптором ядра и доступен только из режима ядра. Дескриптор, созданный без флага OBJ_KERNEL_HANDLE, является пользовательским дескриптором, к которому можно получить доступ из пользовательского режима или режима ядра. Фильтр может создать пользовательский дескриптор, а затем передать его в приложение пользовательского режима для обработки. Например, модуль сканирования вирусов может находиться в приложении в пользовательском режиме и получать дескрипторам пользователей из фильтра файловой системы.
Некоторые ситуации могут возникать, когда удержание открытого раздела несовместимо с текущим файлом ввода-вывода. В частности, файловый ввод-вывод, запускающий очистку кэша, может привести к несогласованности кэша, если очистка кэша запрещена из-за открытого раздела. Минифильтр может предоставлять необязательную подпрограмму обратного вызова для уведомлений об этих событиях. Драйвер минифильтра реализует PFLT_SECTION_CONFLICT_NOTIFICATION_CALLBACK для получения этих уведомлений. Уведомления о конфликтах включены, если при регистрации минифильтра для элемента SectionNotificationCallbackFLT_REGISTRATION задана эта подпрограмма обратного вызова. При получении уведомления раздел можно закрыть, чтобы продолжить конфликтующую операцию ввода-вывода.
Примечание
Обратный вызов уведомления раздела может произойти до возврата FltCreateSectionForDataScan . Мини-фильтр должен иметь возможность принимать обратный вызов и обрабатывать случаи, когда SectionHandle и SectionObject еще не являются допустимыми.
Если объект section, созданный этой подпрограммой, больше не требуется, закройте дескриптор объекта раздела (SectionHandle), вызвав подпрограмму ZwClose , и разыменуйте сам объект section (SectionObject), вызвав подпрограмму ObDereferenceObject .
Общие сведения о создании сопоставленных разделов и представлений памяти см. в разделе Объекты и представления раздела. Кроме того, см. документацию по процедуре CreateFileMapping в Microsoft Windows SDK.
Важно!
Минифильтры не должны явным образом удалять контекст раздела, передаваемый в FltCreateSectionForDataScan. Не вызывайте FltDeleteContext после передачи контекста раздела в FltCreateSectionForDataScan. Контекст раздела освобождается и удаляется из потока путем вызова FltCloseSectionForDataScan в этом случае.
Как правило, разделы должны создаваться только для чтения. В частности, если файл, доступный только для чтения, находится в транзакции, а мини-фильтр не создает раздел только для чтения, запись в раздел удаляется и не включается в транзакцию.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows 8 |
| Целевая платформа | Универсальное |
| Верхняя часть | fltkernel.h (включая Fltkernel.h) |
| Библиотека | FltMgr.lib |
| IRQL | <= APC_LEVEL |
См. также раздел
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по