Función FsRtlCopyWrite (ntifs.h)

La rutina FsRtlCopyWrite copia los datos de un búfer de usuario en un archivo almacenado en caché.

Sintaxis

BOOLEAN FsRtlCopyWrite(
  [in]  PFILE_OBJECT     FileObject,
  [in]  PLARGE_INTEGER   FileOffset,
  [in]  ULONG            Length,
  [in]  BOOLEAN          Wait,
  [in]  ULONG            LockKey,
  [in]  PVOID            Buffer,
  [out] PIO_STATUS_BLOCK IoStatus,
  [in]  PDEVICE_OBJECT   DeviceObject
);

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 almacenado en caché.

[in] Length

Longitud en bytes de los datos que se van a escribir.

[in] Wait

Se establece en TRUE si el autor de la llamada puede colocarse en un estado de espera hasta que se copien todos los datos; de lo contrario, false.

[in] LockKey

Valor asociado al intervalo de bytes que se va a bloquear. Si el intervalo para bloquear se superpone a otro intervalo que ya está bloqueado con un bloqueo noclusivo, o si el intervalo que se va a leer es un subrango de otro intervalo que ya está bloqueado de forma noclusiva, el valor de este parámetro debe ser la clave para ese bloqueo noclusivo El bloqueo debe mantenerse en el proceso primario del subproceso que realiza la llamada. De lo contrario, este parámetro no tiene ningún efecto.

[in] Buffer

Puntero al búfer desde el que se van a copiar los datos.

[out] IoStatus

Puntero a una estructura asignada por el autor de la llamada que recibe el estado de finalización final e información sobre la operación. Si los datos se copian correctamente, IoStatus.Status contiene STATUS_SUCCESS. Si no todos los datos se copian correctamente, IoStatus.Information contiene el número real de bytes que se copiaron.

[in] DeviceObject

Puntero al objeto de dispositivo para el volumen montado que contiene los datos del archivo.

Valor devuelto

FsRtlCopyWrite devuelve TRUE si la solicitud de copia se completó, FALSE en caso contrario. Tenga en cuenta que un valor devuelto de TRUE no significa necesariamente que la operación de copia se haya realizado correctamente.

Si FsRtlCopyWrite devuelve FALSE o si el contenido de IoStatus indica que se produjo un error en la operación de copia, el autor de la llamada debe asignar un IRP de escritura en lugar de llamar a FsRtlCopyWrite.

Comentarios

En lugar de implementar una rutina de escritura rápida de E/S específica del sistema de archivos, los desarrolladores de sistemas de archivos que admiten el almacenamiento en caché de archivos deben considerar el uso de FsRtlCopyWrite como punto de entrada del sistema de archivos para procesar solicitudes de escritura de E/S rápidas. Esto requiere que la rutina DriverEntry del sistema de archivos establezca el punto de entrada FastIoWrite en FsRtlCopyWrite en la estructura FAST_IO_DISPATCH del objeto del controlador del sistema de archivos. Además, el sistema de archivos debe hacer lo siguiente:

1. Para cada archivo en el que se pueda realizar E/S rápida, el sistema de archivos debe asignar e inicializar una estructura de FSRTL_COMMON_FCB_HEADER.

   En la mayoría de los sistemas de archivos, esto se logra mediante la inclusión de la estructura FSRTL_COMMON_FCB_HEADER en un bloque de control de archivos (FCB) o una estructura comparable que se usa para mantener el estado de un archivo abierto.

   El almacenamiento de la estructura de FSRTL_COMMON_FCB_HEADER normalmente se asigna desde el grupo paginado.

2. Para cada archivo en el que se pueda realizar E/S rápida, el sistema de archivos debe vincular los objetos de archivo del archivo a la estructura de FSRTL_COMMON_FCB_HEADER. Esto se hace estableciendo el miembro FsContext de cada objeto de archivo para que apunte a esta estructura (o a la FCB u otra estructura que contiene la estructura FSRTL_COMMON_FCB_HEADER).

3. Al almacenar en caché un archivo, el sistema de archivos debe establecer el miembro IsFastIoPossible de la estructura FSRTL_COMMON_FCB_HEADER del archivo en un valor adecuado. Este valor debe actualizarse según sea necesario siempre que el archivo permanezca almacenado en caché.

   En concreto, los sistemas de archivos deben establecer el miembro IsFastIoPossible de la estructura de FSRTL_COMMON_FCB_HEADER en FastIoIsQuestionable en cuanto exista un bloqueo de intervalo de bytes exclusivo en el archivo almacenado en caché.

Si Wait es TRUE, se garantiza que FsRtlCopyWrite copie los datos y devuelva TRUE. Si las páginas necesarias del archivo almacenado en caché ya residen en la memoria, los datos se copiarán inmediatamente y no se producirá ningún bloqueo. Si las páginas necesarias no son residentes, el autor de la llamada se colocará en un estado de espera hasta que todas las páginas necesarias se hayan hecho residentes y se puedan copiar los datos.

Si Wait es FALSE, FsRtlCopyWrite se negará a bloquear y devolverá FALSE, si no puede adquirir el recurso principal del archivo o si las páginas necesarias del archivo almacenado en caché aún no residen en la memoria.

La rutina FastIoCheckIfPossible del sistema de archivos es responsable de garantizar que el intervalo de bytes definido por FileOffset y Length no incluya ningún intervalo de bytes bloqueado exclusivamente para el que el autor de la llamada no pase el valor LockKey adecuado. Si el sistema de archivos usa las rutinas de soporte técnico de FsRtlXxxLockYyy para administrar bloqueos de intervalo de bytes, esto se puede lograr llamando a FsRtlFastCheckLockForWrite desde la rutina FastIoCheckIfPossible antes de llamar a FsRtlCopyRead.

Para almacenar en caché un archivo, use la rutina CcInitializeCacheMap .

Requisitos

Requisito	Value
Plataforma de destino	Universal
Encabezado	ntifs.h (incluya Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Reglas de cumplimiento de DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)

Consulte también

CcInitializeCacheMap

FsRtlCopyRead

FsRtlFastCheckLockForWrite