MoveFileWithProgressA 関数 (winbase.h)

[アーティクル]
03/13/2024

ファイルまたはディレクトリ (その子を含む) を移動します。進行状況通知を受け取るコールバック関数を指定できます。

この操作をトランザクション操作として実行するには、 MoveFileTransacted 関数を使用します。

構文

BOOL MoveFileWithProgressA(
  [in]           LPCSTR             lpExistingFileName,
  [in, optional] LPCSTR             lpNewFileName,
  [in, optional] LPPROGRESS_ROUTINE lpProgressRoutine,
  [in, optional] LPVOID             lpData,
  [in]           DWORD              dwFlags
);

パラメーター

[in] lpExistingFileName

ローカルコンピューター上の既存のファイルまたはディレクトリの名前。

dwFlags でMOVEFILE_DELAY_UNTIL_REBOOTが指定されている場合、ネットワークが使用可能になる前に遅延操作が実行されるため、リモート共有にファイルを存在できません。

既定では、名前はMAX_PATH文字に制限されています。この制限を 32,767 文字のワイド文字に拡張するには、パスの先頭に "\\?\" を付加します。詳細については、「ファイル、パス、および名前空間の名前付け」を参照してください。

ヒント

Windows 10 バージョン 1607 以降では、"\\?\" を前もって指定しなくても、MAX_PATHの制限を削除するようにオプトインできます。詳細については、「名前付けファイル、パス、および名前空間」の「パスの最大長制限」セクションを参照してください。

[in, optional] lpNewFileName

ローカルコンピューター上のファイルまたはディレクトリの新しい名前。

ファイルを移動する場合、 lpNewFileName は別のファイルシステムまたはボリューム上に置くことができます。 lpNewFileName が別のドライブにある場合は、dwFlags で MOVEFILE_COPY_ALLOWED フラグを設定する必要があります。

ディレクトリを移動するときは、 lpExistingFileName と lpNewFileName が 同じドライブ上に存在する必要があります。

dwFlags がMOVEFILE_DELAY_UNTIL_REBOOTを指定し、lpNewFileName が NULL の場合、MoveFileWithProgress では、システムの再起動時に削除される lpExistingFileName が登録されます。削除操作に関する情報を格納するためにレジストリにアクセスできない場合、関数は失敗します。 lpExistingFileName がディレクトリを参照している場合、システムは、ディレクトリが空の場合にのみ、再起動時にディレクトリを削除します。

ヒント

[in, optional] lpProgressRoutine

ファイルの別の部分が移動されるたびに呼び出される CopyProgressRoutine コールバック関数へのポインター。コールバック関数は、操作の進行状況を表示するユーザーインターフェイスを提供する場合に役立ちます。このパラメーターは、NULL でもかまいません。

[in, optional] lpData

CopyProgressRoutine コールバック関数に渡される引数。このパラメーターは、NULL でもかまいません。

[in] dwFlags

移動オプション。このパラメーターには、次の 1 つ以上の値を指定できます。

値	意味
MOVEFILE_COPY_ALLOWED 2 (0x2)	ファイルを別のボリュームに移動する場合、関数は CopyFile 関数と DeleteFile 関数を使用して移動をシミュレートします。ファイルが正常に別のボリュームにコピーされ、元のファイルを削除できない場合、関数はソースファイルをそのまま残して成功します。この値は、MOVEFILE_DELAY_UNTIL_REBOOTでは使用できません。
MOVEFILE_CREATE_HARDLINK 16 (0x10)	将来利用するために予約されています。
MOVEFILE_DELAY_UNTIL_REBOOT 4 (0x4)	オペレーティングシステムが再起動されるまで、システムはファイルを移動しません。システムは、AUTOCHK が実行された直後に、ページングファイルを作成する前にファイルを移動します。そのため、このパラメーターを使用すると、関数は以前のスタートアップからページングファイルを削除できます。この値は、プロセスが管理者グループまたは LocalSystem アカウントに属するユーザーのコンテキストにある場合にのみ使用できます。この値は、MOVEFILE_COPY_ALLOWEDでは使用できません。
MOVEFILE_FAIL_IF_NOT_TRACKABLE 32 (0x20)	ソースファイルがリンクソースの場合、関数は失敗しますが、移動後にファイルを追跡することはできません。この状況は、ターゲットが FAT ファイルシステムでフォーマットされたボリュームである場合に発生する可能性があります。
MOVEFILE_REPLACE_EXISTING 1 (0x1)	lpNewFileName という名前のファイルが存在する場合、関数はその内容を lpExistingFileName ファイルの内容に置き換えます。 lpNewFileName または lpExistingFileName がディレクトリの名前を付ける場合、この値は使用できません。
MOVEFILE_WRITE_THROUGH 8 (0x8)	関数は、ファイルが実際にディスク上に移動されるまで戻りません。この値を設定すると、コピーおよび削除操作として実行された移動が、関数が返される前にディスクにフラッシュされます。フラッシュはコピー操作の最後に行われます。 MOVEFILE_DELAY_UNTIL_REBOOTが設定されている場合、この値は無効です。

戻り値

関数が成功すると、戻り値は 0 以外になります。

関数が失敗した場合は、0 を返します。詳細なエラー情報を得るには、GetLastError を呼び出します。

ボリューム間でファイルを移動するときに、ユーザーが操作をキャンセルしたため に lpProgressRoutine が PROGRESS_CANCEL を返した場合、 MoveFileWithProgress は 0 を返し、 GetLastError は ERROR_REQUEST_ABORTEDを返します。既存のファイルはそのまま残ります。

ボリューム間でファイルを移動するときに、ユーザーが操作を停止したために lpProgressRoutine が PROGRESS_STOP を返した場合、 MoveFileWithProgress は 0 を返し、 GetLastError は ERROR_REQUEST_ABORTEDを返します。既存のファイルはそのまま残ります。

注釈

MoveFileWithProgress 関数は、リンク追跡サービスと操作を調整するため、リンクソースは移動時に追跡できます。

ファイルを削除または名前変更するには、ファイルに対する削除アクセス許可を持っているか、親ディレクトリの子アクセス許可を削除する必要があります。削除と削除の子を除くすべてのアクセス権を持つディレクトリを設定し、新しいファイルの ACL が継承されている場合は、削除できないファイルを作成できます。ただし、ファイルを作成すると、ファイルの作成時に返されたハンドルに対して要求したすべてのアクセス権を取得できます。ファイルの作成時に削除アクセス許可を要求した場合は、そのハンドルを使用してファイルを削除または名前変更できますが、他のハンドルでは削除できません。

Windows 8 と Windows Server 2012 では、この関数は、次のテクノロジによってサポートされています。

テクノロジ	サポートされています
サーバーメッセージブロック (SMB) 3.0 プロトコル	はい
SMB 3.0 Transparent Failover (TFO)	はい
スケールアウトファイル共有 (SO) を使う SMB 3.0	はい
クラスターの共有ボリュームファイルシステム (CsvFS)	はい
Resilient File System (ReFS)	はい

CsvFs によって、圧縮されたファイルのリダイレクトされた IO が実行されます。

注意

winbase.h ヘッダーでは、MoveFileWithProgress をエイリアスとして定義します。このエイリアスは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイムエラーが発生する不一致が発生する可能性があります。詳細については、「関数プロトタイプの規則」を参照してください。

要件

要件	値
サポートされている最小のクライアント	Windows XP (デスクトップアプリのみ)
サポートされている最小のサーバー	Windows Server 2003 (デスクトップアプリのみ)
対象プラットフォーム	Windows
ヘッダー	winbase.h (Windows.h を含む)
Library	Kernel32.lib
[DLL]	Kernel32.dll

次の方法で共有

MoveFileWithProgressA 関数 (winbase.h)

構文

パラメーター

戻り値

注釈

要件

関連項目

フィードバック

その他のリソース