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