ファイルにデータを書き込みます。ファイルポインタの現在位置が、書き込みの開始位置になります。同期書き込み操作では、書き込みが終了すると、ファイルハンドルがオーバーラップ属性指定で作成されていない限り、ファイルポインタの位置は書き込んだバイト数だけ進められます。非同期書き込み操作では、アプリケーション側でファイルポインタを調整する必要があります。
BOOL WriteFile(
HANDLE hFile, // ファイルハンドル
LPCVOID pBuffer, // バッファアドレス
DWORD nNumberOfBytesToWrite, // サイズ
LPDWORD pNumberOfBytesWritten, // 実際のサイズを格納する変数
LPOVERLAPPED pOverlapped // OVERLAPPED構造体
);
KERNEL32.DLL
読み取り先のファイルのハンドルを指定します。ファイルハンドルは CreateFile 関数で取得できます。このハンドルは、 GENERIC_WRITE アクセスを持っていなければなりません。
Windows NT/2000/XP： CreateFile 関数で FILE_FLAG_OVERLAPPED フラグを指定してオープンされたあらゆる種類のハンドル、または、 socket 関数もしくは accept 関数から返されたソケットハンドルを、非同期書き込み操作で hFile パラメータに指定することができます。
Windows 95/98/Me： CreateFile 関数で FILE_FLAG_OVERLAPPED フラグを指定してオープンされたコミュニケーションリソースのハンドル、または、 socket 関数もしくは accept 関数から返されたソケットハンドルを、非同期書き込み操作で hFile パラメータに指定することができます。メールスロットや名前付きパイプ、ディスクファイルからの非同期書き込み操作を行なうことはできません。
書き込むデータが入ったバッファのアドレスを指定します。
書き込むバイト数を指定します。
0 を指定すると、 NULL の書き込み操作であると解釈され、タイムスタンプが変更されます。（データは変更されません。）
ネットワークを介した名前付きパイプへの書き込み操作では、 65535 以下を指定しなければなりません。
実際に書き込まれたバイト数を格納するための変数のアドレスを指定します。
Windows NT/2000/XP： pOverlapped パラメータに有効なアドレスを指定した場合は 0 (NULL) を指定することができます。非同期書き込み操作の場合は、 GetOverlappedResult 関数を呼び出すことで書き込まれたバイト数を取得することができます。 hFile パラメータが I/O 完了ポートと関連付けられている場合は、 GetQueuedCompletionStatus 関数を呼び出すことで書き込まれたバイト数を取得することができます。
Windows 95/98/Me： このパラメータに 0 (NULL) を指定することはできません。
有効な OVERLAPPED 構造体のアドレスまたは 0 (NULL) を指定します。
hFile パラメータのハンドルが FILE_FLAG_OVERLAPPED フラグを持たないとき、かつ、このパラメータに 0 (NULL) を指定したときは、ファイルポインタの現在位置からファイルが同期的に書き込まれます。書き込みが完了すると、制御が返ります。
hFile パラメータのハンドルが FILE_FLAG_OVERLAPPED フラグを持つとき、かつ、このパラメータで有効な OVERLAPPED 構造体のアドレスを指定したときは、 OVERLAPPED 構造体で指定されたオフセットからファイルが非同期的に書き込まれます。制御はすぐに返りますが、書き込みが完了しているとは限りません。書き込みが終了していない場合は、 WriteFile 関数は失敗し、 GetLastError 関数は 997 (ERROR_IO_PENDING) を返します。その後、書き込みが完了すると、 OVERLAPPED 構造体で指定したイベントがシグナル状態になります。
Windows NT/2000/XP： hFile パラメータのハンドルが FILE_FLAG_OVERLAPPED フラグを持たないとき、かつ、このパラメータで有効な OVERLAPPED 構造体のアドレスを指定したときは、 OVERLAPPED 構造体で指定したオフセットからファイルが同期的に書き込まれます。書き込みが完了すると、制御が返ります。
Windows 95/98/Me： ファイル、ディスク、パイプ、メールスロットへの操作を行なう場合、このパラメータは 0 (NULL) でなければなりません。 0 (NULL) 以外の値を指定すると呼び出しは失敗します。ただし、シリアルポートおよびパラレルポートの非同期入出力はサポートされます。
成功すると 0 以外の値が返ります。
失敗すると 0 が返ります。拡張エラー情報を取得するには、 GetLastError 関数を使います。
ほかのプロセスによってロックされている領域に書き込もうとすると、この関数は失敗します。
書き込み操作が終了しない限り、 pBuffer パラメータで指定されたバッファの内容を変更してはいけません。
未処理の非同期 I/O が大量に残っているとき、 WriteFile 関数が失敗して GetLastError 関数が 1784 (ERROR_INVALID_USER_BUFFER) または 8 (ERROR_NOT_ENOUGH_MEMORY) を返すことがあります。
Windows 95 以降 / Windows NT 3.1 以降