Функция WriteFileGather (fileapi.h)

Статья
08/23/2023

Извлекает данные из массива буферов и записывает данные в файл.

Функция начинает запись данных в файл в позиции, указанной структурой 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.

При назначении указателя на элемент 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