ReadFileScatter-Funktion (fileapi.h)

Artikel
01/10/2024

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