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

Статья
08/07/2023

Подпрограмма 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

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

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

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

Ожидание

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

[out] Bcb

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

[out] Buffer

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

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

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

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

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

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

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

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

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

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

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

Требования

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