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

Статья
08/07/2023

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

Синтаксис

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

Параметры

[in] FileObject

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

[in] FileOffset

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

[in] Length

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

[in] Zero

Установите значение TRUE , если буфер должен быть обнулен при возврате. Этот параметр игнорируется, если флаг PIN_CALLER_TRACKS_DIRTY_DATA задан в параметре Flags .

[in] Flags

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

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

[out] Bcb

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

[out] Buffer

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

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

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

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

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

Microsoft Windows Server 2003 с пакетом обновления 1 (SP1) и более поздних версий: Флаг PIN_CALLER_TRACKS_DIRTY_DATA обычно используется в случаях, когда файловая система управляет файлом журнала, который записывается, но не считывается из. Так как существующие данные файла будут перезаписаны и не считываются, диспетчер кэша может возвращать страницы нулей вместо сбоя на фактических страницах файловых данных с диска. Если этот флаг установлен, диспетчер кэша не отслеживает грязное страниц. Вызывающий объект отвечает за отслеживание любых грязное страниц. Обратите внимание, что ccPreparePinWrite следует использовать для закрепления данных таким образом, только если буфер в конечном итоге будет сбрасываться на диск. Перед вызовом CcFlushCache для очистки буфера на диск вызывающий объект должен сначала вызвать MmSetAddressRangeModified, чтобы уведомить диспетчер памяти о том, что указанные страницы в буфере системного кэша грязное и должны быть записаны.

Каждый успешный вызов CcPreparePinWrite должен соответствовать последующему вызову CcUnpinData. Если ccPreparePinWrite вызывается несколько раз для одних и того же данных, ccUnpinData необходимо вызывать одинаковое количество раз.

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

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

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

Не нужно вызывать CcSetDirtyPinnedData после вызова CcPreparePinWrite. Если CcPreparePinWrite возвращает значение TRUE, bcb уже помечается как грязное.

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

Требования

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