MyFSD_WriteFileGather (Windows CE 5.0)
The WriteFileGather function gathers data from a set of buffers and writes it to a file.
The function starts writing data to the file at a position specified by an OVERLAPPED structure. It operates asynchronously.
BOOL WriteFileGather(
HANDLEhFile,
FILE_SEGMENT_ELEMENTaSegmentArray[],
DWORDnNumberOfBytesToWrite,
LPDWORDlpReserved,
LPOVERLAPPEDlpOverlapped);
Parameters
hFile
[in] Handle to the file. This file handle must have been created with the 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, plus one element for the terminating NULL. For example, if there are 40K bytes to read, and the page size is 4K bytes, the array must have 11 elements (10 for the data, plus one for the NULL).
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 will write one system memory page of data from each buffer.
The 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 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 zero and the offset and length of the write place data beyond the current end of the file, WriteFileGather will extend 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 the aSegmentArray such that a particular buffer corresponds to the file offset to write to.If this parameter contains NULL, then the write will start at the internal file pointer and write 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 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.
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
OS Versions: Windows CE 5.0 and later
Header: FsdMgr.h.
Link Library: Fsdmgr.lib.
See Also
Send Feedback on this topic to the authors