WriteFileGather-Funktion (fileapi.h)

Artikel
01/10/2024

Ruft Daten aus einem Array von Puffern ab und schreibt die Daten in eine Datei.

Die Funktion beginnt mit dem Schreiben von Daten in die Datei an einer Position, die durch eine OVERLAPPED-Struktur angegeben wird. Die WriteFileGather-Funktion wird asynchron ausgeführt.

Syntax

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

Parameter

[in] hFile

Ein Handle zur Datei. Das Dateihandle muss mit dem Zugriffsrecht GENERIC_WRITE 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 , die die Daten enthalten. Eine Beschreibung dieser Vereinigung finden Sie unter Hinweise.

Jedes Element stellt eine Datenseite dar.

Hinweis

Verwenden Sie die GetSystemInfo-Funktion , um die Größe einer Systemseite zu bestimmen.

Das Array muss genügend Elemente enthalten, um nNumberOfBytesToWrite-Datenbytes darzustellen. Wenn beispielsweise 40 KB geschrieben werden sollen 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 Größengrenze des Systemspeichers ausgerichtet sein. Das System schreibt eine Systemspeicherseite mit Daten aus jedem Puffer.

Die Funktion sammelt die Daten aus den Puffern in sequenzieller Reihenfolge. Beispielsweise werden Daten aus dem ersten Puffer, dann dem zweiten Puffer usw. in die Datei geschrieben, bis nNumberOfBytesToWrite-Bytes geschrieben wurden.

Aufgrund des asynchronen Vorgangs dieser Funktion müssen Vorkehrungen getroffen werden, um sicherzustellen, dass dieser Parameter immer auf gültigen Arbeitsspeicher für die Lebensdauer der asynchronen Schreibvorgänge verweist. Für instance besteht ein häufiger Programmierfehler darin, den lokalen Stapelspeicher zu verwenden und dann zuzulassen, dass der Bereich für die Ausführung ausläuft.

[in] nNumberOfBytesToWrite

Die Gesamtanzahl der zu schreibenden Bytes. Jedes Element von aSegmentArray enthält einen einseitigen Block 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.

Wenn nNumberOfBytesToWrite null (0) ist, führt die Funktion einen NULL-Schreibvorgang aus. Das Verhalten eines NULL-Schreibvorgangs hängt vom zugrunde liegenden Dateisystem ab. Wenn nNumberOfBytesToWrite nicht null (0) ist und der Offset und die Länge der Schreibplatzdaten über das aktuelle Ende der Datei hinausgehen, erweitert die WriteFileGather-Funktion die Datei.

lpReserved

Dieser Parameter ist für die zukünftige Verwendung reserviert und muss NULL sein.

[in, out] lpOverlapped

Ein Zeiger auf eine OVERLAPPED-Datenstruktur .

Die WriteFileGather-Funktion erfordert eine gültige OVERLAPPED-Struktur . Der lpOverlapped-Parameter darf nicht NULL sein.

Die WriteFileGather-Funktion beginnt mit dem Schreiben von Daten in die Datei an einer Position, die durch die Offset - und OffsetHigh-Elemente der OVERLAPPED-Struktur angegeben wird.

Die WriteFileGather-Funktion gibt möglicherweise zurück, bevor der Schreibvorgang abgeschlossen ist. In diesem Szenario gibt die WriteFileGather-Funktion den Wert null (0) zurück, und die GetLastError-Funktion gibt den Wert ERROR_IO_PENDING zurück. Mit diesem asynchronen Vorgang der WriteFileGather-Funktion wird der aufrufende Prozess fortgesetzt, während der Schreibvorgang abgeschlossen ist.

Sie können die Funktionen GetOverlappedResult, HasOverlappedIoCompleted oder GetQueuedCompletionStatus aufrufen, um Informationen zum Abschluss des Schreibvorgangs 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 die Funktion zurückgibt, bevor der Schreibvorgang abgeschlossen ist, gibt die Funktion null (0) zurück, und die GetLastError-Funktion gibt ERROR_IO_PENDING zurück.

Hinweise

Diese Funktion wird für 32-Bit-Anwendungen von WOW64 auf itaniumbasierten 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;

Wenn Sie dem Buffer-Member einen Zeiger zuweisen, 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 4-Gigabyte-Optimierung konfiguriert sind oder unter WOW64 unter 64-Bit-Windows ausgeführt werden. Verwenden Sie daher das PtrToPtr64-Makro , wenn Sie dem Puffer Zeiger zuweisen.

Wenn ein Teil der durch hFile angegebenen Datei von einem anderen Prozess gesperrt wird und der Schreibvorgang den gesperrten Teil überlappt, schlägt die WriteFileGather-Funktion fehl.

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

Transaktionierte Vorgänge

Wenn eine Transaktion an das Dateihandle gebunden ist, wird der Vorgang ausgeführt.

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