次の方法で共有


CopyFileExA 関数 (winbase.h)

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

この操作をトランザクション操作として実行するには、 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

新しいファイルの名前。

既定では、名前は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_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
コピーが失敗した場合、コピーの進行状況はターゲット ファイルで追跡されます。 失敗したコピーは、失敗した呼び出しで使用されたものと同じ値を lpExistingFileNamelpNewFileName に指定することで、後で再開できます。 コピー操作中に新しいファイルが複数回フラッシュされる可能性があるため、コピー操作の速度が大幅に低下する可能性があります。
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 を呼び出します。

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

ユーザーが操作を停止したために lpProgressRoutinePROGRESS_STOP を返した場合、 CopyFileEx は 0 を返し、 GetLastErrorERROR_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 を使用してコピーされると、関数はソース ファイルの暗号化に使用されるキーを使用して、コピー先ファイルの暗号化を試みます。 これができない場合、この関数は既定のキーを使用して宛先ファイルの暗号化を試みます。 これらの両方のメソッドを実行できない場合、 CopyFileExERROR_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

関連項目

CopyFile

CopyFileTransacted

CopyProgressRoutine

CreateFile

ファイル属性定数

File Management 関数

MoveFile

MoveFileWithProgress

シンボリック リンク

TransmitFile