MyFSD_ReadFileScatter

A version of this page is also available for

Windows Embedded CE 6.0 R3

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 GetSystemInfo function.

• nNumberOfBytesToRead
  [in] Number of bytes to be read from the file. Each element of aSegmentArray contains 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 aSegmentArray because there is a one-to-one mapping between the array of offsets and aSegmentArray so 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 GetLastError returns ERROR_HANDLE_EOF.

Remarks

The array pointed to by aSegmentArray must contain enough elements to store nNumberOfBytesToWrite bytes 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 aSegmentArray and by lpReserved, ** FILE_SEGMENT_ELEMENT, is defined as follows:

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

Requirements

See Also

Reference

MyFSD Functions
MyFSD_WriteFileGather