Platform SDK: Files and I/O |
The ReadFileScatter function reads data from a file and stores the data into a set of buffers.
The function starts reading data from the file at a position specified by an OVERLAPPED structure. It operates asynchronously.
BOOL ReadFileScatter( HANDLE hFile, // handle to file FILE_SEGMENT_ELEMENT aSegmentArray[ ], // array of buffer pointers DWORD nNumberOfBytesToRead, // number of bytes to read LPDWORD lpReserved, // reserved; must be NULL LPOVERLAPPED lpOverlapped // OVERLAPPED structure );
This file handle must have been created using GENERIC_READ to specify read access to the file, FILE_FLAG_OVERLAPPED to specify asynchronous I/O, and FILE_FLAG_NO_BUFFERING to specify non-cached I/O.
Each buffer must be at least the size of a system memory page and must be aligned on a system memory page size boundary. The system will read one system memory page of data into each buffer that a FILE_SEGMENT_ELEMENT pointer points to.
The function stores the data into the buffers in a sequential manner: it stores data into the first buffer, then into the second buffer, then into the next, filling each buffer, until there is no more data or there are no more buffers.
The final element of the array must be a 64-bit NULL pointer.
Note The array must contain one member for each system memory page-sized chunk of the total number of bytes to read from the file, plus one member for the final NULL pointer. For example, if the number of bytes to read is 40K, and the system page size is 4K, then this array must have 10 members for data, plus one member for the final NULL member, for a total of 11 members.
The ReadFileScatter function requires a valid OVERLAPPED structure. The lpOverlapped parameter cannot be NULL.
The ReadFileScatter function starts reading data from the file at a position specified by the Offset and OffsetHigh members of the OVERLAPPED structure.
The ReadFileScatter function may return before the read operation has completed. In that case, the ReadFileScatter function returns the value zero, and the GetLastError function returns the value ERROR_IO_PENDING. This asynchronous operation of ReadFileScatter lets the calling process continue while the read operation completes. You can call the GetOverlappedResult, HasOverlappedIoCompleted, or GetQueuedCompletionStatus function to obtain information about the completion of the read operation.
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call the GetLastError function.
If the function attempts to read past the end of the file, the function returns zero, and GetLastError returns ERROR_HANDLE_EOF.
If the function returns before the read operation has completed, the function returns zero, and GetLastError returns ERROR_IO_PENDING.
Windows NT/2000: Requires Windows NT 4.0 SP2 or later.
Windows 95/98: Unsupported.
Header: Declared in Winbase.h; include Windows.h.
Library: Use Kernel32.lib.
File I/O Overview, File I/O Functions, CreateFile, GetOverlappedResult, GetQueuedCompletionStatus, HasOverlappedIoCompleted, OVERLAPPED, ReadFile, ReadFileEx, WriteFileGather