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

Статья
08/07/2023

Подпрограмма CcPinMappedData закрепляет указанный диапазон байтов кэшированного файла.

Синтаксис

BOOLEAN CcPinMappedData(
  [in]      PFILE_OBJECT   FileObject,
  [in]      PLARGE_INTEGER FileOffset,
  [in]      ULONG          Length,
  [in]      ULONG          Flags,
  [in, out] PVOID          *Bcb
);

Параметры

[in] FileObject

Указатель на объект файла для кэшированного файла, в котором должен быть закреплен диапазон данных.

[in] FileOffset

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

[in] Length

Длина закрепляемых данных в байтах.

[in] Flags

Битовая маска флагов, указывающих способ выполнения операции закрепления. ORed сочетание одного или нескольких из следующих значений:

Flag	Значение
PIN_WAIT	Вызывающий объект может быть переведен в состояние ожидания, пока данные не будут закреплены.
PIN_EXCLUSIVE	Блок управления буфером (BCB) должен быть получен исключительно. Если этот флаг установлен, необходимо также задать PIN_WAIT.
PIN_NO_READ	Закрепляются только те страницы, которые уже находятся в памяти. Если этот флаг установлен, необходимо также задать PIN_WAIT.
PIN_IF_BCB	Данные следует закреплять только в том случае, если bcb уже существует. В противном случае закрепление завершается сбоем, и bcb имеет значение NULL.

[in, out] Bcb

При первом вызове возвращается указатель на блок управления буфером (BCB). Этот указатель должен быть указан в качестве входных данных для всех последующих вызовов этого буфера.

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

CcPinMappedData возвращает значение TRUE , если данные для кэшированного файла были успешно закреплены, в противном случае — FALSE .

Успешное возвращение из CcPinMappedData гарантирует, что данные, ранее сопоставленные в вызове CcMapData , будут закреплены в кэше и данные в указанном диапазоне могут быть безопасно изменены. Если вызывающий объект впоследствии изменяет данные, закрепленные с помощью CcPinMappedData, он также должен вызвать CcSetDirtyPinnedData , чтобы измененные данные в конечном итоге были записаны на диск.

CcPinMappedData не может закреплять данные через границы представления в диспетчере кэша. Диспетчер кэша управляет файлами в системе в представлениях, выровненных по 256 КБ. (Размер представления диспетчера кэша определяется системной константой VACB_MAPPING_GRANULARITY, которая в ntifs.h имеет значение 256 КБ.) Закрепленные области не могут охватывать более одного представления размером 256 КБ. Таким образом, самая большая область, которая может быть закреплена, составляет 256 КБ, начиная со смещения в 256 КБ в файле.

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

При возникновении какого-либо сбоя CcPinMappedData создает исключение состояния для этого конкретного сбоя. Например, при сбое выделения пула CcPinMappedData вызывает исключение STATUS_INSUFFICIENT_RESOURCES ; При возникновении ошибки ввода-вывода CcPinMappedData вызывает исключение состояния ошибки ввода-вывода. Таким образом, чтобы получить контроль в случае сбоя, драйвер должен заключить вызов CcPinMappedData в оператор try-except или try-finally .

Чтобы сопоставить данные для кэшированного файла, используйте подпрограмму CcMapData . Чтобы кэшировать файл, используйте CcInitializeCacheMap.

Не нужно вызывать CcUnpinData после вызова CcPinMappedData , так как ссылка на закрепление сопоставляется с CcMapData.

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	ntifs.h (включая Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL