CopyFile2 関数 (winbase.h)

[アーティクル]
08/27/2023

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

構文

HRESULT CopyFile2(
  [in]           PCWSTR                        pwszExistingFileName,
  [in]           PCWSTR                        pwszNewFileName,
  [in, optional] COPYFILE2_EXTENDED_PARAMETERS *pExtendedParameters
);

パラメーター

[in] pwszExistingFileName

既存のファイルの名前。

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

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

lpExistingFileName が存在しない場合、CopyFile2 関数はを返HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)します。

[in] pwszNewFileName

新しいファイルの名前。

[in, optional] pExtendedParameters

COPYFILE2_EXTENDED_PARAMETERS構造体の省略可能なアドレス。

戻り値

関数が成功した場合、SUCCEEDED マクロに渡されると、戻り値は TRUE を返します。

リターンコード	説明
S_OK	コピー操作が正常に完了しました。
HRESULT_FROM_WIN32(ERROR_REQUEST_PAUSED)	コピー操作は、CopyFile2ProgressRoutine コールバック関数から返されるCOPYFILE2_PROGRESS_PAUSEによって一時停止されました。
HRESULT_FROM_WIN32(ERROR_REQUEST_ABORTED)	コピー操作は、COPYFILE2_PROGRESS_CANCELによって一時停止されたか、CopyFile2ProgressRoutine コールバック関数から返COPYFILE2_PROGRESS_STOP。
HRESULT_FROM_WIN32(ERROR_ALREADY_EXISTS)	pExtendedParameters パラメーターを介して渡されるCOPYFILE2_EXTENDED_PARAMETERS構造体の dwCopyFlags メンバーには、COPY_FILE_FAIL_IF_EXISTS フラグが含まれており、競合する名前が存在します。
HRESULT_FROM_WIN32(ERROR_FILE_EXISTS)	pExtendedParameters パラメーターを介して渡されるCOPYFILE2_EXTENDED_PARAMETERS構造体の dwCopyFlags メンバーには、COPY_FILE_FAIL_IF_EXISTS フラグが含まれており、競合する名前が存在します。

解説

この関数は、拡張属性、OLE 構造化ストレージ、NTFS ファイルシステム代替データストリーム、およびファイル属性を保持します。既存のファイルのセキュリティ属性は、新しいファイルにコピーされません。セキュリティ属性をコピーするには、 SHFileOperation 関数を使用します。

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

この関数を使用するアプリケーションをコンパイルするには、 _WIN32_WINNT マクロを _WIN32_WINNT_WIN8 以降として定義します。詳細については、「 Windows ヘッダーの使用」を参照してください。

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

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

Windows 10 バージョン 1903 および Windows Server 2022 以降では、pExtendedParameters 引数でこの関数に渡されるCOPYFILE2_EXTENDED_PARAMETERS構造体の dwCopyFlags フィールドに対して、新しい値である COPY_FILE_REQUEST_COMPRESSED_TRAFFIC がサポートされています。この新しい値は、コピー操作中に基になる転送チャネルがデータを圧縮することを要求します。要求は、すべてのメディアでサポートされていない場合があり、その場合は無視されます。圧縮属性とパラメーター (計算の複雑さ、メモリ使用量) は、この API では構成できません。また、異なる OS リリース間で変更される可能性があります。 Windows 10では、SMB 共有に存在するファイルに対してフラグがサポートされます。この場合、ネゴシエートされた SMB プロトコルのバージョンは SMB v3.1.1 以降です。

要件


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

次の方法で共有

CopyFile2 関数 (winbase.h)

構文

パラメーター

戻り値

解説

要件

関連項目

フィードバック

その他のリソース