Функция FsRtlCreateSectionForDataScan (ntifs.h)

Статья
03/08/2023

Подпрограмма FsRtlCreateSectionForDataScan создает объект section. Используйте эту процедуру с крайней осторожностью. (См. следующий раздел примечаний .)

Синтаксис

NTSTATUS FsRtlCreateSectionForDataScan(
  [out]           PHANDLE            SectionHandle,
  [out]           PVOID              *SectionObject,
  [out, optional] PLARGE_INTEGER     SectionFileSize,
  [in]            PFILE_OBJECT       FileObject,
  [in]            ACCESS_MASK        DesiredAccess,
  [in, optional]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional]  PLARGE_INTEGER     MaximumSize,
  [in]            ULONG              SectionPageProtection,
  [in]            ULONG              AllocationAttributes,
  [in]            ULONG              Flags
);

Параметры

[out] SectionHandle

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

[out] SectionObject

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

[out, optional] SectionFileSize

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

[in] FileObject

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

[in] DesiredAccess

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

Флаг DesiredAccess	Разрешает вызывающему объекту
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 для инициализации этой структуры. Так как FsRtlCreateSectionForDataScan вставляет этот объект в таблицу дескрипторов процесса, вызывающий объект должен указать атрибут OBJ_KERNEL_HANDLE при вызове InitializeObjectAttributes.

[in, optional] MaximumSize

Этот параметр зарезервирован для использования в будущем.

[in] SectionPageProtection

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

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

Flag

Значение

PAGE_READONLY

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

PAGE_READWRITE

Обеспечивает доступ как на чтение, так и на запись к зафиксированной области страниц.

[in] AllocationAttributes

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

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

[in] Flags

Этот параметр зарезервирован для использования в будущем.

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

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

Код возврата	Описание
STATUS_END_OF_FILE	Размер файла, указанного параметром FileObject, равен нулю. Это код ошибки.
STATUS_FILE_LOCK_CONFLICT	Файл, указанный параметром FileObject, заблокирован. Это код ошибки.
STATUS_INSUFFICIENT_RESOURCES	FsRtlCreateSectionForDataScan обнаружил сбой выделения пула. Это код ошибки.
STATUS_INVALID_FILE_FOR_SECTION	Файл, указанный параметром FileObject, не поддерживает разделы. Это код ошибки.
STATUS_INVALID_PARAMETER_8	Недопустимое значение, указанное для параметра SectionPageProtection. Это код ошибки.
STATUS_INVALID_PARAMETER_9	Вызывающий объект указал недопустимое значение для параметра AllocationAttributes. Это код ошибки.
STATUS_PRIVILEGE_NOT_HELD	Вызывающий объект не имеет необходимых привилегий для создания объекта раздела с доступом, указанным в параметре DesiredAccess. Это код ошибки.

Важно Подпрограмму FsRtlCreateSectionForDataScan следует использовать только в тех случаях, когда дескриптор объекта файла, указанного в параметре FileObject , еще не был создан (обычно при обработке операции после создания). Если драйвер имеет дескриптор объекта файла или может получить дескриптор для объекта файла, драйвер должен использовать подпрограмму ZwCreateSection .

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

Дополнительные сведения о создании сопоставленных разделов и представлений памяти см. в разделе Объекты и представления раздела. См. также документацию по подпрограмме CreateFileMapping в Microsoft Windows SDK.

Требования

Требование	Значение
Минимальная версия клиента	Накопительный пакет обновления для Windows 2000 с пакетом обновления 4 (SP4); Свертка диспетчера фильтров для Windows XP с пакетом обновления 2 (SP2).
Минимальная версия сервера	Microsoft Windows Server 2003 с пакетом обновления 1 (SP1)
Целевая платформа	Универсальное
Верхняя часть	ntifs.h (включая Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL