Функция 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 сочетание одного или нескольких из следующих значений:
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 |