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

Программа 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 одного или нескольких из следующих значений:

[out] Bcb

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

[out] Buffer

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

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

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

Замечания

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

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

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

Указатель, возвращенный в буфере , действителен до 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.

Требования

См. также

CcInitializeCacheMap

CcMapData

CcPinMappedData

CcPreparePinWrite

CcSetDirtyPinnedData

CcUnpinData