MoveFileTransactedA 関数 (winbase.h)

  • [アーティクル]

[Microsoft では、開発者がアプリケーションのニーズを達成するために代替手段を利用することを強くお勧めします。 TxF が開発された多くのシナリオは、よりシンプルで利用しやすい手法で実現できます。 また、将来のバージョンの Microsoft Windows では TxF を使用できない場合があります。 詳細、および TxF の代替手段については、「トランザクション NTFS の使用の代替手段」を参照してください。]

トランザクション操作として、既存のファイルまたはディレクトリ (その子を含む) を移動します。

構文

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

パラメーター

[in] lpExistingFileName

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

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

ヒント

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

[in, optional] lpNewFileName

ファイルまたはディレクトリの新しい名前。 新しい名前が存在してはいけません。 新しいファイルは、別のファイル システムまたはドライブ上に配置できますが、 新しいディレクトリは同じドライブ上に配置する必要があります。

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

ヒント

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

[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_REPLACE_EXISTING
1 (0x1)
 lpNewFileName という名前のファイルが存在する場合、関数はその内容を lpExistingFileName ファイルの内容に置き換えます。

lpNewFileName または lpExistingFileName がディレクトリの名前を付ける場合、この値は使用できません。
MOVEFILE_WRITE_THROUGH
8 (0x8)
 MoveFileTransacted の呼び出しは、コミット操作が完了したときにファイルの移動操作が完了することを意味します。 このフラグは不要です。このフラグを指定した場合、操作の速度低下以外に悪影響はありません。 関数は、ファイルが実際にディスク上に移動されるまで戻りません。

この値を設定すると、コピーおよび削除操作として実行された移動が、関数が返される前にディスクにフラッシュされます。 フラッシュはコピー操作の最後に行われます。

MOVEFILE_DELAY_UNTIL_REBOOTが設定されている場合、この値は無効です。

[in] hTransaction

トランザクションへのハンドル。 このハンドルは、 CreateTransaction 関数によって返されます。

戻り値

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

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

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

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

注釈

dwFlags パラメーターでMOVEFILE_DELAY_UNTIL_REBOOTが指定されている場合、レジストリにアクセスできない場合、MoveFileTransacted は失敗します。 関数は、再起動時に名前を変更するファイルの場所を、次のレジストリ値にトランザクションによって格納します。system\CurrentControlSet\コントロール\セッション マネージャー\PendingFileRenameOperationsHKEY_LOCAL_MACHINE\

このレジストリ値は 、REG_MULTI_SZ型です。 各名前変更操作には、名前の変更が削除かどうかに応じて、次の NULL で終わる文字列のいずれかが格納されます。

szDstFile\0\0

szSrcFile\0szDstFile\0

文字列 szDstFile\0\0 は、再起動時にファイル szDstFile が削除されることを示します。

文字列 szSrcFile\0szDstFile\0 は、再起動時に szSrcFile の名前を szDstFile に変更することを示します。

メモ \0\0 は技術的には REG_MULTI_SZ ノードでは許可されていませんが、ファイルの名前が null 名に変更されていると見なされるため、可能です。
 
システムは、これらのレジストリ エントリを使用して、再起動時に、発行されたのと同じ順序で操作を完了します。 MOVEFILE_DELAY_UNTIL_REBOOT フラグの使用方法の詳細については、「MoveFileWithProgress」を参照してください。

ファイルがボリューム間で移動された場合、 MoveFileTransacted はファイルを含むセキュリティ記述子を移動しません。 ファイルには、宛先ディレクトリの既定のセキュリティ記述子が割り当てられます。

MOVEFILE_FAIL_IF_NOT_TRACKABLE フラグを指定すると、この関数は常 に 失敗します。追跡は TxF ではサポートされていません。

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

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

SMB 3.0 は TxF をサポートしていません。

要件

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

関連項目

CopyFileTransacted

File Management 関数

MoveFileWithProgress

トランザクション NTFS