WriteFile

Declare Function Api_WriteFile& Lib "kernel32" Alias "WriteFile" (ByVal hFile&, lpBuffer As Any, ByVal nNumberOfBytesToWrite&, lpNumberOfBytesWritten&, lpOverlapped As Any)

Declare Function WriteFile Lib "kernel32" Alias "WriteFile" (ByVal hFile As Long, lpBuffer As Any, ByVal nNumberOfBytesToWrite As Long, lpNumberOfBytesWritten As Long, lpOverlapped As OVERLAPPED) As Long

ファイルにデータを書き込む。この関数は、同期と非同期両方の操作を想定して設計されている。

パラメータ
hFile
    書き込み対象のファイルのハンドルを指定する。

    このハンドルは、GENERIC_WRITE アクセス権を指定して作成したものでなければならない。
    Windows NT/2000：非同期の書き込み操作を行う場合、FILE_FLAG_OVERLAPPED フラグを指定し CreateFile 関数を呼び出して開

    いた任意のハンドル、または socket と accept どちらかの関数が返したソケットのハンドルを指定する。
    Windows 95/98：非同期の書き込み操作を行う場合、FILE_FLAG_OVERLAPPED フラグを指定し CreateFile 関数を呼び出して開いた

    通信リソース、または socket と accept どちらかの関数が返したソケットのハンドルを指定する。メールスロット、名前付きパイプ、ディスクフ

    ァイルに対する非同期書き込み操作はサポートしていない。
lpBuffer
    ファイルに書き込むべきデータを保持しているバッファへのポインタを指定する。
nNumberOfBytesToWrite
    ファイルに書き込むべきバイト数を指定する。
    このパラメータで 0 を指定すると、NULL 書き込み操作と解釈される。NULL 書き込み操作は、ファイルに何も書き込まず、タイムスタンプ

    を変更するだけである（データは変更されない）。
    ネットワーク経由の名前付きパイプへの書き込み操作では、上限は 65,535 バイトである。
lpNumberOfBytesWritten
    1 個の変数へのポインタを指定する。関数から制御が返ると、この変数に、実際に書き込まれたバイト数が格納される。

    何らかの作業やエラーのチェックを行う前に、WriteFile はこの値を 0 に設定する。
    Windows NT/2000：lpOverlapped パラメータで NULL を指定した場合、lpNumberOfBytesWritten パラメータで NULL を指定できな

    い。lpOverlapped パラメータで有効なポインタを指定した場合、lpNumberOfBytesWritten パラメータで NULL を指定できる。

    オーバーラップ書き込み操作を行う場合、GetOverlappedResult 関数を呼び出すと、書き込みの終わったバイト数を取得できる。

    hFile が I/O 完了ポートに関連付けられている場合、GetQueuedCompletionStatus 関数を呼び出すと、書き込みの終わったバイト数を取

    得できる。
    Windows 95/98：このパラメータでは NULL を指定できない。
lpOverlapped
    1 個の OVERLAPPED 構造体へのポインタを指定する。

    hFile パラメータが、FILE_FLAG_OVERLAPPED を指定して開いたファイルのハンドルを指している場合、この構造体は必須である。
    hFile パラメータが、FILE_FLAG_OVERLAPPED フラグを指定して開かれたハンドルを指している場合、lpOverlapped パラメータでは

    NULL を指定できない。このパラメータでは、1 個の有効な OVERLAPPED 構造体を指定しなければならない。もしこの状況で、

    lpOverlapped パラメータで NULL を指定すると、この関数は、書き込み操作が完了したと間違って通知することがある。
    hFile パラメータが、FILE_FLAG_OVERLAPPED フラグを指定して開かれたハンドルを指していて、lpOverlapped パラメータで有効なポイ

    ンタを指定した場合、OVERLAPPED 構造体で指定したオフセットでファイルの非同期書き込みが開始され、WriteFile はファイルの書き込

    みが完了する前に制御を返すことがある。この場合、WriteFile 関数は 0（FALSE）を返し、GetLastError 関数は

    ERROR_IO_PENDING を返す。この結果、呼び出し側プロセスは書き込み操作が完了する前に、他の作業を実行できる。

    その後、書き込み操作が完了すると、OVERLAPPED 構造体で指定したイベントがシグナル状態になる。
    hFile パラメータが、FILE_FLAG_OVERLAPPED フラグを指定せずに開かれたハンドルを指していて、lpOverlapped パラメータで NULL

    を指定した場合、ファイルポインタの現在の位置からファイルの同期書き込みが開始され、WriteFile は、書き込みが完了すると制御を返

    す。
    Windows NT/2000：hFile パラメータが、FILE_FLAG_OVERLAPPED フラグを指定せずに開かれたハンドルを指していて、

    lpOverlapped パラメータで有効なポインタを指定した場合、OVERLAPPED 構造体で指定したオフセットでファイルの同期書き込みが開始

    され、WriteFile は、書き込みが完了すると制御を返す。
    Windows 95/98：ファイル、ディスク、パイプ、メールスロットのいずれかを対象とする操作では、このパラメータで NULL を指定しなければ

    ならない。OVERLAPPED 構造体へのポインタを指定すると、この関数は失敗する。ただし、Windows 95/98 は、シリアルポートとパラレ

    ルポートに対するオーバーラップ I/O をサポートしている。

戻り値
    関数が成功すると、0 以外の値が返る。
    関数が失敗すると、0 が返る。拡張エラー情報を取得するには、GetLastError 関数を使う。