CopyFileTransactedA 関数 (winbase.h)

  • [アーティクル]

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

トランザクション操作として既存のファイルを新しいファイルにコピーし、コールバック関数を介してその進行状況をアプリケーションに通知します。

構文

BOOL CopyFileTransactedA(
  [in]           LPCSTR             lpExistingFileName,
  [in]           LPCSTR             lpNewFileName,
  [in, optional] LPPROGRESS_ROUTINE lpProgressRoutine,
  [in, optional] LPVOID             lpData,
  [in, optional] LPBOOL             pbCancel,
  [in]           DWORD              dwCopyFlags,
  [in]           HANDLE             hTransaction
);

パラメーター

[in] lpExistingFileName

既存のファイルの名前。

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

ヒント

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

lpExistingFileName が存在しない場合、CopyFileTransacted 関数は失敗し、GetLastError 関数はERROR_FILE_NOT_FOUNDを返します。

ファイルはローカル コンピューター上に存在する必要があります。それ以外の場合、関数は失敗し、最後のエラー コードは ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE に設定されます。

[in] lpNewFileName

新しいファイルの名前。

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

ヒント

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

[in, optional] lpProgressRoutine

ファイルの別の部分がコピーされるたびに呼び出される LPPROGRESS_ROUTINE 型のコールバック関数のアドレス。 このパラメーターは、NULL でもかまいません。 進行状況コールバック関数の詳細については、 CopyProgressRoutine 関数を参照してください。

[in, optional] lpData

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

[in, optional] pbCancel

コピー操作中にこのフラグが TRUE に設定されている場合、操作は取り消されます。 それ以外の場合、コピー操作は完了し続けます。

[in] dwCopyFlags

ファイルのコピー方法を指定するフラグ。 このパラメーターは、次の値と組み合わせて使用できます。

値 説明
COPY_FILE_COPY_SYMLINK
0x00000800
 ソース・ファイルがシンボリック・リンクの場合、宛先ファイルは、ソース・シンボリック・リンクが指すのと同じファイルを指すシンボリック・リンクでもあります。
COPY_FILE_FAIL_IF_EXISTS
0x00000001
 ターゲット ファイルが既に存在する場合、コピー操作はすぐに失敗します。
COPY_FILE_OPEN_SOURCE_FOR_WRITE
0x00000004
 ファイルがコピーされ、元のファイルが書き込みアクセス用に開かれます。
COPY_FILE_RESTARTABLE
0x00000002
 コピーが失敗した場合、コピーの進行状況はターゲット ファイルで追跡されます。 失敗したコピーは、失敗した呼び出しで使用されるものと同じ値を lpExistingFileName と lpNewFileName に指定することで、後で再起動できます。 コピー操作中に新しいファイルが複数回フラッシュされる可能性があるため、コピー操作の速度が大幅に低下する可能性があります。

[in] hTransaction

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

戻り値

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

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

ユーザーが操作をキャンセルしたために lpProgressRoutine が PROGRESS_CANCEL を返した場合、 CopyFileTransacted は 0 を返し、 GetLastError は ERROR_REQUEST_ABORTEDを返します。 この場合、部分的にコピーされたコピー先ファイルが削除されます。

ユーザーが操作を停止したために lpProgressRoutine が PROGRESS_STOP を返した場合、 CopyFileTransacted は 0 を返し、 GetLastError は ERROR_REQUEST_ABORTEDを返します。 この場合、部分的にコピーされたコピー先ファイルはそのまま残ります。

既にロールバックされているトランザクションへのハンドルを使用してこの関数を呼び出そうとすると、 CopyFileTransacted は ERROR_TRANSACTION_NOT_ACTIVE または ERROR_INVALID_TRANSACTIONを返します。

Remarks

この関数は、拡張属性、OLE 構造化ストレージ、NTFS ファイル システム代替データ ストリーム、セキュリティ属性、およびファイル属性を保持します。

Windows 7、Windows Server 2008 R2、Windows Server 2008、Windows Vista: 既存のファイルのセキュリティ リソース属性 (ATTRIBUTE_SECURITY_INFORMATION) は、Windows 8してWindows Server 2012するまで新しいファイルにコピーされません。

変換先ファイルが既に存在し、 FILE_ATTRIBUTE_HIDDEN または FILE_ATTRIBUTE_READONLY 属性が設定されている場合、この関数は ERROR_ACCESS_DENIED で失敗します。

暗号化されたファイルは TxF ではサポートされていません。

COPY_FILE_COPY_SYMLINKが指定されている場合は、次の規則が適用されます。

  • ソース・ファイルがシンボリック・リンクの場合は、ターゲット・ファイルではなくシンボリック・リンクがコピーされます。
  • ソース ファイルがシンボリック リンクでない場合、動作に変更はありません。
  • 宛先ファイルが既存のシンボリック・リンクの場合は、ターゲット・ファイルではなくシンボリック・リンクが上書きされます。
  • COPY_FILE_FAIL_IF_EXISTSも指定され、宛先ファイルが既存のシンボリック リンクである場合、操作は失敗します。
COPY_FILE_COPY_SYMLINKが指定されていない場合は、次の規則が適用されます。
  • COPY_FILE_FAIL_IF_EXISTSも指定され、宛先ファイルが既存のシンボリック リンクである場合、シンボリック リンクのターゲットが存在する場合にのみ操作は失敗します。
  • COPY_FILE_FAIL_IF_EXISTSが指定されていない場合、動作に変更はありません。

リンク追跡は TxF ではサポートされていません。

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

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

SMB 3.0 では TxF がサポートされないことに注意してください。

注意

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

要件

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

関連項目

CopyProgressRoutine

CreateFileTransacted

ファイル属性定数

ファイル管理機能

MoveFileTransacted

シンボリック リンク

トランザクション NTFS