Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function reads data from a file and stores it in an array of buffers.

Syntax 

BOOL ReadFileScatter(
  HANDLE hFile,
  FILE_SEGMENT_ELEMENT aSegmentArray[],
  DWORD nNumberOfBytesToRead,
  LPDWORD lpReserved,
  LPOVERLAPPED lpOverlapped
);

Parameters

hFile

[in] Handle to the file to be read.

This file handle must have been created with the GENERIC_READ access.

aSegmentArray

[out] Pointer to an array of FILE_SEGMENT_ELEMENT buffers that receives the data. Each element can receive one page of data. To determine the size of a system page, use the GetSystemInfofunction.

nNumberOfBytesToRead

[in] Number of bytes to be read from the file. Each element of aSegmentArraycontains a one-page chunk of this total.

lpReserved

[in] Pointer to an array of FILE_SEGMENT_ELEMENT unions that enables reading from discontinuous parts of the file by providing offsets to read from. If used, this parameter must contain the same number of elements as aSegmentArraybecause there is a one-to-one mapping between the array of offsets and aSegmentArrayso that each offset corresponds to the buffer to read into.

If this parameter is set to NULL, the read starts at the internal file pointer and reads contiguous pages. In this case, the function updates the internal file pointer after the read is complete.

lpOverlapped

[in] Unsupported. Set to NULL.

Return Value

A nonzero value indicates success. Zero indicates failure. To get extended error information, call GetLastError.

If the function attempts to read past the end of the file, the function returns zero, and GetLastErrorreturns ERROR_HANDLE_EOF.

Remarks

The array pointed to by aSegmentArraymust contain enough elements to store nNumberOfBytesToWritebytes of data.

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 reads one system memory page of data into each buffer.

This function stores the data in the buffers in a sequential manner. That is, 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 union pointed to by aSegmentArrayand by lpReserved, FILE_SEGMENT_ELEMENT, is defined as follows:

Copy Code 
typedef union _FILE_SEGMENT_ELEMENT
{
   PVOID64 Buffer;
   ULONGLONG Alignment;
}
FILE_SEGMENT_ELEMENT, *PFILE_SEGMENT_ELEMENT;

Requirements

Header fsdmgr.h
Library Fsdmgr.lib
Windows Embedded CE Windows Embedded CE 6.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also