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

Статья
01/10/2024

Считывает данные из файла и сохраняет их в массиве буферов.

Функция начинает считывание данных из файла в позиции, заданной структурой OVERLAPPED . Функция ReadFileScatter работает асинхронно.

Синтаксис

BOOL ReadFileScatter(
  [in]      HANDLE                  hFile,
  [in]      FILE_SEGMENT_ELEMENT [] aSegmentArray,
  [in]      DWORD                   nNumberOfBytesToRead,
            LPDWORD                 lpReserved,
  [in, out] LPOVERLAPPED            lpOverlapped
);

Параметры

[in] hFile

Дескриптор для считываемого файла.

Дескриптор файла должен быть создан с правой GENERIC_READ , а также флагами FILE_FLAG_OVERLAPPED и FILE_FLAG_NO_BUFFERING . Дополнительные сведения см. в разделе Безопасность файлов и права доступа.

[in] aSegmentArray

Указатель на массив FILE_SEGMENT_ELEMENT буферов структуры , получающих данные. Описание этого объединения см. в разделе Примечания.

Каждый элемент представляет одну страницу данных.

Примечание

Чтобы определить размер системной страницы, используйте GetSystemInfo.

Массив должен содержать достаточно элементов для представления байтов данных nNumberOfBytesToRead . Например, если требуется считывать 40 КБ, а размер страницы равен 4 КБ, массив должен содержать 10 элементов.

Каждый буфер должен быть не ниже размера страницы системной памяти и должен быть выровнен по границе размера страницы системной памяти. Система считывает одну страницу данных системной памяти в каждый буфер.

Функция хранит данные в буферах в последовательном порядке. Например, данные хранятся в первом буфере, затем во втором и т. д. до тех пор, пока не будет заполнен каждый буфер и все данные не будут сохранены, или пока не будут прочитаны байты nNumberOfBytesToRead .

[in] nNumberOfBytesToRead

Общее количество байтов, считываемых из файла. Каждый элемент объекта ASegmentArray содержит одностраничный блок из этого итогового значения. Так как файл должен быть открыт с FILE_FLAG_NO_BUFFERING, количество байтов должно быть кратно размеру сектора файловой системы, в которой находится файл.

lpReserved

Этот параметр зарезервирован для использования в будущем и должен иметь значение NULL.

[in, out] lpOverlapped

Указатель на структуру данных OVERLAPPED .

Для функции ReadFileScatter требуется допустимая структура OVERLAPPED . Параметр lpOverlapped не может иметь значение NULL.

Функция ReadFileScatter начинает считывание данных из файла в позиции, указанной элементами Offset и OffsetHigh структуры OVERLAPPED .

Функция ReadFileScatter может вернуться до завершения операции чтения. В этом сценарии функция ReadFileScatter возвращает значение 0 (ноль), а функция GetLastError возвращает значение ERROR_IO_PENDING. Эта асинхронная операция ReadFileScatter позволяет продолжить вызывающий процесс, пока операция чтения завершается. Для получения сведений о завершении операции чтения можно вызвать функции GetOverlappedResult, HasOverlappedIoCompleted или GetQueuedCompletionStatus . Дополнительные сведения см. в разделе Синхронный и асинхронный ввод-вывод.

Возвращаемое значение

Если функция выполняется успешно, возвращается ненулевое значение.

Если функция завершается сбоем, возвращаемое значение равно нулю (0). Чтобы получить расширенные сведения об ошибке, вызовите функцию GetLastError .

Если ReadFileScatter пытается выполнить чтение после окончания файла (EOF), вызов Метода GetOverlappedResult для этой операции возвращает значение FALSE , а GetLastError возвращает ERROR_HANDLE_EOF.

Если функция возвращается до завершения операции чтения, функция возвращает ноль (0), а GetLastError возвращает ERROR_IO_PENDING.

При назначении указателя на элемент Buffer значение будет расширяться, если код компилируется как 32-разрядный; это может нарушить работу приложений с поддержкой больших адресов, работающих в системах, настроенных с настройкой 4 Гигабайт или работающих в WOW64 в 64-разрядной версии Windows. Поэтому используйте макрос PtrToPtr64 при назначении указателей буферу.

В 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