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 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 OVERLAPPEDstructure. 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 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 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 aSegmentArraycontains a one-page chunk of this total. If nNumberOfBytesToWriteis set to zero, the function performs a null write operation. The behavior of a null write operation depends on the underlying file system. If nNumberOfBytesToWriteis 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 aSegmentArraybecause there is a one-to-one mapping between the array of offsets and aSegmentArrayso 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 aSegmentArrayand by lpReservedis 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