MyFSD_WriteFileGather

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function gathers data from a set of buffers and writes it to a file. This function starts writing data to the file at a position specified by an OVERLAPPED structure. It operates asynchronously.

Syntax

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

Parameters

• hFile
  [in] Handle to the file. This file handle must have been created with GENERIC_WRITE access right.

• aSegmentArray
  [in] Pointer to an array of FILE_SEGMENT_ELEMENT buffers that contains the data. Each element contains one page of data. To determine the size of a system page, use GetSystemInfo.

  The array 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 writes one system memory page of data from each buffer.

  This function gathers the data from the buffers in a sequential manner: it writes data to the file from the first buffer, then from the second buffer, then from the next, until there is no more data.

• nNumberOfBytesToWrite
  [in] Total number of bytes to write. Each element of aSegmentArray contains a one-page chunk of this total. If nNumberOfBytesToWrite is set to zero, the function performs a null write operation. The behavior of a null write operation depends on the underlying file system. If nNumberOfBytesToWrite is not set to zero and the offset and length of the write place data beyond the current end of the file, this function extends the file.

• lpReserved
  [in] Pointer to an array of FILE_SEGMENT_ELEMENT unions. If the user wants to write to discontinuous parts of the file, this parameter can be used to pass in an array of offsets to write to. This parameter must contain the same number of elements as the aSegmentArray because there is a one-to-one mapping between the array of offsets and aSegmentArray so that a particular buffer corresponds to the file offset to write to.

  If this parameter is set to NULL, the write starts at the internal file pointer and writes to contiguous pages. In this case, the function updates the internal file pointer after the write 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.

Remarks

The FILE_SEGMENT_ELEMENT union referred to by aSegmentArray and by lpReserved 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_ReadFileScatter