CF_OPERATION_PARAMETERS 结构 (cfapi.h)

项目
02/23/2024

占位符文件或文件夹上操作的详细参数。此结构中提供的数据特定于操作 CF_OPERATION_TYPE 。

语法

typedef struct CF_OPERATION_PARAMETERS {
  ULONG ParamSize;
  union {
    struct {
      CF_OPERATION_TRANSFER_DATA_FLAGS Flags;
      NTSTATUS                         CompletionStatus;
      LPCVOID                          Buffer;
      LARGE_INTEGER                    Offset;
      LARGE_INTEGER                    Length;
    } TransferData;
    struct {
      CF_OPERATION_RETRIEVE_DATA_FLAGS Flags;
      LPVOID                           Buffer;
      LARGE_INTEGER                    Offset;
      LARGE_INTEGER                    Length;
      LARGE_INTEGER                    ReturnedLength;
    } RetrieveData;
    struct {
      CF_OPERATION_ACK_DATA_FLAGS Flags;
      NTSTATUS                    CompletionStatus;
      LARGE_INTEGER               Offset;
      LARGE_INTEGER               Length;
    } AckData;
    struct {
      CF_OPERATION_RESTART_HYDRATION_FLAGS Flags;
      const CF_FS_METADATA                 *FsMetadata;
      LPCVOID                              FileIdentity;
      DWORD                                FileIdentityLength;
    } RestartHydration;
    struct {
      CF_OPERATION_TRANSFER_PLACEHOLDERS_FLAGS Flags;
      NTSTATUS                                 CompletionStatus;
      LARGE_INTEGER                            PlaceholderTotalCount;
      CF_PLACEHOLDER_CREATE_INFO               *PlaceholderArray;
      DWORD                                    PlaceholderCount;
      DWORD                                    EntriesProcessed;
    } TransferPlaceholders;
    struct {
      CF_OPERATION_ACK_DEHYDRATE_FLAGS Flags;
      NTSTATUS                         CompletionStatus;
      LPCVOID                          FileIdentity;
      DWORD                            FileIdentityLength;
    } AckDehydrate;
    struct {
      CF_OPERATION_ACK_RENAME_FLAGS Flags;
      NTSTATUS                      CompletionStatus;
    } AckRename;
    struct {
      CF_OPERATION_ACK_DELETE_FLAGS Flags;
      NTSTATUS                      CompletionStatus;
    } AckDelete;
  } DUMMYUNIONNAME;
} CF_OPERATION_PARAMETERS;

成员

ParamSize

DUMMYUNIONNAME

DUMMYUNIONNAME.TransferData

同步提供程序执行 TRANSFER_DATA 来冻结占位符文件。此操作可以作为对 FETCH_DATA 回调、 VALIDATE_DATA 回调的响应，或作为任何回调上下文之外的抢先后台混合工作的一部分来执行。

此 API 仅适用于支持小于 ALWAYS_FULL 的混合策略的同步提供程序。否则，操作将失败并 ERROR_CLOUD_FILE_INVALID_REQUEST。

同步提供程序需要 具有WRITE_DATA 或 WRITE_DAC 对要对其执行 TRANSFER_DATA 操作的文件的访问权限。否则，操作将失败并 显示ERROR_CLOUD_FILE_ACCESS_DENIED。

若要执行此操作，请执行以下操作：

OpInfo.Type 必须设置为 CF_OPERATION_TYPE_TRANSFER_DATA。
OpParams.ParamSize 必须设置为 OpParams.TransferData 的确切大小加上 OpParams.TransferData 的偏移量。
OpParams.TransferData.Flags 必须设置为 CF_OPERATION_TRANSFER_DATA_FLAG_NONE。
如果同步提供程序要将数据传输到占位符文件，则必须将 OpParams.TransferData.CompletionStatus 设置为 STATUS_SUCCESS。如果同步提供程序出于任何原因无法处理水化请求，并且不想重新启动混合，则必须在 CompletionStatus 中设置STATUS_CLOUD_FILE_* 状态。 STATUS_CLOUD_FILE_ * 范围之外返回的任何状态代码（ STATUS_SUCCESS 除外）都将由平台转换为 STATUS_CLOUD_FILE_UNSUCCESSFUL 。
如果 OpParams.TransferData.CompletionStatusSTATUS_SUCCESS且至少应为 OpParams.TransferData.Length 字节，则 OpParams.TransferData.Buffer 必须指向有效的用户模式缓冲区;否则，将忽略缓冲区字段。
OpParams.TransferData.Offset 和 OpParams.TransferData.Length 描述同步提供程序将数据传输到的占位符中的范围。同步提供程序不要求在一次拍摄中按请求返回所有数据。同步提供程序也可以返回比请求更多的数据。例如，出于性能或其他原因，同步提供程序可以决定过度读取。同步提供程序还可以重复执行多个 TRANSFER_DATA 操作，作为对同一 FETCH_DATA回调的 响应。唯一的要求是偏移量和长度都是 4KB 对齐的，除非所描述的范围以逻辑文件大小 (EoF) 结束，在这种情况下，只要结果范围结束于或超过逻辑文件大小，长度就不需要对齐 4KB。

操作完成后：

如果同步提供程序未指定同步根注册时 VALIDATION_REQUIRED 。

在成功传输的情况下，任何挂起的用户 IO 请求都将完成已收到传输所需的所有字节的占位符文件;否则，不完整的用户 IO 请求将更新以反映最新的混合状态。在传输失败的情况下，如果占位符文件与偏移量和长度描述的范围重叠，则任何挂起的用户 IO 请求都将因 OpParams.TransferData.CompletionStatus 而失败。

如果同步提供程序在同步根注册时指定 了VALIDATION_REQUIRED ，则在同步提供程序通过ACK_DATA操作确认范围中的数据之前，平台不会再执行 任何处理 。

DUMMYUNIONNAME.TransferData.Flags

用于传输数据的标志。必须将其设置为 CF_OPERATION_TRANSFER_DATA_FLAG_NONE。有关详细信息，请参阅CF_OPERATION_TRANSFER_DATA_FLAGS 。

DUMMYUNIONNAME.TransferData.CompletionStatus

传输数据的状态。如果同步提供程序要将数据传输到占位符文件，则必须将其设置为 STATUS_SUCCESS 。如果同步提供程序出于任何原因无法处理水化请求，并且不想重新启动混合，则必须在 CompletionStatus 中设置STATUS_CLOUD_FILE_* 状态。 STATUS_CLOUD_FILE_ * 范围之外返回的任何状态代码（ STATUS_SUCCESS 除外）都将由平台转换为 STATUS_CLOUD_FILE_UNSUCCESSFUL 。

DUMMYUNIONNAME.TransferData.Buffer

有效的用户模式缓冲区。如果 CompletionStatus 是 STATUS_SUCCESS 且 长度至少为 字节，则必须指向有效的用户模式缓冲区。否则，将忽略缓冲区字段。

DUMMYUNIONNAME.TransferData.Offset

与 Length 一起使用的偏移量，用于描述数据要传输到的占位符中的范围。它描述同步提供程序将数据传输到的占位符中的一个范围。同步提供程序不要求在一次拍摄中按请求返回所有数据。同步提供程序也可以返回比请求更多的数据。例如，出于性能或其他原因，同步提供程序可以决定过度读取。同步提供程序还可以重复执行多个 TRANSFER_DATA 操作，作为对同一 FETCH_DATA回调的 响应。 偏移量 必须对齐 4KB。

DUMMYUNIONNAME.TransferData.Length

Buffer 的长度（以字节为单位）。长度必须对齐 4KB，除非所描述的范围以逻辑文件大小 (EoF) 结束，在这种情况下，只要生成的范围以逻辑文件大小结束或超过逻辑文件大小，长度就不需要对齐 4KB。即使不STATUS_SUCCESSCompletionStatus，也应将此字段设置为有效值。

DUMMYUNIONNAME.RetrieveData

同步提供程序在占位符混合过程中执行 RETRIEVE_DATA 操作，以验证以前传输到占位符的数据的完整性。此操作可以作为对 FETCH_DATA 回调、 VALIDATE_DATA 回调的响应，或作为任何回调上下文之外的抢先后台混合工作的一部分来执行。

此 API 仅适用于支持小于 ALWAYS_FULL 的混合策略的同步提供程序。否则，操作将失败并 STATUS_CLOUD_FILE_NOT_SUPPORTED。

同步提供程序需要在同步根注册时指定水化策略修饰符 VALIDATE_REQUIRED ，以便执行此操作。否则，操作将失败并 STATUS_CLOUD_FILE_NOT_SUPPORTED。

同步提供程序需要对要对其执行RETRIEVE_DATA操作的文件具有READ_DATA或WRITE_DAC访问权限。否则，操作将失败并 STATUS_CLOUD_FILE_ACCESS_DENIED。

若要执行此操作，请执行以下操作：

OpInfo.Type 必须设置为 CF_OPERATION_TYPE_RETRIEVE_DATA。
OpParams.ParamSize 必须设置为 OpParams.RetrieveData 的确切大小加上 OpParams.RetrieveData 的偏移量。
OpParams.RetrieveData.Flags 必须设置为 CF_OPERATION_RETRIEVE_DATA_FLAG_NONE。
OpParams.RetrieveData.Buffer 必须指向有效的用户模式缓冲区，并且至少为 OpParams.RetrieveData.Length 字节。成功完成操作后，它将接收之前通过 TRANSFER_DATA传输到占位符的数据。
OpParams.RetrieveData.Offset 和 OpParams.RetrieveData.Length 描述同步提供程序从中检索数据的占位符范围。请求的范围必须在RETRIEVE_DATA操作之前由TRANSFER_DATA操作完全冻结，否则操作将失败并STATUS_CLOUD_FILE_INVALID_REQUEST。偏移量和长度都是 4KB 对齐的，除非所描述的范围以逻辑文件大小 (EoF) 结束，在这种情况下，只要长度在逻辑文件大小上结束或超过逻辑文件大小，就不需要对齐 4KB。
OpParams.RetrieveData.ReturnedLength 接收成功完成操作后检索到的实际字节数。

DUMMYUNIONNAME.RetrieveData.Flags

用于检索数据的标志。必须将其设置为 CF_OPERATION_RETRIEVE_DATA_FLAG_NONE。有关详细信息，请参阅CF_OPERATION_RETRIEVE_DATA_FLAGS 。

DUMMYUNIONNAME.RetrieveData.Buffer

这必须指向有效的用户模式缓冲区，并且至少为长度字节。成功完成操作后，它将接收之前通过 TRANSFER_DATA传输到占位符的数据。

DUMMYUNIONNAME.RetrieveData.Offset

与 Length 一起使用的偏移量，用于描述从占位符检索的数据范围。它描述同步提供程序从中检索数据的占位符中的一个范围。请求的范围必须在RETRIEVE_DATA操作之前由TRANSFER_DATA操作完全冻结，否则操作将失败并STATUS_CLOUD_FILE_INVALID_REQUEST。 偏移量 必须对齐 4KB。

DUMMYUNIONNAME.RetrieveData.Length

Buffer 的长度（以字节为单位）。除非所描述的范围以逻辑文件大小 (EoF) 结束，否则为 4KB 对齐，在这种情况下，只要长度在逻辑文件大小上或超过逻辑文件大小，就不需要对齐 4KB。

DUMMYUNIONNAME.RetrieveData.ReturnedLength

成功完成操作时检索到的字节数。

DUMMYUNIONNAME.AckData

同步提供程序在验证以前传输到平台的数据的完整性后，执行 ACK_DATA 操作，作为占位符混合的一部分。此操作可以作为对 FETCH_DATA 回调、 VALIDATE_DATA 回调的响应，或作为任何回调上下文之外的抢先后台混合工作的一部分来执行。

此 API 仅适用于支持小于 ALWAYS_FULL 的混合策略的同步提供程序。否则，操作将失败并 STATUS_CLOUD_FILE_NOT_SUPPORTED。

同步提供程序需要在同步根注册时指定水化策略修饰符 VALIDATE_REQUIRED 以执行此操作。否则，操作将失败并 STATUS_CLOUD_FILE_NOT_SUPPORTED。

同步提供程序需要对要对其执行ACK_DATA操作的文件具有READ_DATA或WRITE_DAC访问权限。否则，操作将失败并 STATUS_CLOUD_FILE_ACCESS_DENIED。

若要执行此操作，请执行以下操作：

OpInfo.Type 必须设置为 CF_OPERATION_TYPE_ACK_DATA。
OpParams.ParamSize 必须设置为 OpParams.AckData 的确切大小加上 OpParams.AckData 的偏移量。
OpParams.AckData.Flags 必须设置为 CF_OPERATION_ACK_DATA_FLAG_NONE。
如果同步提供程序验证要确认的范围内的数据是否正常，则必须将 OpParams.AckData.CompletionStatus 设置为 STATUS_SUCCESS。如果同步提供程序出于任何原因未能验证数据，并且不想重启水化，则必须在 CompletionStatus 中设置STATUS_CLOUD_FILE_* 状态。 STATUS_CLOUD_FILE_ * 范围之外返回的任何状态代码（ STATUS_SUCCESS 除外）都将由平台转换为 STATUS_CLOUD_FILE_UNSUCCESSFUL 。
OpParams.AckData.Offset 和 OpParams.AckData.Length 描述占位符中的一个范围，其数据将由同步提供程序确认。在操作之前，不需要通过 TRANSFER_DATA 操作完全冻结所请求的范围。 Offset 和 Length 都是 4KB 对齐的，除非所描述的范围以逻辑文件大小 (EoF) 结束，在这种情况下，只要长度在逻辑文件大小上结束或超过逻辑文件大小，就不需要对齐 4KB。
长度-1（表示为 CF_EOF）表示无限 (，即到文件) 末尾。

成功ACK_DATA操作后，将完成占位符文件上由于ACK_DATA操作而收到所有所需字节的挂起用户 IO 请求;否则，不完整的用户 IO 请求将更新以反映最新的混合状态。在失败 ACK_DATA 的情况下，占位符文件上与 Offset 和 Length 所描述的范围重叠的任何挂起的用户 IO 请求都将因 CompletionStatus 而失败。

DUMMYUNIONNAME.AckData.Flags

用于确认数据的标志。必须将其设置为 CF_OPERATION_ACK_DATA_FLAG_NONE。有关详细信息，请参阅CF_OPERATION_ACK_DATA_FLAGS 。

DUMMYUNIONNAME.AckData.CompletionStatus

数据确认的完成状态。如果同步提供程序验证要确认的范围内的数据是否正常，则必须将其设置为 STATUS_SUCCESS 。如果同步提供程序出于任何原因未能验证数据，并且不想重启水化，则必须在 CompletionStatus 中设置STATUS_CLOUD_FILE_* 状态。 STATUS_CLOUD_FILE_ * 范围之外返回的任何状态代码（ STATUS_SUCCESS 除外）都将由平台转换为 STATUS_CLOUD_FILE_UNSUCCESSFUL 。

DUMMYUNIONNAME.AckData.Offset

要确认的占位符数据的偏移量（以字节为单位）。 Offset 描述占位符中的一个范围，同步提供程序将确认其数据。在操作之前，不需要通过 TRANSFER_DATA 操作完全冻结所请求的范围。 偏移量 必须对齐 4KB。

DUMMYUNIONNAME.AckData.Length

要确认的占位符中数据的长度（以字节为单位）。必须对齐 4KB，除非所描述的范围以逻辑文件大小 (EoF) 结束，在这种情况下，只要长度在逻辑文件大小上或超过逻辑文件大小，就不需要对齐 4KB。长度-1（表示为 CF_EOF）表示无限 (，即到文件) 末尾。

DUMMYUNIONNAME.RestartHydration

同步提供程序执行 RESTART_HYDRATION 操作以重新启动正在进行的混合。此操作可以作为对 FETCH_DATA 回调、 VALIDATE_DATA 回调的响应，或作为任何回调上下文之外的抢先后台混合工作的一部分来执行。

此 API 仅适用于支持完全混合策略的同步提供程序。否则，操作将失败并 STATUS_CLOUD_FILE_NOT_SUPPORTED。

同步提供程序需要对要对其执行RESTART_HYDRATION操作的文件具有WRITE_DATA或WRITE_DAC访问权限。否则，操作将失败并 STATUS_CLOUD_FILE_ACCESS_DENIED。

若要执行此操作，请执行以下操作：

OpInfo.Type 必须设置为 CF_OPERATION_TYPE_RESTART_HYDRATION。
OpParams.ParamSize 必须设置为 OpParams.RestartHydration 的确切大小加上 OpParams.RestartHydration 的偏移量。
OpParams.RestartHydration.Flags 必须设置为 CF_OPERATION_RESTART_HYDRATION_FLAG_NONE 或 CF_OPERATION_RESTART_HYDRATION_FLAG_MARK_IN_SYNC。
- 如果指定 了CF_OPERATION_RESTART_HYDRATION_FLAG_MARK_IN_SYNC ，则占位符将在成功 RESTART_HYDRATION 操作后标记为同步。
OpParams.RestartHydration.FsMetadata 是可选的。提供时：
- 0 timestamp 字段中的值 (CreationTime、LastAccessTime、LastWriteTime 和 ChangeTime) 表示对文件的当前时间戳没有更改。
- 0FileAttributes 中的值表示文件中的当前文件属性没有更改。
- FileSize 中没有特殊值。 0FileSize 中的值将文件大小截断为 0。
OpParams.RestartHydration.FileIdentity 和 OpParams.RestartHydration.FileIdentityLength 是可选的。提供后，新标识将保留在文件中。否则，当前文件标识将保留。

同步提供程序在确定占位符中的磁盘数据实际上无效且不适合满足 I/O 请求的情况下调用此 API。典型的情况是，由于某种原因检索到的数据未能通过校验和验证。另一种使用场景是，在混合过程中，文件内容实际上已在云中更新 (并且同步提供程序无法从云中检索对应于本地占位符版本) 的历史内容。

成功重启后，占位符将完全冻结，并使用新的元数据（如果有）进行更新。挂起的用户 IO 请求（如果有）将重新处理，就像它们刚刚到达一样，因此，同步提供程序将收到看起来与同步提供程序之前收到的回调完全相同的新回调。

但是，如果重启因任何原因失败，则占位符可能处于非确定性状态，具体取决于遇到错误的位置，并且占位符上的所有挂起的用户 IO 请求都将失败并出现相同的错误。在这种情况下，平台唯一保证的是，用户将来对占位符文件的访问权限将触发相同的回调。

DUMMYUNIONNAME.RestartHydration.Flags

用于重启占位符混合的标志。必须将其设置为 CF_OPERATION_RESTART_HYDRATION_FLAG_NONE 或 CF_OPERATION_RESTART_HYDRATION_FLAG_MARK_IN_SYNC。如果指定 了CF_OPERATION_RESTART_HYDRATION_FLAG_MARK_IN_SYNC ，则占位符将在成功 RESTART_HYDRATION 操作后标记为同步。有关详细信息，请参阅CF_OPERATION_RESTART_HYDRATION_FLAGS 。

DUMMYUNIONNAME.RestartHydration.FsMetadata

可选。包含对文件元数据的更新。指定时：

0 timestamp 字段中的值 (CreationTime、LastAccessTime、LastWriteTime 和 ChangeTime) 表示对文件的当前时间戳没有更改。
0FileAttributes 中的值表示对文件的当前文件属性没有更改。
FileSize 中没有特殊值。 0FileSize 中的值将文件大小截断为 0。

DUMMYUNIONNAME.RestartHydration.FileIdentity

可选。提供后，文件标识将更新为此值。否则，它保持不变。

DUMMYUNIONNAME.RestartHydration.FileIdentityLength

可选。这指定 FileIdentity 的长度。

DUMMYUNIONNAME.TransferPlaceholders

DUMMYUNIONNAME.TransferPlaceholders.Flags

用于传输占位符的标志。有关详细信息，请参阅CF_OPERATION_TRANSFER_PLACEHOLDERS_FLAGS 。

DUMMYUNIONNAME.TransferPlaceholders.CompletionStatus

传输占位符操作的完成状态。

DUMMYUNIONNAME.TransferPlaceholders.PlaceholderTotalCount

占位符的总数。

DUMMYUNIONNAME.TransferPlaceholders.PlaceholderArray

要传输的占位符数组。

DUMMYUNIONNAME.TransferPlaceholders.PlaceholderCount

正在传输的占位符数。

DUMMYUNIONNAME.TransferPlaceholders.EntriesProcessed

已处理的占位符条目。

DUMMYUNIONNAME.AckDehydrate

DUMMYUNIONNAME.AckDehydrate.Flags

冻结的数据确认标志。有关详细信息，请参阅CF_OPERATION_ACK_DEHYDRATE_FLAGS 。

DUMMYUNIONNAME.AckDehydrate.CompletionStatus

确认冻结操作的完成状态。如果同步提供程序能够允许解除冻结继续进行，则必须将其设置为 STATUS_SUCCESS 。如果同步提供程序出于任何原因打算禁止解除冻结，则必须在 CompletionStatus 中设置STATUS_CLOUD_FILE_*状态。 STATUS_CLOUD_FILE_ * 范围之外返回的任何状态代码（ STATUS_SUCCESS 除外）都将由平台转换为 STATUS_CLOUD_FILE_UNSUCCESSFUL 。

DUMMYUNIONNAME.AckDehydrate.FileIdentity

要确认其冻结数据的占位符文件的文件标识。

DUMMYUNIONNAME.AckDehydrate.FileIdentityLength

FileIdentity 的长度（以字节为单位）。

DUMMYUNIONNAME.AckRename

DUMMYUNIONNAME.AckRename.Flags

确认重命名占位符标志。有关详细信息，请参阅CF_OPERATION_ACK_RENAME_FLAGS 。

DUMMYUNIONNAME.AckRename.CompletionStatus

确认重命名操作的完成状态。如果同步提供程序能够允许重命名操作继续，则必须将其设置为 STATUS_SUCCESS 。如果同步提供程序出于任何原因打算禁止重命名，则必须在 CompletionStatus 中设置STATUS_CLOUD_FILE_*状态。 STATUS_CLOUD_FILE_ * 范围之外返回的任何状态代码（ STATUS_SUCCESS 除外）都将由平台转换为 STATUS_CLOUD_FILE_UNSUCCESSFUL 。

DUMMYUNIONNAME.AckDelete

DUMMYUNIONNAME.AckDelete.Flags

确认删除标志。有关详细信息，请参阅CF_OPERATION_ACK_DELETE_FLAGS 。

DUMMYUNIONNAME.AckDelete.CompletionStatus

确认删除操作的完成状态。如果同步提供程序能够允许删除操作继续，则必须将其设置为 STATUS_SUCCESS 。如果同步提供程序出于任何原因打算禁止删除，则必须在 CompletionStatus 中设置STATUS_CLOUD_FILE_* 状态。 STATUS_CLOUD_FILE_ * 范围之外返回的任何状态代码（ STATUS_SUCCESS 除外）都将由平台转换为 STATUS_CLOUD_FILE_UNSUCCESSFUL 。

要求

要求	值
最低受支持的客户端	Windows 10版本 1709 [仅限桌面应用]
最低受支持的服务器	Windows Server 2016 [仅限桌面应用]
标头	cfapi.h

另请参阅

CfExecute

CF_OPERATION_TRANSFER_DATA_FLAGS

CF_OPERATION_RETRIEVE_DATA_FLAGS

通过

CF_OPERATION_PARAMETERS 结构 (cfapi.h)

语法

成员

要求

另请参阅

反馈

其他资源