WriteFileGather-Funktion (fileapi.h)
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 |