Función CcPinRead (ntifs.h)

Artículo
02/26/2024

La rutina CcPinRead ancla el intervalo de bytes especificado de un archivo almacenado en caché y lee los datos anclados en un búfer en memoria.

Sintaxis

BOOLEAN CcPinRead(
  [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 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 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 anclaje. Combinación de ORed de uno o varios de los valores siguientes:

Valor	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.

[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.

[out] Buffer

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

Valor devuelto

CcPinRead devuelve TRUE si los datos del archivo almacenado en caché se anclaron y se leyeron correctamente; de lo contrario, FALSE .

Comentarios

Si se establece la marca PIN_WAIT, se garantiza que CcPinRead complete la solicitud de anclaje y devuelva TRUE. Si las páginas necesarias del archivo almacenado en caché ya residen en la memoria, los datos se anclan inmediatamente y no se produce ningún bloqueo. Si las páginas necesarias no están 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 anclar los datos. Si no se establece la marca PIN_WAIT, pero los datos no se pueden anclar inmediatamente, CcPinRead devuelve FALSE y sus valores de parámetro de salida no tienen sentido.

Si el autor de la llamada modifica posteriormente los datos leídos por CcPinRead, también debe llamar a CcSetDirtyPinnedData para que los datos modificados se escriban en el disco.

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

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 ).

CcPinRead 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, CcPinRead genera una excepción de estado para ese error en particular. Por ejemplo, si se produce un error de asignación de grupo, CcPinRead genera una excepción de STATUS_INSUFFICIENT_RESOURCES; Si se produce un error de E/S, CcPinRead 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 CcPinRead 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.