CopyFileExA 関数 (winbase.h)

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

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

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

構文

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

パラメーター

[in] lpExistingFileName

既存のファイルの名前。

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

ヒント

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

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

[in] lpNewFileName

新しいファイルの名前。

ヒント

[in, optional] lpProgressRoutine

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

[in, optional] lpData

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

[in, optional] pbCancel

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

[in] dwCopyFlags

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

値	意味
COPY_FILE_ALLOW_DECRYPTED_DESTINATION 0x00000008	暗号化されたファイルをコピーしようとすると、コピー先のコピーを暗号化できない場合でも成功します。
COPY_FILE_COPY_SYMLINK 0x00000800	ソース・ファイルがシンボリック・リンクの場合、宛先ファイルは、ソース・シンボリック・リンクが指しているのと同じファイルを指すシンボリック・リンクでもあります。 Windows Server 2003 および Windows XP: この値はサポートされていません。
COPY_FILE_FAIL_IF_EXISTS 0x00000001	ターゲットファイルが既に存在する場合、コピー操作はすぐに失敗します。
COPY_FILE_NO_BUFFERING 0x00001000	コピー操作は、バッファーなしの I/O を使用して実行され、システム I/O キャッシュリソースをバイパスします。非常に大きなファイル転送に推奨されます。 Windows Server 2003 および Windows XP: この値はサポートされていません。
COPY_FILE_OPEN_SOURCE_FOR_WRITE 0x00000004	ファイルがコピーされ、元のファイルが書き込みアクセス用に開かれます。
COPY_FILE_RESTARTABLE 0x00000002	コピーが失敗した場合、コピーの進行状況はターゲットファイルで追跡されます。失敗したコピーは、失敗した呼び出しで使用されたものと同じ値を lpExistingFileName と lpNewFileName に指定することで、後で再開できます。コピー操作中に新しいファイルが複数回フラッシュされる可能性があるため、コピー操作の速度が大幅に低下する可能性があります。
COPY_FILE_REQUEST_COMPRESSED_TRAFFIC 0x10000000	コピー操作中に、基になる転送チャネルにデータの圧縮を要求します。要求は、すべてのメディアでサポートされていない場合がありますが、その場合は無視されます。圧縮属性とパラメーター (計算の複雑さ、メモリ使用量) は、この API を介して構成することはできません。また、異なる OS リリース間で変更される可能性があります。このフラグは、Windows 10 バージョン 1903 および Windows Server 2022 で導入されました。 Windows 10では、SMB 共有に存在するファイルに対してフラグがサポートされます。この場合、ネゴシエートされた SMB プロトコルのバージョンは SMB v3.1.1 以降です。

戻り値

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

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

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

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

注釈

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

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

既存のファイルのセキュリティリソースプロパティ (ATTRIBUTE_SECURITY_INFORMATION) が新しいファイルにコピーされます。

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

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

暗号化されたファイルが CopyFileEx を使用してコピーされると、関数はソースファイルの暗号化に使用されるキーを使用して、コピー先ファイルの暗号化を試みます。これができない場合、この関数は既定のキーを使用して宛先ファイルの暗号化を試みます。これらの両方のメソッドを実行できない場合、 CopyFileEx は ERROR_ENCRYPTION_FAILED エラーコードで失敗します。コピー先ファイルを暗号化できない場合でも CopyFileEx でコピー操作を完了させる場合は、copyFileEx の呼び出しに dwCopyFlags パラメーターの値としてCOPY_FILE_ALLOW_DECRYPTED_DESTINATIONを含めます。

COPY_FILE_COPY_SYMLINKを指定した場合は、次の規則が適用されます。

ソースファイルがシンボリックリンクである場合、ターゲットファイルではなく、シンボリックリンクがコピーされます。
ソースファイルがシンボリックリンクではない場合、動作は変わりません。
コピー先ファイルが既存のシンボリックリンクである場合、ターゲットファイルではなく、シンボリックリンクが上書きされます。
COPY_FILE_FAIL_IF_EXISTS も指定され、コピー先ファイルが既存のシンボリックリンクである場合、操作は常に失敗します。

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

COPY_FILE_FAIL_IF_EXISTS も指定され、コピー先ファイルが既存のシンボリックリンクである場合、シンボリックリンクのターゲットが存在する場合にのみ、操作は失敗します。
COPY_FILE_FAIL_IF_EXISTS が指定されていない場合、動作は変わりません。

Windows 7、Windows Server 2008 R2、Windows Server 2008、Windows Vista、Windows Server 2003、Windows XP: LAN 全体でファイルコピー操作を最適化するアプリケーションを作成する場合は、Windows ソケット (Winsock) の TransmitFile 関数の使用を検討してください。 TransmitFile は 、高パフォーマンスのネットワーク転送をサポートし、ファイルの内容をリモートコンピューターに送信するための簡単なインターフェイスを提供します。 TransmitFile を使用するには、ソースコンピューターからファイルを送信する Winsock クライアントアプリケーションと、他の Winsock 関数を使用してリモートコンピューター上のファイルを受信する Winsock サーバーアプリケーションを記述する必要があります。

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

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

注意

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

要件

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

CopyFileExA 関数 (winbase.h)

構文

パラメーター

戻り値

注釈

要件

関連項目

フィードバック

フィードバック

その他のリソース