Поделиться через

Функция 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

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

[in] SectionContext

Указатель на ранее выделенный контекст раздела.

[in] DesiredAccess

Тип доступа для объекта раздела как один или несколько из следующих флагов ACCESS_MASK.

Флаг Разрешает вызывающим абонентам
SECTION_MAP_READ Чтение представлений раздела.
SECTION_MAP_WRITE Написание представлений раздела.
SECTION_QUERY Запрос объекта раздела для получения сведений о разделе. Драйверы должны задать этот флаг.
SECTION_ALL_ACCESS Все действия, определенные предыдущими флагами, а также определенные STANDARD_RIGHTS_REQUIRED. Дополнительные сведения о STANDARD_RIGHTS_REQUIRED см. в ACCESS_MASK.

[in, optional] ObjectAttributes

Указатель на необязательную структуру OBJECT_ATTRIBUTES, указывающую имя объекта и другие атрибуты. Используйте макрос InitializeObjectAttributes для инициализации этой структуры.

[in, optional] MaximumSize

Этот параметр зарезервирован для дальнейшего использования.

[in] SectionPageProtection

Защита, размещаемая на каждой странице в разделе. Укажите одно из следующих значений. Этот параметр является обязательным и не может быть нулевым.

Флаг Значение
PAGE_READONLY Включает доступ только для чтения к зафиксированной области страниц. Попытка записи в зафиксированный регион приводит к нарушению доступа. Если система отличается от доступа только для чтения и выполнения, попытка выполнить код в зафиксированном регионе приводит к нарушению доступа.
PAGE_READWRITE Включает доступ для чтения и записи к зафиксированной области страниц.

[in] AllocationAttributes

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

Флаг Значение
SEC_COMMIT Выделяет физическое хранилище в памяти или на диске на диске для всех страниц раздела. Это параметр по умолчанию. Обратите внимание, что этот флаг является обязательным и не может быть опущен.
SEC_FILE Файл, указанный параметром FileObject, является сопоставленным файлом.

[in] Flags

Этот параметр зарезервирован для дальнейшего использования.

[out] SectionHandle

Указатель на выделенную вызывающим переменную, которая получает непрозрачный дескриптор в раздел. По умолчанию дескриптор раздела — это дескриптор пользователя. Если вызывающий объект нуждается в дескрипторе ядра, он должен передать указатель на инициализированную структуру OBJECT_ATTRIBUTES в параметре ObjectAttributes с набором флагов OBJ_KERNEL_HANDLE.

[out] SectionObject

Указатель на выделенную вызывающим переменную, которая получает непрозрачный указатель на объект раздела.

[out, optional] SectionFileSize

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

Замечания

Перед вызовом FltCreateSectionForDataScanминифильтр должен сначала зарегистрировать его том для сканирования данных путем вызова FltRegisterForDataScan. Как и в случае с другими элементами контекста фильтра, SectionContext сначала выделяется FltAllocateContext.

FltCreateSectionForDataScan вставляет дескриптор в объект (SectionHandle) в таблицу обработки для потока, на который вызывается FltCreateSectionForDataScan.

Дескриптор может быть дескрипторами пользователей или дескрипторами ядра. Дескриптор, созданный с помощью OBJ_KERNEL_HANDLE заданной в структуре OBJECT_ATTRIBUTES, которая ObjectAttributes указывает на дескриптор ядра, и доступ к ним можно получить только в режиме ядра. Дескриптор, созданный без флага OBJ_KERNEL_HANDLE, — это дескриптор пользователя, к которому можно получить доступ из режима пользователя или ядра. Фильтр может создать дескриптор пользователя, а затем передать его в приложение пользовательского режима для обработки. Например, модуль сканирования вирусов может жить в приложении пользовательского режима и получать отфильтрованные пользовательские дескрипторы из фильтра файловой системы.

Некоторые ситуации могут возникать, когда открытие раздела несовместимо с текущим операцией ввода-вывода файла. В частности, операции ввода-вывода файлов, которые активируют очистку кэша, могут привести к несогласованности кэша, если очистка кэша запрещена из-за открытого раздела. Минифильтр может предоставить необязательный подпрограмму обратного вызова для уведомлений об этих событиях. Драйвер минифильтра реализует PFLT_SECTION_CONFLICT_NOTIFICATION_CALLBACK для получения этих уведомлений. Уведомления о конфликтах включены, если SectionNotificationCallback член FLT_REGISTRATION установлен в эту подпрограмму обратного вызова при регистрации минифильтра. При получении уведомления раздел можно закрыть, чтобы разрешить конфликтующую операцию ввода-вывода продолжить.

Заметка

Обратный вызов уведомлений раздела может возникнуть до возврата FltCreateSectionForDataScan. Мини-фильтр должен иметь возможность получать обратный вызов и обрабатывать ситуацию, когда SectionHandle и SectionObject еще не допустимы.

Если объект раздела, созданный этой подпрограммой, больше не нужен, не забудьте закрыть дескриптор объекта раздела (SectionHandle) путем вызова процедуры ZwClose и отмены ссылки на сам объект раздела (SectionObject), вызвав подпрограмму ObDereferenceObject.

Общие сведения о создании сопоставленных разделов и представлений памяти см. в разделах и представлениях. Кроме того, см. документацию по подпрограмме CreateFileMapping в пакете SDK для Microsoft Windows.

Важный

Минифильтры не должны явно удалять контекст раздела, переданный FltCreateSectionForDataScan. Не вызывайте FltDeleteContext после передачи контекста раздела в FltCreateSectionForDataScan. Контекст раздела освобожден и удален из потока путем вызова FltCloseSectionForDataScan в этом случае.

Как правило, разделы должны создаваться как доступные только для чтения. В частности, если файл только для чтения находится в транзакции, а мини-фильтр не создает раздел только для чтения, запись в раздел удаляется и не входит в состав транзакции.

Требования

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

См. также

ACCESS_MASK

CcPurgeCacheSection

FLT_REGISTRATION

FltAllocateContext

FltCloseSectionForDataScan

FltRegisterForDataScan

ObDereferenceObject

PFLT_SECTION_CONFLICT_NOTIFICATION_CALLBACK

ZwClose

ZwCreateSection