Ескертпе
Бұл бетке кіру үшін қатынас шегін айқындау қажет. Жүйеге кіруді немесе каталогтарды өзгертуді байқап көруге болады.
Бұл бетке кіру үшін қатынас шегін айқындау қажет. Каталогтарды өзгертуді байқап көруге болады.
Извлекает данные из массива буферов и записывает данные в файл.
Функция начинает запись данных в файл в позиции, указанной структурой 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 |