ReadFileScatter

The ReadFileScatter function reads data from a file and stores the data into a set of buffers.

The ReadFileScatter function starts reading data from the file at a position specified by an OVERLAPPED structure.

The ReadFileScatter function operates asynchronously.

BOOL ReadFileScatter(
  HANDLE hFile,              // handle to a file to read data from
  FILE_SEGMENT_ELEMENT aSegmentArray [],
                             // pointer to an array of buffer 
                             // pointers
  DWORD nNumberOfBytesToRead,  // number of bytes to read
  LPDWORD lpReserved,        // reserved; must be NULL
  LPOVERLAPPED lpOverlapped  // pointer to an asynchronous I/O data 
                             // structure
);
 

Parameters

hFile

An open handle to the file to read from.

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.

aSegmentArray

Pointer to an array of FILE_SEGMENT_ELEMENT pointers to buffers. The function stores the data it reads from the file into this set of buffers.

Each buffer should be the size of a system memory page. Each buffer should be aligned on a system memory page size boundary.

A FILE_SEGMENT_ELEMENT pointer is a 64-bit value. The ReadFileScatter function uses all 64 bits. Since the operating systems do not currently support 64-bit memory addressing, you must explicitly zero the upper 32 bits of each FILE_SEGMENT_ELEMENT pointer.

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 should be a NULL pointer.

nNumberOfBytesToRead

Specifies the number of bytes to read from the file.

lpReserved

This parameter is reserved for future use. You must set it to NULL.

lpOverlapped

Pointer to an OVERLAPPED data structure.

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.

Return Values

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.

QuickInfo

  Windows NT: Requires version 4.0 SP2 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in winbase.h.
  Import Library: Use kernel32.lib.

See Also

File I/O Overview, File Functions, CreateFile, GetOverlappedResult, GetQueuedCompletionStatus, HasOverlappedIoCompleted, OVERLAPPED, ReadFile, ReadFileEx, ReadFileVlm, WriteFileGather