Функция WriteFileGather собирает данные из набора буферов и пишет данные в файл.
Функция начинает писать данные в файл с позиции, заданной структурой OVERLAPPED. Она работает асинхронно.
Синтаксис
BOOL WriteFileGather( HANDLE hFile, // дескриптор файла FILE_SEGMENT_ELEMENT aSegmentArray[ ],// массив указателей буферов DWORD nNumberOfBytesToWrite, // число записываемых байтов LPDWORD lpReserved, // резерв LPOVERLAPPED lpOverlapped // асинхронный буфер ); |
Параметры
hFile
[in] Дескриптор файла. Этот дескриптор файла должен быть создан с правом доступа GENERIC_WRITE и флажками FILE_FLAG_OVERLAPPED и FILE_FLAG_NO_BUFFERING. Подробную информацию о правах доступа, см. в статье Защита файла и права доступа.aSegmentArray
[out] Указатель на массив буферов FILE_SEGMENT_ELEMENT, которые содержат данные. Каждый элемент содержит одну страницу данных (чтобы определить размер в страницы системной памяти, используйте функцию GetSystemInfo). Массив должен содержат 11 элементов, чтобы сохранить nNumberOfBytesToWrite байтов данных, плюс один элемент для символа конца строки NULL. Например, если число байтов для записи - 40 КБ, а размер системной страницы - 4 КБ, то этот массив должен иметь 10 членов для данных, плюс один член структуры для конечного пустого члена, общее количество - 11 членов структуры.Каждый буфер должен быть, по крайней мере, размером в страницу системной памяти и должен выравниваться по границе размера этой страницы. Система должна писать по одной странице системной памяти данных из каждого буфера.
Функция собирает данные из буферов последовательным способом: она пишет данные в файл из первого буфера, затем - из второго, затем - из следующего до тех пор, пока не закончатся данные для записи.
nNumberOfBytesToWrite
[in] Общее количество записываемых байтов. Каждый элемент aSegmentArray содержит 1-страничную порцию от общего количества данных. Поскольку файл должен открываться с флажком FILE_FLAG_NO_BUFFERING, число байтов для записи должно быть кратным размеру сектора файловой системы, в которой постоянно находится файл.Если параметр nNumberOfBytesToWrite равняется нулю, функция исполняет пустую операцию записи. Поведение операции пустой записи зависит от лежащей в основе файловой системы. Если nNumberOfBytesToWrite не нуль, а смещение и длина данных места записи вне текущего конца файла, WriteFileGather продляет файл.
lpReserved
Этот параметр резервируется для будущего использования и должен быть NULL.lpOverlapped
[in] Указатель на структуру данных OVERLAPPED.Функция WriteFileGather требует допустимой структуры OVERLAPPED. Параметр lpOverlapped не может иметь значения NULL.
Функция WriteFileGather начинает запись данных в файл с позиции, определенной членами Offset и OffsetHigh структуры OVERLAPPED.
Функция WriteFileGather может возвратить значение прежде, чем закончится операция записи. В этом случае функция WriteFileGather возвращает значение нуль, а функция GetLastError возвращает значение ERROR_IO_PENDING. Эта асинхронная операция WriteFileGather позволяет вызывающему процессу продолжать работать до тех пор, пока операция записи не закончит работу. Вы можете вызвать функцию GetOverlappedResult, HasOverlappedIoCompleted или GetQueuedCompletionStatus, чтобы получить информацию об окончании операции записи.
Возвращаемые значения
Если функция завершается успешно, возвращаемое значение - не нуль.
Если функция завершается ошибкой, величина возвращаемого значения - нуль. Чтобы получить дополнительные данные об ошибке, вызовите функцию GetLastError.
Если функция возвращает значение прежде, чем закончится операция записи, функция возвращает нуль, а GetLastError возвращает ошибку ERROR_IO_PENDING.
Замечания
Союз FILE_SEGMENT_ELEMENT определяется как ниже указано:
typedef union _FILE_SEGMENT_ELEMENT {
PVOID64 Buffer;
ULONGLONG Alignment;
}FILE_SEGMENT_ELEMENT, *PFILE_SEGMENT_ELEMENT;
|
Если часть файла, определяемого параметром hFile блокируется другим процессом, а операция записи накладывается на заблокированную часть, функция WriteFileGather завершается ошибкой.
Смотри также
Обзор Управление файлами, Функции для файлового ввода-вывода (I/O), CreateFile, GetOverlappedResult , GetQueuedCompletionStatus, HasOverlappedIoCompleted, OVERLAPPED, ReadFile, ReadFileEx, ReadFileScatter
|
Размещение и совместимость WriteFileGather |
||
| К |
Windows XP |
Да |
| л |
Windows 2000 Professional |
Да |
| и |
Windows NT Workstation |
Да версии 4.0 SP2 и выше |
| е |
Windows Me |
Нет |
| н |
Windows 98 |
Нет |
| т |
Windows 95 |
Нет |
| С |
Windows Server 2003 |
Да |
| е | Windows 2000 Server | Да |
| р | Windows NT Server | Да версии 4.0 SP2 и выше |
| в | ||
| е | ||
| р | ||
|
Используемая библиотека |
Kernel32.lib |
|
| Используемая DLL | - | |
| Заголовочный файл | ||
|
- объявлено в |
Winbase.h |
|
| - включено в |
Windows.h |
|
| Unicode |
Реализуется как версии Unicode и ANSI. |
|
| Замечания по платформе |
Не имеется |
|