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 文字のワイド文字に拡張するには、パスの先頭に "\\?\" を付加します。 詳細については、「ファイル、パス、および名前空間の名前付け」を参照してください。

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

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

[in] lpNewFileName

新しいファイルの名前。

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

[in, optional] lpProgressRoutine

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

[in, optional] lpData

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

[in, optional] pbCancel

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

[in] dwCopyFlags

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

[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_FAIL_IF_EXISTSも指定され、宛先ファイルが既存のシンボリック リンクである場合、シンボリック リンクのターゲットが存在する場合にのみ操作は失敗します。
• COPY_FILE_FAIL_IF_EXISTSが指定されていない場合、動作に変更はありません。

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

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

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

要件

関連項目

CopyProgressRoutine

CreateFileTransacted

ファイル属性定数

ファイル管理機能

MoveFileTransacted

シンボリック リンク

トランザクション NTFS