COPYFILE2_EXTENDED_PARAMETERS_V2 结构 (winbase.h)

项目
11/14/2023

包含 CopyFile2 函数COPYFILE2_EXTENDED_PARAMETERS结构之外的更新的其他功能。

语法

typedef struct COPYFILE2_EXTENDED_PARAMETERS_V2 {
  DWORD                         dwSize;
  DWORD                         dwCopyFlags;
  BOOL                          *pfCancel;
  PCOPYFILE2_PROGRESS_ROUTINE   pProgressRoutine;
  PVOID                         pvCallbackContext;
  DWORD                         dwCopyFlagsV2;
  ULONG                         ioDesiredSize;
  ULONG                         ioDesiredRate;
  LPPROGRESS_ROUTINE            pProgressRoutineOld;
  PCOPYFILE2_CREATE_OPLOCK_KEYS SourceOplockKeys;
#if ...
  PVOID                         reserved[6];
#elif
  PVOID                         reserved[7];
#else
  PVOID                         reserved[8];
#endif
} COPYFILE2_EXTENDED_PARAMETERS_V2;

成员

dwSize

包含此结构 sizeof(COPYFILE2_EXTENDED_PARAMETERS_V2)的大小。

dwCopyFlags

包含零个或多个这些标志值的组合。

值	含义
COPY_FILE_FAIL_IF_EXISTS `0x00000001`	如果目标文件存在，则复制操作将立即失败。如果存在具有目标名称的文件或目录，则 CopyFile2 函数调用将失败并出现 `HRESULT_FROM_WIN32(ERROR_ALREADY_EXISTS)` 或 `HRESULT_FROM_WIN32(ERROR_FILE_EXISTS)`。如果还指定了COPY_FILE_RESUME_FROM_PAUSE ，则仅当目标文件没有有效的重启标头时才会触发失败。
COPY_FILE_RESTARTABLE `0x00000002`	如果再次使用相同的源文件名和目标文件名，则复制文件的方式可以重启。速度较慢。
COPY_FILE_OPEN_SOURCE_FOR_WRITE `0x00000004`	复制该文件，并打开源文件以获取写入访问权限。
COPY_FILE_ALLOW_DECRYPTED_DESTINATION `0x00000008`	即使无法加密目标文件，也会尝试复制。
COPY_FILE_COPY_SYMLINK `0x00000800`	如果源文件是符号链接，则目标文件也是指向与源符号链接相同的文件的符号链接。
COPY_FILE_NO_BUFFERING `0x00001000`	复制是使用未缓冲的 I/O 执行的，绕过系统缓存资源。对于非常大的文件副本，建议使用此标志。不建议暂停使用此标志的副本。
COPY_FILE_REQUEST_SECURITY_PRIVILEGES `0x00002000`	尝试复制，并指定 `ACCESS_SYSTEM_SECURITY` 源文件和 `ACCESS_SYSTEM_SECURITY \\| WRITE_DAC \\| WRITE_OWNER` 目标文件。如果拒绝这些请求，则访问请求将降低到授予访问权限的最高特权级别。有关详细信息，请参阅 SACL 访问权限。这可用于允许 CopyFile2ProgressRoutine 回调执行需要更高特权的操作，例如复制文件的安全属性。
COPY_FILE_RESUME_FROM_PAUSE `0x00004000`	检查目标文件以查看它是否使用 COPY_FILE_RESTARTABLE复制。如果是这样，则恢复复制。否则，将完全复制文件。
COPY_FILE_NO_OFFLOAD `0x00040000`	请勿尝试使用 Windows 复制卸载机制。通常不建议这样做。
COPY_FILE_IGNORE_EDP_BLOCK `0x00400000`	如果目标文件系统支持，则应在目标上复制和加密文件，而不是阻止该文件。在 Windows 10 及更高版本上受支持。
COPY_FILE_IGNORE_SOURCE_ENCRYPTION `0x00800000`	忽略源文件的加密状态。在 Windows 10 及更高版本上受支持。
COPY_FILE_DONT_REQUEST_DEST_WRITE_DAC `0x02000000`	不要请求目标文件访问WRITE_DAC。在 Windows 10 及更高版本上受支持。
COPY_FILE_OPEN_AND_COPY_REPARSE_POINT `0x00200000`	无论类型如何，始终复制重新分析点。调用方有责任了解重新分析点的含义。支持Windows 10版本 19041 及更高版本。
COPY_FILE_DIRECTORY `0x00000080`	指示源文件是目录文件。如果提供，则使用 `FILE_OPEN_FOR_BACKUP_INTENT`打开源文件。目录文件将具有其备用数据流、重新分析点信息和像普通文件一样复制的 CA。在 Windows 10 版本 19041 及更高版本中受支持。
COPY_FILE_SKIP_ALTERNATE_STREAMS `0x00008000`	请勿复制备用数据流。在 Windows 10 版本 19041 及更高版本中受支持。
COPY_FILE_DISABLE_PRE_ALLOCATION `0x04000000`	在执行复制之前，请勿预先分配目标文件大小。在 Windows 10 版本 19041 及更高版本中受支持。
COPY_FILE_ENABLE_LOW_FREE_SPACE_MODE `0x08000000`	启用 LowFreeSpace 模式。不使用重叠的 I/O。不会尝试 ODX 和 SMB 卸载。在 Windows 10 版本 19041 及更高版本中受支持。
COPY_FILE_REQUEST_COMPRESSED_TRAFFIC `0x10000000`	请求基础传输通道在复制操作期间压缩数据。并非所有媒体都支持请求，在这种情况下，它将被忽略。压缩属性和参数 (计算复杂性、内存使用情况) 无法通过此 API 进行配置，并且可能会在不同的 OS 版本之间发生更改。此标志是在 Windows 10 版本 1903 和 Windows Server 2022 中引入的。在Windows 10，驻留在 SMB 共享上的文件支持标志，其中协商的 SMB 协议版本为 SMB v3.1.1 或更高版本。
COPY_FILE_ENABLE_SPARSE_COPY `0x20000000`	在复制期间启用保留文件的稀疏状态。在 Windows 11 版本 22H2 及更高版本中受支持。

pfCancel

如果在复制操作期间将此标志设置为 TRUE ，则取消复制操作。

pProgressRoutine

类型 为 PCOPYFILE2_PROGRESS_ROUTINE 的回调函数的可选地址，每次复制文件的另一部分时调用该函数。此参数可以为 NULL。有关进度回调函数的详细信息，请参阅 CopyFile2ProgressRoutine 回调函数。如果同时提供了 pProgressRoutineOld 和 pProgressRoutine ， 则 pProgressRoutineOld 优先。

pvCallbackContext

指向要传递给 CopyFile2ProgressRoutine 的应用程序特定上下文信息的指针。

dwCopyFlagsV2

包含零个或多个这些标志值的组合。

值	含义
COPY_FILE2_V2_DONT_COPY_JUNCTIONS `0x00000001`	禁用复制交汇点。

ioDesiredSize

可选。每个 I/O 操作的请求大小 (字节) (即复制文件) 一个读/写周期。如果可用内存不足，可能会减少这一点。如果为零，则使用默认大小。如果还提供了 ioDesiredRate ，则可能会忽略此内容

ioDesiredRate

可选。请求的平均 I/O 速率，以千字节/秒为单位。如果为零，则执行复制的速度会尽可能快。

pProgressRoutineOld

SourceOplockKeys

reserved[6]

reserved[7]

reserved[8]

pProgressRoutineOld。可选。类型为 LPPROGRESS_ROUTINE 的旧样式回调函数的地址，每次复制文件的另一部分时都会调用该函数。此参数可以为 NULL。有关详细信息，请参阅进度回调函数 LPPROGRESS_ROUTINE回调。如果同时提供了 pProgressRoutineOld 和 pProgressRoutine ， 则 pProgressRoutineOld 优先。

注解

若要编译使用此结构的应用程序，请将 _WIN32_WINNT 宏定义为 _WIN32_WINNT_WIN8 或更高版本。有关详细信息，请参阅使用 Windows 标头。

要求


最低受支持的客户端	Windows 11 [桌面应用	UWP 应用]
最低受支持的服务器	Windows Server 2012 [桌面应用	UWP 应用]
标头	winbase.h (包括 Windows.h)

另请参阅

CopyFile2

COPYFILE2_EXTENDED_PARAMETERS

CopyFile2ProgressRoutine

文件管理结构

LPPROGRESS_ROUTINE

使用 Windows 标头

通过

COPYFILE2_EXTENDED_PARAMETERS_V2 结构 (winbase.h)

语法

成员

注解

要求

另请参阅

反馈

其他资源