winbase.h) (COPYFILE2_EXTENDED_PARAMETERS 结构

项目
03/13/2024

包含 CopyFile2 函数的扩展参数。

语法

typedef struct COPYFILE2_EXTENDED_PARAMETERS {
  DWORD                       dwSize;
  DWORD                       dwCopyFlags;
  BOOL                        *pfCancel;
  PCOPYFILE2_PROGRESS_ROUTINE pProgressRoutine;
  PVOID                       pvCallbackContext;
} COPYFILE2_EXTENDED_PARAMETERS;

成员

dwSize

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

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 \\| WRITE_DAC \\| WRITE_OWNER`为目标文件指定 `ACCESS_SYSTEM_SECURITY` 。如果拒绝这些请求，访问请求将降低到为其授予访问权限的最高特权级别。有关详细信息，请参阅 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 Server 2022 和 Windows 10 内部版本 1903 及更高版本中受支持。 (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 回调函数。

pvCallbackContext

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

注解

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

要求

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

另请参阅

CopyFile2

CopyFile2ProgressRoutine

文件管理结构

COPYFILE2_EXTENDED_PARAMETERS_V2

通过

winbase.h) (COPYFILE2_EXTENDED_PARAMETERS 结构

语法

成员

注解

要求

另请参阅

反馈

其他资源