Función ReadFileScatter (fileapi.h)
Lee los datos de un archivo y los almacena en una matriz de búferes.
La función comienza a leer datos del archivo en una posición especificada por una estructura SUPERPUESTA . La función ReadFileScatter funciona de forma asincrónica.
Sintaxis
BOOL ReadFileScatter(
[in] HANDLE hFile,
[in] FILE_SEGMENT_ELEMENT [] aSegmentArray,
[in] DWORD nNumberOfBytesToRead,
LPDWORD lpReserved,
[in, out] LPOVERLAPPED lpOverlapped
);
Parámetros
[in] hFile
Identificador del archivo que se va a leer.
El identificador de archivo debe crearse con el GENERIC_READ derecho y las marcas FILE_FLAG_OVERLAPPED y FILE_FLAG_NO_BUFFERING . Para obtener más información, vea Derechos de acceso y seguridad de archivos.
[in] aSegmentArray
Puntero a una matriz de FILE_SEGMENT_ELEMENT búferes de estructura que recibe los datos. Para obtener una descripción de esta unión, vea Comentarios.
Cada elemento representa una página de datos.
Nota
Para determinar el tamaño de una página del sistema, use GetSystemInfo.
La matriz debe contener suficientes elementos para representar bytes nNumberOfBytesToRead de datos. Por ejemplo, si hay 40 KB para leer y el tamaño de página es de 4 KB, la matriz debe tener 10 elementos.
Cada búfer debe tener al menos el tamaño de una página de memoria del sistema y debe alinearse en un límite de tamaño de página de memoria del sistema. El sistema lee una página de memoria del sistema de datos en cada búfer.
La función almacena los datos en los búferes en orden secuencial. Por ejemplo, almacena datos en el primer búfer, después en el segundo búfer, etc. hasta que se rellena cada búfer y se almacenan todos los datos, o se han leído los bytes nNumberOfBytesToRead .
[in] nNumberOfBytesToRead
Número total de bytes que se van a leer del archivo. Cada elemento de aSegmentArray contiene un fragmento de una página de este total. Dado que el archivo debe abrirse con FILE_FLAG_NO_BUFFERING, el número de bytes debe ser un múltiplo del tamaño de sector del sistema de archivos donde se encuentra el archivo.
lpReserved
Este parámetro está reservado para uso futuro y debe ser NULL.
[in, out] lpOverlapped
Puntero a una estructura de datos SUPERPUESTA .
La función ReadFileScatter requiere una estructura SUPERPUESTA válida. El parámetro lpOverlapped no puede ser NULL.
La función ReadFileScatter comienza a leer datos del archivo en una posición especificada por los miembros Offset y OffsetHigh de la estructura SUPERPUESTA .
La función ReadFileScatter puede devolver antes de que se complete la operación de lectura. En ese escenario, la función ReadFileScatter devuelve el valor 0 (cero) y la función GetLastError devuelve el valor ERROR_IO_PENDING. Esta operación asincrónica de ReadFileScatter permite que el proceso de llamada continúe mientras se completa la operación de lectura. Puede llamar a las funciones GetOverlappedResult, HasOverlappedIoCompleted o GetQueuedCompletionStatus para obtener información sobre la finalización de la operación de lectura. Para obtener más información, vea E/S sincrónica y asincrónica.
Valor devuelto
Si la función se realiza correctamente, el valor devuelto es distinto de cero.
Si la función no se realiza correctamente, el valor devuelto es cero (0). Para obtener información ampliada de los errores, llame a la función GetLastError.
Si ReadFileScatter intenta leer más allá del final del archivo (EOF), la llamada a GetOverlappedResult para esa operación devuelve FALSE y GetLastError devuelve ERROR_HANDLE_EOF.
Si la función devuelve antes de que se complete la operación de lectura, la función devuelve cero (0) y GetLastError devuelve ERROR_IO_PENDING.
Comentarios
Esta función no es compatible con las aplicaciones de 32 bits de WOW64 en sistemas basados en Itanium.
La estructura FILE_SEGMENT_ELEMENT se define de la siguiente manera:
typedef union _FILE_SEGMENT_ELEMENT {
PVOID64 Buffer;
ULONGLONG Alignment;
}FILE_SEGMENT_ELEMENT, *PFILE_SEGMENT_ELEMENT;
Al asignar un puntero al miembro buffer , se ampliará el valor si el código se compila como 32 bits; Esto puede interrumpir las aplicaciones compatibles con direcciones grandes que se ejecutan en sistemas configurados con ajuste de 4 gigabytes o que se ejecutan en en WOW64 en Windows de 64 bits. Por lo tanto, use la macro PtrToPtr64 al asignar punteros a Buffer.
En Windows 8 y Windows Server 2012, esta función es compatible con las tecnologías siguientes.
| Tecnología | Compatible |
|---|---|
| Protocolo Bloque de mensajes del servidor (SMB) 3.0 | Sí |
| Conmutación por error transparente (TFO) de SMB 3.0 | Sí |
| SMB 3.0 con recursos compartidos de archivos de escalabilidad horizontal (SO) | Sí |
| Sistema de archivos de Volumen compartido de clúster (CsvFS) | Sí |
| Sistema de archivos resistente a errores (ReFS) | Sí |
Operaciones de transacción
Si hay una transacción enlazada al identificador de archivo, la función devuelve datos de la vista de transacción del archivo. Se garantiza que un identificador de lectura de transacción muestra la misma vista de un archivo mientras dura el identificador.Requisitos
| Cliente mínimo compatible | Windows XP [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows Server 2003 [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | fileapi.h (incluye Windows.h) |
| Library | Kernel32.lib |
| Archivo DLL | Kernel32.dll |