Función CcPinMappedData (ntifs.h)

Artículo
02/29/2024

La rutina CcPinMappedData ancla el intervalo de bytes especificado de un archivo almacenado en caché.

Sintaxis

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

Parámetros

[in] FileObject

Puntero a un objeto de archivo para el archivo almacenado en caché en el que se va a anclar un intervalo de datos.

[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 en bytes de los datos que se van a anclar.

[in] Flags

Máscara de bits de marcas que especifican cómo se va a realizar la operación de anclaje. Combinación de ORed de uno o varios de los valores siguientes:

Marca	Significado
PIN_WAIT	El autor de la llamada se puede colocar en un estado de espera hasta que se hayan anclado los datos.
PIN_EXCLUSIVE	El bloque de control de búfer (BCB) se va a adquirir exclusivamente. Si se establece esta marca, también se debe establecer PIN_WAIT.
PIN_NO_READ	Solo las páginas que ya residen en la memoria se van a anclar. Si se establece esta marca, también se debe establecer PIN_WAIT.
PIN_IF_BCB	Los datos se van a anclar solo si ya existe un BCB. De lo contrario, se produce un error en el pin y Bcb se establece en NULL.

[in, out] Bcb

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

Valor devuelto

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

Comentarios

Una devolución correcta de CcPinMappedData garantiza que los datos asignados previamente en una llamada a CcMapData se anclan en la memoria caché y los datos del intervalo especificado se pueden modificar de forma segura. Si el autor de la llamada modifica posteriormente los datos anclados por CcPinMappedData, también debe llamar a CcSetDirtyPinnedData para que los datos modificados se escriban en el disco.

CcPinMappedData no puede anclar 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 ancladas no pueden abarcar más de una vista de 256 KB. Por lo tanto, la región más grande que se puede anclar es de 256 KB, comenzando en un desplazamiento alineado con 256 KB en el archivo.

Anclar un intervalo de bytes en un archivo almacenado en caché no garantiza que las páginas permanezcan residentes en la memoria. Siempre que las páginas estén ancladas, 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 produce algún error, CcPinMappedData genera una excepción de estado para ese error en particular. Por ejemplo, si se produce un error de asignación de grupo, CcPinMappedData genera una excepción de STATUS_INSUFFICIENT_RESOURCES ; Si se produce un error de E/S, CcPinMappedData 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 CcPinMappedData en una instrucción try-except o try-finally .

Para asignar datos de un archivo almacenado en caché, use la rutina CcMapData . Para almacenar en caché un archivo, use CcInitializeCacheMap.

No es necesario llamar a CcUnpinData después de llamar a CcPinMappedData , ya que la referencia de patillas coincide con CcMapData.