SetFilePointerEx

Declare Function Api_SetFilePointerEx& Lib "kernel32" Alias "SetFilePointerEx" (ByVal hFile&, ByVal liDistanceToMove As Large_Integer, ByRef lpNewFilePointer As Any, ByVal dwMoveMethod&)

Declare Function SetFilePointerEx Lib "kernel32" Alias "SetFilePointerEx" (ByVal hFile As Long, ByVal liDistanceToMove As Large_Integer, ByRef lpNewFilePointer As Any, ByVal dwMoveMethod As Long) As Long

開いたファイルのファイルポインタを移動する。

パラメータ
hFile
    ファイルポインタを移動するファイルのハンドルを指定する。ファイルハンドルは、ファイルへの GENERIC_READ アクセスまたは

    GENERIC_WRITE アクセスで作成されていなければならない。
liDistanceToMove
    ファイルポインタを移動するバイト数を指定する。正の値を指定すると、ポインタはファイルの前方に移動し、負の値を指定すると、後方に移

    動する。
lpNewFilePointer
    新しいファイルポインタを受け取る変数へのポインタを指定する。NULL を指定すると、新しいファイルポインタは返されない。
dwMoveMethod
    ファイルポインタの移動を開始する位置を指定する。次のいずれかの値を指定する。。

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

解説
    SetFilePointerEx 関数にパイプや通信デバイスのような、シークを行わない装置のハンドルを指定することはできない。hFile のファイルタイ

    プを判断するには、 GetFileType 関数を使う。
    マルチスレッドアプリケーションでファイルポインタを設定する場合は注意が必要である。共有リソースへのアクセスは同期させなければならな

    い。たとえば、複数のスレッドがファイルハンドルの共有、ファイルポインタの更新、ファイルの読み取りなどを実行するアプリケーションで

    は、クリティカルセクションオブジェクトやミューテックスオブジェクトを使ってこの順序を守る必要がある。
    FILE_FLAG_NO_BUFFERING フラグをセットして hFile ハンドルを開いた場合、アプリケーションはファイルポインタをセクタの境界整列位

    置にだけ移動することができる。セクタの境界整列位置は、ボリュームのセクタサイズの倍数（ 整数）である。ボリュームのセクタサイズを

    取得するには、 GetDiskFreeSpaceEx 関数を呼び出す。移動距離だけを表してセクタの境界整列を指示しない値と

    FILE_FLAG_NO_BUFFERING を使って開いたハンドルを指定して SetFilePointerEx 関数を呼び出すと、関数が失敗し、 関数から

    ERROR_INVALID_PARAMETER が返る。
    ファイルポインタをファイルの終端よりも後ろに設定してもエラーにならないので注意が必要である。 SetEndOfFile、 WriteFile、または

    WriteFileEx 関数を呼び出すまでファイルサイズは増えない。書き込み操作を実行すると、ファイルサイズは、書き込まれたバッファのサイ

    ズをファイルポインタの位置に足したサイズに増加する。このとき、間にあるバイトは初期化されない。
    SetFilePointerEx 関数では、ファイルの長さを確認することができる。この場合、dwMoveMethod パラメータに FILE_END を指定し、位

    置 0 を検索する。その結果返されるファイルオフセットがファイルの長さになる。ただし、この操作を実行すると、予期しない結果が発生する

    ことがある。たとえば、プログラムを現在のファイルポインタの場所に戻すために必要な、現在のファイルポインタの保存に失敗することがあ

    る。そのため、ファイルの長さを確認するには GetFileSizeEx 関数を使った方が簡単で安全である。
    また、SetFilePointerEx 関数は、現在のファイルポインタの位置を照会することもできる。この場合、移動方法として FILE_CURRENT

    を、移動距離として 0 を指定する。