Функция CcPinMappedData (ntifs.h)
Подпрограмма 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 одного или нескольких из следующих значений:
| Флаг | Значение |
|---|---|
| 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, которая имеет значение 256 КБ в ntifs.h.) Закрепленные регионы не могут охватывать более одного представления 256 КБ. Таким образом, самый большой регион, который можно закрепить, составляет 256 КБ, начиная с смещения с выравниванием 256 КБ в файле.
Закрепление диапазона байтов в кэшированном файле не гарантирует, что страницы остаются в памяти. Если страницы закреплены, диапазон байтов гарантированно сопоставляется с виртуальным адресным пространством кэша системы, но диспетчер памяти может вывести физические страницы в соответствии с требованиями к памяти системы.
Если произойдет сбой, CcPinMappedData вызывает исключение состояния для конкретного сбоя. Например, если возникает сбой выделения пула, CcPinMappedData вызывает исключение STATUS_INSUFFICIENT_RESOURCES; Если возникает ошибка ввода-вывода, CcPinMappedData вызывает исключение состояния ошибки ввода-вывода. Таким образом, чтобы получить контроль при возникновении сбоя, драйвер должен упаковать вызов CcPinMappedData в , кроме или инструкции try-finally.
Чтобы сопоставить данные для кэшированного файла, используйте подпрограмму CcMapData. Чтобы кэшировать файл, используйте CcInitializeCacheMap.
Не обязательно вызывать CcUnpinData после вызова CcPinMappedData, так как ссылка на закрепление соответствует CcMapData.
Требования
| Требование | Ценность |
|---|---|
| целевая платформа | Всеобщий |
| заголовка | ntifs.h (include Ntifs.h) |
| библиотеки |
NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |