WriteFileEx

指定したファイルや I/O デバイスにデータを書き込む。完了状態を非同期に報告し、書き込みが完了またはキャンセルされ呼び出し側スレッドが警告可能待機状態に入ったときに、指定の完了ルーチンを呼び出す。

WriteFileEx hFile, lpBuffer, nNumberOfBytesToWrite, lpOverlapped, lpCompletionRoutine

hFile : [intptr] ファイルや I/O デバイス (ファイル、ファイルストリーム、物理ディスク、ボリューム、コンソールバッファ、テープドライブ、ソケット、通信リソース、メールスロット、パイプなど) のハンドル。本パラメータには CreateFile 関数で **FILE_FLAG_OVERLAPPED** フラグを付けて開いた任意のハンドル、または socket / accept 関数が返したソケットハンドルを指定できる。このハンドルに I/O 完了ポートを関連付けてはならない。詳細は備考を参照。本ハンドルは **GENERIC_WRITE** アクセス権も持たなければならない。
lpBuffer : [var] ファイルやデバイスに書き込むデータを含むバッファへのポインタ。本バッファは書き込み操作の間有効である必要がある。呼び出し側は書き込み完了までこのバッファを使ってはならない。
nNumberOfBytesToWrite : [int] ファイルやデバイスに書き込むバイト数。0 を指定すると null 書き込み操作となる。null 書き込みの動作は基になるファイルシステムに依存する。ネットワーク越しのパイプ書き込みは 1 回 65,535 バイトに制限される。
lpOverlapped : [var] オーバーラップ (非同期) 書き込み中に使うデータを供給する OVERLAPPED 構造体へのポインタ。バイトオフセットをサポートするファイルでは、書き込み開始バイトオフセットを指定する必要がある。これは OVERLAPPED 構造体の **Offset** と **OffsetHigh** メンバで指定する。バイトオフセットをサポートしないファイル/デバイスでは無視される。EOF に書き込むには両方を `0xFFFFFFFF` にする。これは CreateFile を **FILE_APPEND_DATA** で開くことと機能的に同等である。**WriteFileEx** は OVERLAPPED 構造体の **hEvent** メンバを無視し、アプリケーションは自由にこのメンバを WriteFileEx 呼び出し文脈で利用できる。WriteFileEx は完了を lpCompletionRoutine の呼び出し (またはキューイング) で通知するため、イベントハンドルを必要としない。**Internal** と **InternalHigh** メンバは WriteFileEx が使用するので変更してはならない。OVERLAPPED 構造体は書き込み操作の間有効でなければならず、書き込み完了前にスコープ外になり得る変数を使ってはならない。
lpCompletionRoutine : [int] 書き込み完了時かつ呼び出し側スレッドが警告可能待機状態のときに呼ばれる完了ルーチンへのポインタ。詳細は FileIOCompletionRoutine を参照。

(プラグイン / モジュール : kernel32.dll)

解説

指定したファイルや I/O
デバイスにデータを書き込む。完了状態を非同期に報告し、書き込みが完了またはキャンセルされ呼び出し側スレッドが警告可能待機状態に入ったときに、指定の完了ルーチンを呼び出す。

[戻り値]
関数が成功した場合、戻り値は 0 以外である。関数が失敗した場合、戻り値は 0 となる。拡張エラー情報を取得するには
GetLastError を呼ぶ。**WriteFileEx** が成功した場合、呼び出し側スレッドにはオーバーラップ書き込み I/O
操作が保留中となる。この I/O 完了時かつスレッドが警告可能待機状態でブロックされている場合、OS は
_lpCompletionRoutine_ が指す関数を呼び、待機は WAIT_IO_COMPLETION
で完了する。関数が成功し書き込みが完了したが呼び出し側スレッドが警告可能待機状態でない場合、システムは
_lpCompletionRoutine_ への呼び出しをキューイングし、スレッドが警告可能待機状態に入るまで保持する。

[備考]
**WriteFileEx** を使う際は、関数が "成功" を返した場合でも GetLastError
を確認するべきである。たとえばバッファオーバーフローでは TRUE が返るが GetLastError は ERROR_MORE_DATA
を返す。成功で警告条件もない場合、GetLastError は ERROR_SUCCESS を返す。**WriteFileEx** は
_hFile_ が I/O 完了ポートに関連付けられている場合は失敗する。この種のハンドルでは WriteFile
を使うこと。**WriteFileEx** は未完了の非同期 I/O 要求が多すぎると失敗することがある。失敗時に
GetLastError は ERROR_INVALID_USER_BUFFER または ERROR_NOT_ENOUGH_MEMORY
を返す。すべての保留中非同期 I/O 操作をキャンセルするには CancelIo (呼び出し側スレッドが発行した操作のみ) または
CancelIoEx (指定ハンドルに対するすべての操作) を使う。同期 I/O のキャンセルには CancelSynchronousIo
を使う。キャンセルされた I/O 操作は ERROR_OPERATION_ABORTED で完了する。_hFile_
が示すファイルの一部が別プロセスによりロックされていて、書き込み範囲がロック領域と重なる場合、**WriteFileEx**
は失敗する。ファイル書き込み時、ファイルへの書き込みに使われたすべてのハンドルが閉じられるまでは最終書き込み時刻が完全には更新されない。よって正確な最終書き込み時刻を得るためには書き込み直後にファイルハンドルを閉じる。書き込み中の出力バッファにアクセスすると書き込みデータが破損することがある。アプリケーションは書き込み完了まで出力バッファに書いたり再割り当てしたり解放してはならない。リモートファイルではタイムスタンプが正しく更新されないことがあるため、一貫した結果のためには非バッファ
I/O を使う。システムは 0 バイトを null 書き込み操作と解釈し、WriteFile
はファイルを切り詰めも拡張もしない。切り詰めや拡張には SetEndOfFile を使う。アプリケーションは
WaitForSingleObjectEx、WaitForMultipleObjectsEx、MsgWaitForMultipleObjectsEx、SignalObjectAndWait、SleepEx
で警告可能待機状態に入る。マウントされたファイルシステムを持つボリュームに直接書き込む場合、まずボリュームに排他アクセスを取得しなければならない。さもなければデータ破損やシステム不安定の原因となる。これらの問題を防ぐため、Windows
Vista 以降では次の変更がある。-
マウントファイルシステムがないボリュームのハンドル書き込みは成功する。次の条件のいずれかが真なら成功する:
ブートセクタへの書き込み、ファイルシステム空間外のセクタへの書き込み、FSCTL_LOCK_VOLUME /
FSCTL_DISMOUNT_VOLUME で明示的にロック・ディスマウント済み、ボリュームに実際のファイルシステムがない (RAW
がマウント)。- ディスクハンドル書き込みは次の条件のいずれかが真なら成功する:
書き込みセクタがボリュームエクステント外、書き込みセクタがマウントボリューム内だが明示的にロック・ディスマウント済み、書き込みセクタが
RAW 以外のマウントファイルシステムを持たないボリューム内。CreateFile で
**FILE_FLAG_NO_BUFFERING** で開いたファイルとの作業には厳格な要件がある。詳細は File Buffering
を参照。Windows 8 と Windows Server 2012 では本関数は SMB 3.0 / TFO / SO / CsvFS
/ ReFS でサポートされる。

情報