ReadFileScatter-Funktion (fileapi.h)
Liest Daten aus einer Datei und speichert sie in einem Array von Puffern.
Die Funktion beginnt mit dem Lesen von Daten aus der Datei an einer Position, die durch eine OVERLAPPED-Struktur angegeben wird. Die ReadFileScatter-Funktion arbeitet asynchron.
Syntax
BOOL ReadFileScatter(
[in] HANDLE hFile,
[in] FILE_SEGMENT_ELEMENT [] aSegmentArray,
[in] DWORD nNumberOfBytesToRead,
LPDWORD lpReserved,
[in, out] LPOVERLAPPED lpOverlapped
);
Parameter
[in] hFile
Ein Handle für die zu lesende Datei.
Das Dateihandle muss mit der rechten GENERIC_READ und den flags FILE_FLAG_OVERLAPPED und FILE_FLAG_NO_BUFFERING erstellt werden. Weitere Informationen finden Sie unter Dateisicherheit und Zugriffsrechte.
[in] aSegmentArray
Ein Zeiger auf ein Array von FILE_SEGMENT_ELEMENT Strukturpuffern , das die Daten empfängt. Eine Beschreibung dieser Vereinigung finden Sie unter Hinweise.
Jedes Element stellt eine Datenseite dar.
Hinweis
Verwenden Sie GetSystemInfo, um die Größe einer Systemseite zu bestimmen.
Das Array muss genügend Elemente enthalten, um nNumberOfBytesToRead-Bytes von Daten darzustellen. Wenn beispielsweise 40 KB gelesen werden können und die Seitengröße 4 KB beträgt, muss das Array über 10 Elemente verfügen.
Jeder Puffer muss mindestens die Größe einer Systemspeicherseite aufweisen und an einer Seitengröße des Systemspeichers ausgerichtet sein. Das System liest eine Systemspeicherseite mit Daten in jeden Puffer ein.
Die Funktion speichert die Daten in den Puffern in sequenzieller Reihenfolge. Sie speichert beispielsweise Daten im ersten Puffer, dann im zweiten Puffer usw., bis jeder Puffer gefüllt ist und alle Daten gespeichert sind, oder bis nNumberOfBytesToRead-Bytes gelesen wurden.
[in] nNumberOfBytesToRead
Die Gesamtanzahl der Bytes, die aus der Datei gelesen werden sollen. Jedes Element von aSegmentArray enthält einen Einseitenblock dieser Summe. Da die Datei mit FILE_FLAG_NO_BUFFERING geöffnet werden muss, muss die Anzahl der Bytes ein Vielfaches der Sektorgröße des Dateisystems sein, in dem sich die Datei befindet.
lpReserved
Dieser Parameter ist für die zukünftige Verwendung reserviert und muss NULL sein.
[in, out] lpOverlapped
Ein Zeiger auf eine ÜBERLAPPENDE Datenstruktur.
Die ReadFileScatter-Funktion erfordert eine gültige OVERLAPPED-Struktur . Der lpOverlapped-Parameter darf nicht NULL sein.
Die ReadFileScatter-Funktion beginnt mit dem Lesen von Daten aus der Datei an einer Position, die durch die Elemente Offset und OffsetHigh der OVERLAPPED-Struktur angegeben wird.
Die ReadFileScatter-Funktion kann zurückgegeben werden, bevor der Lesevorgang abgeschlossen ist. In diesem Szenario gibt die ReadFileScatter-Funktion den Wert 0 (null) zurück, und die GetLastError-Funktion gibt den Wert ERROR_IO_PENDING zurück. Mit diesem asynchronen Vorgang von ReadFileScatter kann der aufrufende Prozess fortgesetzt werden, während der Lesevorgang abgeschlossen ist. Sie können die Funktionen GetOverlappedResult, HasOverlappedIoCompleted oder GetQueuedCompletionStatus aufrufen, um Informationen zum Abschluss des Lesevorgangs zu erhalten. Weitere Informationen finden Sie unter Synchrone und asynchrone E/A.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.
Wenn die Funktion fehlschlägt, ist der Rückgabewert 0 (null). Um erweiterte Fehlerinformationen zu erhalten, rufen Sie die GetLastError-Funktion auf.
Wenn ReadFileScatter versucht, über das Dateiende (EOF) hinaus zu lesen, gibt der Aufruf von GetOverlappedResult für diesen Vorgang FALSE und GetLastErrorERROR_HANDLE_EOF zurück.
Wenn die Funktion zurückgibt, bevor der Lesevorgang abgeschlossen ist, gibt die Funktion null (0) zurück, und GetLastError gibt ERROR_IO_PENDING zurück.
Hinweise
Diese Funktion wird für 32-Bit-Anwendungen von WOW64 auf Itanium-basierten Systemen nicht unterstützt.
Die FILE_SEGMENT_ELEMENT-Struktur ist wie folgt definiert:
typedef union _FILE_SEGMENT_ELEMENT {
PVOID64 Buffer;
ULONGLONG Alignment;
}FILE_SEGMENT_ELEMENT, *PFILE_SEGMENT_ELEMENT;
Durch Zuweisen eines Zeigers auf den Puffermember wird der Wert signiert und erweitert, wenn der Code als 32-Bits kompiliert wird. Dies kann Anwendungen mit großem Adressbewusstsein unterbrechen, die auf Systemen ausgeführt werden, die mit einer 4-Gigabyte-Optimierung konfiguriert sind oder unter WOW64 unter 64-Bit-Windows ausgeführt werden. Verwenden Sie daher das PtrToPtr64-Makro beim Zuweisen von Zeigern zum Puffer.
Unter Windows 8 und Windows Server 2012 wird diese Funktion von den folgenden Technologien unterstützt.
| Technologie | Unterstützt |
|---|---|
| SMB 3.0-Protokoll (Server Message Block) | Ja |
| SMB 3.0 Transparent Failover (TFO) | Ja |
| SMB 3.0 mit Dateifreigaben mit horizontaler Skalierung (SO) | Ja |
| Dateisystem mit freigegebenen Clustervolumes (CsvFS) | Ja |
| Robustes Dateisystem (Resilient File System, ReFS) | Ja |
Transaktionen
Ist an das Dateihandle eine Transaktion gebunden, gibt die Funktion Daten aus der transaktiven Dateiansicht zurück. Ein transaktives Lesehandle zeigt für die Dauer des Handles garantiert die gleiche Dateiansicht an.Anforderungen
| Unterstützte Mindestversion (Client) | Windows XP [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | fileapi.h (Einschließen von Windows.h) |
| Bibliothek | Kernel32.lib |
| DLL | Kernel32.dll |