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

Статья
02/29/2024

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

Синтаксис

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

Параметры

[in] FileObject

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

[in] FileOffset

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

[in] Length

Длина требуемых данных в байтах.

[in] Flags

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

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

[out] Bcb

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

[out] Buffer

Указатель на буфер, содержащий закрепленные данные.

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

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

Если установлен флаг PIN_WAIT, CcPinRead гарантированно завершит запрос на закрепление и возвратит значение TRUE. Если необходимые страницы кэшированного файла уже находятся в памяти, данные закрепляются немедленно и блокировка не возникает. Если какие-либо необходимые страницы не являются резидентами, вызывающий объект переводится в состояние ожидания до тех пор, пока все необходимые страницы не будут резидентированы, и данные могут быть закреплены. Если флаг PIN_WAIT не задан, но данные не могут быть закреплены немедленно, CcPinRead возвращает значение FALSE, а значения выходных параметров не имеют смысла.

Если вызывающий объект впоследствии изменяет данные, считываемые CcPinRead, он также должен вызвать CcSetDirtyPinnedData , чтобы измененные данные в конечном итоге были записаны на диск.

Каждый успешный вызов CcPinRead должен соответствовать последующему вызову CcUnpinData.

Указатель, возвращаемый в buffer , действителен до вызова CcUnpinData . Если вызывается CcPinMappedData , пока этот указатель по-прежнему действителен, указатель остается действительным после вызова CcPinMappedData (но только до вызова CcUnpinData ).

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

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

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

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

Требования

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