Función CcMapData (ntifs.h)

Artículo
02/29/2024

La rutina CcMapData asigna un intervalo de bytes especificado de un archivo almacenado en caché a un búfer en memoria.

Sintaxis

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

Parámetros

[in] FileObject

Puntero a un objeto de archivo para el archivo cuyos datos se van a asignar para el acceso de lectura.

[in] FileOffset

Puntero a una variable que especifica el desplazamiento de bytes inicial dentro del archivo almacenado en caché donde residen los datos deseados.

[in] Length

Longitud de los datos deseados en bytes.

[in] Flags

Máscara de bits de marcas que especifican cómo se va a realizar la operación de asignación. Se trata de una combinación OR bit a bit de uno o varios de los valores siguientes:

Valor	Significado
MAP_WAIT	El autor de la llamada se puede colocar en un estado de espera hasta que se hayan asignado los datos.
MAP_NO_READ	Solo se asignarán las páginas que ya residen en la memoria.

Nota En Windows 2000 y versiones anteriores, este parámetro era un valor BOOLEAN denominado Wait:

Esperar

Se establece en TRUE si el autor de la llamada se puede colocar en un estado de espera hasta que se hayan asignado los datos; en caso contrario, FALSE .

[out] Bcb

En la primera llamada, devuelve un puntero a una estructura de bloque de control de búfer (BCB). Este puntero debe proporcionarse como entrada en todas las llamadas posteriores, para este búfer.

[out] Buffer

Puntero a un búfer que contiene los datos asignados.

Valor devuelto

CcMapData devuelve TRUE si los datos del archivo almacenado en caché se asignaron correctamente, FALSE en caso contrario.

Comentarios

CcMapData asigna datos en un archivo almacenado en caché para el acceso de lectura. Tenga en cuenta que después de llamar a CcMapData , los datos se asignan; pero no está anclado. Esta distinción es importante. Los datos asignados pero no anclados no se pueden modificar de forma segura. Para anclar los datos, use CcPinMappedData, CcPinRead o CcPreparePinWrite.

Cada llamada correcta a CcMapData debe coincidir con una llamada posterior a CcUnpinData.

CcMapData no puede asignar datos a través de los límites de vista en el administrador de caché. El administrador de caché administra los archivos del sistema en vistas alineadas con 256 KB. (El tamaño de vista del administrador de caché se especifica mediante la constante definida por el sistema VACB_MAPPING_GRANULARITY, que se establece en 256 KB en ntifs.h). Las regiones asignadas no pueden abarcar más de una vista de 256 KB. Por lo tanto, la región más grande que se puede asignar es de 256 KB, empezando por un desplazamiento alineado con 256 KB en el archivo.

La asignación de un intervalo de bytes en un archivo almacenado en caché no garantiza que las páginas permanezcan residentes en la memoria. Siempre que se asignen las páginas, se garantiza que el intervalo de bytes se mantenga asignado al espacio de direcciones virtuales de la memoria caché del sistema, pero el administrador de memoria puede paginar las páginas físicas según requiera la demanda de memoria del sistema.

Si se establece la marca MAP_WAIT (o Wait es TRUE), se garantiza que CcMapData complete la solicitud de asignación y devuelva TRUE. Si las páginas necesarias del archivo almacenado en caché ya residen en la memoria, los datos se asignan inmediatamente y no se producirá ningún bloqueo. Si las páginas necesarias no son residentes, el autor de la llamada se coloca en un estado de espera hasta que se hayan hecho residentes todas las páginas necesarias y se puedan asignar los datos. Si no se establece la marca MAP_WAIT (o Wait es FALSE) y los datos no se pueden asignar inmediatamente, CcMapData devuelve FALSE.

El puntero devuelto en Buffer es válido hasta que se llama a CcUnpinData . Si se llama a CcPinMappedData mientras este puntero sigue siendo válido, el puntero permanece válido después de la llamada a CcPinMappedData (pero solo hasta que se llama a CcUnpinData ).

Si se produce algún error, CcMapData genera una excepción de estado para ese error en particular. Por ejemplo, si se produce un error de asignación de grupo, CcMapData genera una excepción de STATUS_INSUFFICIENT_RESOURCES ; Si se produce un error de E/S, CcMapData genera la excepción de estado del error de E/S. Por lo tanto, para obtener control si se produce un error, el controlador debe encapsular la llamada a CcMapData en una instrucción try-except o try-finally .

Para almacenar en caché un archivo, use CcInitializeCacheMap.