Функция ReadFileScatter (fileapi.h)
Считывает данные из файла и сохраняет их в массиве буферов.
Функция начинает считывание данных из файла в позиции, заданной структурой 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.
Комментарии
Эта функция не поддерживается для 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 при назначении указателей буферу.
В 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 |