Функция WriteFileGather (fileapi.h)
Извлекает данные из массива буферов и записывает данные в файл.
Функция начинает запись данных в файл в позиции, указанной структурой OVERLAPPED . Функция WriteFileGather работает асинхронно.
Синтаксис
BOOL WriteFileGather(
[in] HANDLE hFile,
[in] FILE_SEGMENT_ELEMENT [] aSegmentArray,
[in] DWORD nNumberOfBytesToWrite,
LPDWORD lpReserved,
[in, out] LPOVERLAPPED lpOverlapped
);
Параметры
[in] hFile
Дескриптор файла. Дескриптор файла должен быть создан с правом доступа GENERIC_WRITE , а также флагами FILE_FLAG_OVERLAPPED и FILE_FLAG_NO_BUFFERING . Дополнительные сведения см. в разделе Безопасность файлов и права доступа.
[in] aSegmentArray
Указатель на массив FILE_SEGMENT_ELEMENT буферов структуры , содержащих данные. Описание этого объединения см. в разделе Примечания.
Каждый элемент представляет одну страницу данных.
Примечание
Чтобы определить размер системной страницы, используйте функцию GetSystemInfo .
Массив должен содержать достаточно элементов для представления байтов данных nNumberOfBytesToWrite . Например, если требуется записать 40 КБ и размер страницы составляет 4 КБ, массив должен содержать 10 элементов.
Каждый буфер должен быть не ниже размера страницы системной памяти и должен быть выровнен по границе размера страницы системной памяти. Система записывает одну страницу данных системной памяти из каждого буфера.
Функция собирает данные из буферов в последовательном порядке. Например, он записывает данные в файл из первого, затем второго буфера и т. д., пока не будут записаны байты nNumberOfBytesToWrite .
Из-за асинхронной работы этой функции необходимо принять меры предосторожности, чтобы гарантировать, что этот параметр всегда ссылается на допустимую память в течение времени существования асинхронных операций записи. Например, распространенная ошибка программирования заключается в использовании локального хранилища стека, а затем разрешить выполнение область.
[in] nNumberOfBytesToWrite
Общее число записываемых байтов. Каждый элемент объекта ASegmentArray содержит одностраничный блок из этого итогового значения. Так как файл должен быть открыт с FILE_FLAG_NO_BUFFERING, количество байтов должно быть кратно размеру сектора файловой системы, в которой находится файл.
Если nNumberOfBytesToWrite равно нулю (0), функция выполняет операцию записи null. Поведение операции записи null зависит от базовой файловой системы. Если nNumberOfBytesToWrite не равно нулю (0), а смещение и длина данных места записи выходят за пределы текущего конца файла, функция WriteFileGather расширяет файл.
lpReserved
Этот параметр зарезервирован для использования в будущем и должен иметь значение NULL.
[in, out] lpOverlapped
Указатель на структуру данных OVERLAPPED .
Для функции WriteFileGather требуется допустимая структура OVERLAPPED . Параметр lpOverlapped не может иметь значение NULL.
Функция WriteFileGather начинает запись данных в файл в позиции, указанной элементами Offset и OffsetHigh структуры OVERLAPPED .
Функция WriteFileGather может вернуться до завершения операции записи. В этом сценарии функция WriteFileGather возвращает нулевое значение (0), а функция GetLastError возвращает значение ERROR_IO_PENDING. Эта асинхронная операция функции WriteFileGather позволяет продолжить вызывающий процесс, пока операция записи завершается.
Для получения сведений о завершении операции записи можно вызвать функцию GetOverlappedResult, HasOverlappedIoCompleted или GetQueuedCompletionStatus . Дополнительные сведения см. в разделе Синхронный и асинхронный ввод-вывод.
Возвращаемое значение
Если функция выполняется успешно, возвращается ненулевое значение.
Если функция завершается сбоем, возвращаемое значение равно нулю (0). Чтобы получить расширенные сведения об ошибке, вызовите функцию GetLastError .
Если функция возвращается до завершения операции записи, функция возвращает ноль (0), а функция GetLastError возвращает ERROR_IO_PENDING.
Комментарии
Эта функция не поддерживается для 32-разрядных приложений WOW64 в системах на основе Itanium.
Структура FILE_SEGMENT_ELEMENT определяется следующим образом:
typedef union _FILE_SEGMENT_ELEMENT {
PVOID64 Buffer;
ULONGLONG Alignment;
}FILE_SEGMENT_ELEMENT, *PFILE_SEGMENT_ELEMENT;
При назначении указателя на элемент Buffer значение будет расширяться, если код компилируется как 32-разрядный; это может нарушить работу приложений с поддержкой больших адресов, работающих в системах, настроенных с 4-гигабайтной настройкой или работающих под управлением WOW64 в 64-разрядной версии Windows. Поэтому используйте макрос PtrToPtr64 при назначении указателей буферу.
Если часть файла, указанная hFile, заблокирована другим процессом, а операция записи перекрывает заблокированную часть, функция WriteFileGather завершается ошибкой.
В Windows 8 и Windows Server 2012 эта функция поддерживается следующими технологиями.
| Технология | Поддерживается |
|---|---|
| Протокол SMB 3.0 | Да |
| Прозрачная отработка отказа (TFO) SMB 3.0 | Да |
| SMB 3.0 с масштабируемыми общими папками (SO) | Да |
| Файловая система общего тома кластера (CSVFS) | Да |
| Восстанавливаемая файловая система (ReFS) | Да |
Транзакция операций
Если к дескриптору файла привязана транзакция, транзакция выполняется.Требования
| Минимальная версия клиента | Windows XP [только классические приложения] |
| Минимальная версия сервера | Windows Server 2003 [только классические приложения] |
| Целевая платформа | Windows |
| Header | fileapi.h (включая Windows.h) |
| Библиотека | Kernel32.lib |
| DLL | Kernel32.dll |