Función CcPreparePinWrite (ntifs.h)

Artículo
08/07/2023

La rutina CcPreparePinWrite ancla el intervalo de bytes especificado de un archivo almacenado en caché para el acceso de escritura.

Sintaxis

BOOLEAN CcPreparePinWrite(
  [in]  PFILE_OBJECT   FileObject,
  [in]  PLARGE_INTEGER FileOffset,
  [in]  ULONG          Length,
  [in]  BOOLEAN        Zero,
  [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 van a escribir los datos.

[in] FileOffset

Puntero a una variable que especifica el desplazamiento de bytes inicial dentro del archivo donde se van a escribir los datos.

[in] Length

Longitud de los datos deseados en bytes.

[in] Zero

Se establece en TRUE si el búfer se va a cero en la devolución. Este parámetro se omite si la marca PIN_CALLER_TRACKS_DIRTY_DATA está establecida en el parámetro Flags .

[in] Flags

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

Valor	Significado
PIN_WAIT	El autor de la llamada puede colocarse 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.
PIN_NO_READ	Solo las páginas que ya están residentes 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 no se devuelve ningún BCB.
PIN_CALLER_TRACKS_DIRTY_DATA	El autor de la llamada es responsable de realizar un seguimiento de las páginas desfasadas. Si se establece esta marca, se omiten todas las demás marcas. Esta marca está disponible en Microsoft Windows Server 2003 SP1 y versiones posteriores.

[out] Bcb

Puntero opaco a un bloque de control de búfer anclado (BCB). Este puntero debe proporcionarse como entrada en las llamadas posteriores a CcPreparePinWrite o CcUnpinData para este búfer.

[out] Buffer

Devuelve el puntero a los datos deseados, válido hasta que el búfer se desancla o libera.

Valor devuelto

CcPreparePinWrite devuelve TRUE si el archivo almacenado en caché se ancló correctamente, FALSE en caso contrario.

Comentarios

CcPreparePinWrite ancla las páginas de archivo especificadas en la memoria caché del sistema. Es posible que las páginas que se sobrescriban completamente se cumplan con las páginas de ceros.

Si se establece la marca PIN_WAIT, se garantiza que CcPreparePinWrite complete la solicitud de preparación y devuelva TRUE. Si todas las páginas se pueden preparar inmediatamente, no se produce 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 todas las páginas necesarias se hayan hecho residentes y se puedan preparar las páginas. Si no se establece la marca de PIN_WAIT, pero no todas las páginas se pueden preparar inmediatamente, CcPreparePinWrite devuelve FALSE y sus valores de parámetro de salida no tienen sentido.

Microsoft Windows Server 2003 SP1 y versiones posteriores: La marca de PIN_CALLER_TRACKS_DIRTY_DATA se usa normalmente en los casos en los que un sistema de archivos administra un archivo de registro que se escribe en pero no se lee. Dado que los datos de archivo existentes se sobrescribirán y no se leerán, el administrador de caché puede devolver páginas de ceros en lugar de generar errores en las páginas reales de datos de archivo del disco. Si se establece esta marca, el administrador de caché no realiza un seguimiento de las páginas desfasadas. El autor de la llamada es responsable de realizar un seguimiento de las páginas sucias. Tenga en cuenta que CcPreparePinWrite solo debe usarse para anclar datos de esta manera si el búfer finalmente se vaciará en el disco. Antes de llamar a CcFlushCache para vaciar el búfer en el disco, el autor de la llamada primero debe llamar a MmSetAddressRangeModified para notificar al administrador de memoria que las páginas especificadas en el búfer de caché del sistema están sucias y deben escribirse.

Cada llamada correcta a CcPreparePinWrite debe coincidir con una llamada posterior a CcUnpinData. Si se llama a CcPreparePinWrite varias veces para los mismos datos, se debe llamar a CcUnpinData el mismo número de veces.

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 sigue siendo válido después de la llamada a CcPinMappedData (pero solo hasta que se llame a CcUnpinData ).

CcPreparePinWrite 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, a partir de 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 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 caché del sistema, pero el administrador de memoria puede paginar las páginas físicas, ya que requiere la demanda de memoria del sistema.

No es necesario llamar a CcSetDirtyPinnedData después de llamar a CcPreparePinWrite. Si CcPreparePinWrite devuelve TRUE, el BCB ya está marcado como sucio.

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