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

2024-12-21

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

Синтаксис

BOOLEAN CcMapData(
  [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

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

Ценность	Значение
MAP_WAIT	Вызывающий объект можно поместить в состояние ожидания до тех пор, пока данные не будут сопоставлены.
MAP_NO_READ	Сопоставляются только те страницы, которые уже находятся в памяти.

Примечание в Windows 2000and ранее, этот параметр был логическим значением с именем Wait:

Ждать

Задайте значение TRUE, если вызывающий объект может быть помещен в состояние ожидания, пока данные не будут сопоставлены, FALSE в противном случае.

[out] Bcb

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

[out] Buffer

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

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

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

Замечания

CcMapData сопоставляет данные в кэшированном файле для доступа на чтение. Обратите внимание, что после вызова CcMapData данные сопоставляются; но это не закреплено. Это различие важно. Данные, сопоставленные, но не закрепленные, не могут быть безопасно изменены. Чтобы закрепить данные, используйте CcPinMappedData, CcPinReadили CcPreparePinWrite.

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

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

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

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

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

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

Чтобы кэшировать файл, используйте CcInitializeCacheMap.

Требования

Требование	Ценность
целевая платформа	Всеобщий
заголовка	ntifs.h (include Ntifs.h)
библиотеки	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	< DISPATCH_LEVEL