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

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

[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, которая имеет значение 256 КБ в ntifs.h.) Закрепленные регионы не могут охватывать более одного представления 256 КБ. Таким образом, самый большой регион, который можно закрепить, составляет 256 КБ, начиная с смещения с выравниванием 256 КБ в файле.

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

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

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

Требования

См. также

CcFlushCache

CcMapData

CcPinMappedData

CcPinRead

CcSetDirtyPinnedData

CcUnpinData

MmSetAddressRangeModified