Función CcPreparePinWrite (ntifs.h)
El CcPreparePinWrite rutina 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é al 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
Establézcalo en TRUE si el búfer se va a cero al devolver. 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 de ORed de uno o varios de los siguientes valores:
| 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 se van a anclar las páginas que ya están residentes en la memoria. Si se establece esta marca, también se debe establecer PIN_WAIT. |
| PIN_IF_BCB | Los datos solo se van a anclar si ya existe un BCB. De lo contrario, se produce un error en el pin y no se devuelve bcB. |
| PIN_CALLER_TRACKS_DIRTY_DATA | El autor de la llamada es responsable de realizar un seguimiento de las páginas sucias. 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 cualquier llamada posterior a CcPreparePinWrite o CcUnpinData para este búfer.
[out] Buffer
Devuelve el puntero a los datos deseados, válidos hasta que el búfer está desanclado o liberado.
Valor devuelto
ccPreparePinWrite devuelve TRUE si el archivo almacenado en caché se ancló correctamente, FALSE de lo contrario.
Observaciones
CcPreparePinWrite ancla las páginas de archivo especificadas en la memoria caché del sistema. Las páginas que se van a sobrescribir por completo pueden cumplirse con las páginas de ceros.
Si se establece la marca de PIN_WAIT, se garantiza ccPreparePinWrite para completar la solicitud de preparación y devolver 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 pone en un estado de espera hasta que se hayan hecho residentes todas las páginas necesarias y se puedan preparar las páginas. Si no se establece la marca PIN_WAIT, pero no todas las páginas se pueden preparar inmediatamente, ccPreparePinWrite devuelve FALSEy sus valores de parámetro de salida no tienen sentido.
Microsoft Windows Server 2003 SP1 y versiones posteriores: La marca PIN_CALLER_TRACKS_DIRTY_DATA se usa normalmente en los casos en los que un sistema de archivos administra un archivo de registro escrito en pero no leído. 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 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 se debe usar para anclar datos de esta manera si el búfer se vaciará finalmente en el disco. Antes de llamar a CcFlushCache para vaciar el búfer en el disco, el autor de la llamada debe llamar primero 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 ccPreparePinWrite se llama varias veces para los mismos datos, CcUnpinData debe llamarse al 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 llama a ccUnpinData).
CcPreparePinWrite no pueden 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 caché del sistema, pero el administrador de memoria puede paginar las páginas físicas, ya que la demanda de memoria del sistema requiere.
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 un try-except o instrucción try-finally.
Requisitos
| Requisito | Valor |
|---|---|
| de la plataforma de destino de |
Universal |
| encabezado de |
ntifs.h (incluya Ntifs.h) |
| biblioteca de |
NtosKrnl.lib |
| DLL de |
NtosKrnl.exe |
| irQL | PASSIVE_LEVEL |
Consulte también
ccMapData de
ccPinRead de