CF_CALLBACK_PARAMETERS 结构 (cfapi.h)

  • 项目

此结构包含特定于回调的参数，例如文件偏移量、长度、标志等。

语法

typedef struct CF_CALLBACK_PARAMETERS {
  ULONG ParamSize;
  union {
    struct {
      CF_CALLBACK_CANCEL_FLAGS Flags;
      union {
        struct {
          LARGE_INTEGER FileOffset;
          LARGE_INTEGER Length;
        } FetchData;
      } DUMMYUNIONNAME;
    } Cancel;
    struct {
      CF_CALLBACK_FETCH_DATA_FLAGS   Flags;
      LARGE_INTEGER                  RequiredFileOffset;
      LARGE_INTEGER                  RequiredLength;
      LARGE_INTEGER                  OptionalFileOffset;
      LARGE_INTEGER                  OptionalLength;
      LARGE_INTEGER                  LastDehydrationTime;
      CF_CALLBACK_DEHYDRATION_REASON LastDehydrationReason;
    } FetchData;
    struct {
      CF_CALLBACK_VALIDATE_DATA_FLAGS Flags;
      LARGE_INTEGER                   RequiredFileOffset;
      LARGE_INTEGER                   RequiredLength;
    } ValidateData;
    struct {
      CF_CALLBACK_FETCH_PLACEHOLDERS_FLAGS Flags;
      PCWSTR                               Pattern;
    } FetchPlaceholders;
    struct {
      CF_CALLBACK_OPEN_COMPLETION_FLAGS Flags;
    } OpenCompletion;
    struct {
      CF_CALLBACK_CLOSE_COMPLETION_FLAGS Flags;
    } CloseCompletion;
    struct {
      CF_CALLBACK_DEHYDRATE_FLAGS    Flags;
      CF_CALLBACK_DEHYDRATION_REASON Reason;
    } Dehydrate;
    struct {
      CF_CALLBACK_DEHYDRATE_COMPLETION_FLAGS Flags;
      CF_CALLBACK_DEHYDRATION_REASON         Reason;
    } DehydrateCompletion;
    struct {
      CF_CALLBACK_DELETE_FLAGS Flags;
    } Delete;
    struct {
      CF_CALLBACK_DELETE_COMPLETION_FLAGS Flags;
    } DeleteCompletion;
    struct {
      CF_CALLBACK_RENAME_FLAGS Flags;
      PCWSTR                   TargetPath;
    } Rename;
    struct {
      CF_CALLBACK_RENAME_COMPLETION_FLAGS Flags;
      PCWSTR                              SourcePath;
    } RenameCompletion;
  } DUMMYUNIONNAME;
} CF_CALLBACK_PARAMETERS;

成员

ParamSize

ParamSize 是根据正在执行的回调设置的。

回调 ParamSize 信息
CF_CALLBACK_TYPE_FETCH_DATA 将 设置为 的大小 FetchData 加上 的大小 ULONG。
CF_CALLBACK_TYPE_VALIDATE_DATA 将 设置为 的大小 ValidateData 加上 的大小 ULONG。
CF_CALLBACK_TYPE_CANCEL_FETCH_DATA 将 设置为 的大小 Cancel.FetchData 加上两 ULONG个 s 的大小。
CF_CALLBACK_TYPE_FETCH_PLACHOLDERS 将 设置为 的大小 FetchPlaceholders 加上 的大小 ULONG。
CF_CALLBACK_TYPE_CANCEL_FETCH_PLACHOLDERS 将 设置为两 ULONG个 s 的大小。
CF_CALLBACK_TYPE_NOTIFY_FILE_OPEN_COMPLETION 将 设置为 的大小 OpenCompletion 加上 的大小 ULONG。
CF_CALLBACK_TYPE_NOTIFY_FILE_CLOSE_COMPLETION 将 设置为 的大小 CloseCompletion 加上 的大小 ULONG。
CF_CALLBACK_TYPE_NOTIFY_DEHYDRATE 将 设置为 的大小 Dehydrate 加上 的大小 ULONG。
CF_CALLBACK_TYPE_NOTIFY_DEHYDRATE_COMPLETION 将 设置为 的大小 DehydrateCompletion 加上 的大小 ULONG。
CF_CALLBACK_TYPE_NOTIFY_DELETE 将 设置为 的大小 Delete 加上 的大小 ULONG。
CF_CALLBACK_TYPE_NOTIFY_DELETE_COMPLETION 将 设置为 的大小 DeleteCompletion 加上 的大小 ULONG。
CF_CALLBACK_TYPE_NOTIFY_RENAME 将 设置为 的大小 Rename 加上 的大小 ULONG。
CF_CALLBACK_TYPE_NOTIFY_RENAME_COMPLETION 将 设置为 的大小 RenameCompletion 加上 的大小 ULONG。

DUMMYUNIONNAME

DUMMYUNIONNAME.Cancel

DUMMYUNIONNAME.Cancel.Flags

可以将标志 设置为以下标志：

  • 如果用户请求因 60 秒计时器过期而取消，则设置CF_CALLBACK_CANCEL_FLAG_IO_TIMEOUT。
  • 如果由于用户显式终止应用启动的下载 Toast 中的混合而取消用户请求，则会设置CF_CALLBACK_CANCEL_FLAG_IO_ABORTED。

DUMMYUNIONNAME.Cancel.DUMMYUNIONNAME

DUMMYUNIONNAME.Cancel.DUMMYUNIONNAME.FetchData

DUMMYUNIONNAME.Cancel.DUMMYUNIONNAME.FetchData.FileOffset

用于指定不再需要的文件数据范围的偏移量（以字节为单位）。 请注意，这可能与相应提取中的 RequiredFileOffset 匹配，但也可能是子集。 如果是子集，则仍然需要取消范围以外的数据，例如，以满足随后到达的未完成 I/O 操作。

DUMMYUNIONNAME.Cancel.DUMMYUNIONNAME.FetchData.Length

不再需要的文件数据的长度（以字节为单位）。 请注意，这可能与相应提取中的 RequiredLength 匹配，但也可能是子集。 如果是子集，则仍然需要取消范围以外的数据，例如，以满足随后到达的未完成 I/O 操作。

DUMMYUNIONNAME.FetchData

DUMMYUNIONNAME.FetchData.Flags

可以将标志设置为以下值：

  • 如果由于以前由于同步提供程序不干净关闭或断电等原因而中断水化过程而调用回调，则设置CF_CALLBACK_FETCH_DATA_FLAG_RECOVER。
  • 如果回调因调用 CfHydratePlaceholder 而调用，则设置CF_CALLBACK_FETCH_DATA_FLAG_EXPLICIT_HYDRATION。

DUMMYUNIONNAME.FetchData.RequiredFileOffset

用于指定筛选器为满足未完成的 I/O 请求而绝对需要的文件数据范围的偏移量（以字节为单位）。

DUMMYUNIONNAME.FetchData.RequiredLength

筛选器为满足未完成的 I/O 请求而绝对需要的文件数据的长度（以字节为单位）。

DUMMYUNIONNAME.FetchData.OptionalFileOffset

偏移量（以字节为单位）作为一个提示提供，可以有效地提供给平台的更广泛的文件数据，以防同步提供程序倾向于提供较大区块中的数据。 通常，可选范围将是占位符中当前不存在的最大连续范围。 这是可选的，如果同步提供程序希望处理较大的数据段，则可以使用。

DUMMYUNIONNAME.FetchData.OptionalLength

长度（以字节为单位）作为一个提示提供，可以有效地提供给平台的更广泛的文件数据，以防同步提供程序倾向于提供较大区块中的数据。 通常，可选范围将是占位符中当前不存在的最大连续范围。 这是可选的，如果同步提供程序希望处理较大的数据段，则可以使用。

长度为 -1（表示为 CF_EOF）表示无穷大 (即到文件) 末尾。

同步提供程序不需要一次返回所需的所有数据。 同步提供程序也不要求返回所需范围或可选范围内的数据。 平台确保在任何情况下都不会因为无效 的CF_OPERATION_TYPE_TRANSFER_DATA 操作而修改/未同步的文件数据。 但是，返回的数据在偏移量和长度上必须对齐 4KB，除非返回的范围在文件末尾结束，在这种情况下，如果范围在文件末尾或超过文件末尾，则不需要将长度对齐 4KB。

DUMMYUNIONNAME.FetchData.LastDehydrationTime

有关云文件解除冻结的系统时间。 这是自 1601 年 1 月 1 日以来的 100 纳秒间隔计数。

DUMMYUNIONNAME.FetchData.LastDehydrationReason

CF_CALLBACK_DEHYDRATION_REASON枚举的成员，指定上次解除冻结文件的原因。

LastDehydrationReason 可以是下列值之一：

原因 说明
CF_CALLBACK_DEHYDRATE_REASON_NEVER 云文件在创建后从未冻结过。
CF_CALLBACK_DEHYDRATE_REASON_USER_MANUAL 用户显式解除冻结了云文件。
CF_CALLBACK_DEHYDRATE_REASON_SYSTEM_PERIODIC 平台根据用户定义的策略将云文件过期。
CF_CALLBACK_DEHYDRATE_REASON_SYSTEM_LOWSPACE 当此文件所在的卷上的磁盘空间不足时，平台会解除云文件冻结。
CF_CALLBACK_DEHYDRATE_REASON_SYSTEM_UPGRADE 平台在回收磁盘空间以升级 OS 时将此文件冻结。

DUMMYUNIONNAME.ValidateData

DUMMYUNIONNAME.ValidateData.Flags

数据验证标志。 如果回调因调用 CfHydratePlaceholder 而调用，则设置CF_CALLBACK_VALIDATE_DATA_FLAG_EXPLICIT_HYDRATION。

DUMMYUNIONNAME.ValidateData.RequiredFileOffset

用于指定要验证的文件数据范围的偏移量（以字节为单位）。

DUMMYUNIONNAME.ValidateData.RequiredLength

需要验证的文件数据范围的长度（以字节为单位）。 长度为 -1（表示为 CF_EOF）表示无穷大 (即到文件) 末尾。

同步提供程序不需要一次确认所需的所有数据。 同步提供程序也无需确认所需范围内的数据。 平台确保在任何情况下都不会因为无效 的CF_OPERATION_TYPE_ACT_DATA 操作而修改/未同步的文件数据。 但是，除非返回的范围在文件末尾结束，否则确认的数据在偏移量和长度上必须对齐 4KB，在这种情况下，如果范围在文件末尾或超过文件末尾，则不需要长度为 4KB。

DUMMYUNIONNAME.FetchPlaceholders

DUMMYUNIONNAME.FetchPlaceholders.Flags

此 Flags 值应设置为 CF_CALLBACK_FETCH_PLACEHOLDERS_FLAG_NONE。

DUMMYUNIONNAME.FetchPlaceholders.Pattern

一种标准 Windows 文件模式，可能包含通配符 (?、 *) 。 模式通常为 * ，但可能更具体。 同步提供程序应使用 CF_OPERATION_TYPE_TRANSFER_PLACEHOLDERS 开始传输目录中所有文件的占位符信息。 同步提供程序必须传输与模式匹配的所有占位符，但不一定是一次性传输，这是最低要求。 同步提供程序可能还会选择传输与模式不匹配的占位符。

DUMMYUNIONNAME.OpenCompletion

DUMMYUNIONNAME.OpenCompletion.Flags

占位符打开完成标志。 可以将其设置为以下两个标志之一：

  • 如果占位符元数据损坏，则设置CF_CALLBACK_OPEN_COMPLETION_FLAG_PLACEHOLDER_UNKNOWN。
  • 如果占位符元数据的版本较旧且不受支持，则设置CF_CALLBACK_OPEN_COMPLETION_FLAG_PLACEHOLDER_UNSUPPORTED。

DUMMYUNIONNAME.CloseCompletion

DUMMYUNIONNAME.CloseCompletion.Flags

占位符关闭完成标志。 如果占位符因关闭而被删除，则可以将其设置为 CF_CALLBACK_CLOSE_COMPLETION_FLAG_DELETED 。

DUMMYUNIONNAME.Dehydrate

DUMMYUNIONNAME.Dehydrate.Flags

占位符冻结标志。 如果解除冻结请求由系统后台服务发起，则可以将其设置为 CF_CALLBACK_DEHYDRATE_FLAG_BACKGROUND 。

DUMMYUNIONNAME.Dehydrate.Reason

Reason 是CF_CALLBACK_DEHYDRATION_REASON枚举的成员，用于指定占位符被冻结的原因。 可以为下列值之一：

原因 说明
CF_CALLBACK_DEHYDRATE_REASON_USER_MANUAL 用户显式要求解除云文件冻结。
CF_CALLBACK_DEHYDRATE_REASON_SYSTEM_INACTIVITY 平台根据用户定义的策略定期将云文件过期。
CF_CALLBACK_DEHYDRATE_REASON_SYSTEM_LOW_SPACE 平台在此云文件所在的卷上遇到磁盘空间不足的情况。
CF_CALLBACK_DEHYDRATE_REASON_SYSTEM_OS_UPGRADE 平台正在回收磁盘空间以升级 OS。

DUMMYUNIONNAME.DehydrateCompletion

DUMMYUNIONNAME.DehydrateCompletion.Flags

占位符解除冻结完成标志。 可以将其设置为以下值：

  • 如果解除冻结请求由系统后台服务发起，则设置CF_CALLBACK_DEHYDRATE_COMPLETION_FLAG_BACKGROUND。
  • 如果放置器在脱水请求之前水合，则设置CF_CALLBACK_DEHYDRATE_COMPLETION_FLAG_DEHYDRATED。

DUMMYUNIONNAME.DehydrateCompletion.Reason

Reason 是CF_CALLBACK_DEHYDRATION_REASON枚举的成员，它指定占位符被冻结的原因。 可以为下列值之一：

原因 说明
CF_CALLBACK_DEHYDRATE_REASON_USER_MANUAL 用户显式要求解除云文件冻结。
CF_CALLBACK_DEHYDRATE_REASON_SYSTEM_INACTIVITY 平台根据用户定义的策略定期将云文件过期。
CF_CALLBACK_DEHYDRATE_REASON_SYSTEM_LOW_SPACE 平台在此云文件所在的卷上遇到磁盘空间不足的情况。
CF_CALLBACK_DEHYDRATE_REASON_SYSTEM_OS_UPGRADE 平台正在回收磁盘空间以升级 OS。

DUMMYUNIONNAME.Delete

DUMMYUNIONNAME.Delete.Flags

占位符删除标志。 它设置为 CF_CALLBACK_DELETE_FLAG_NONE。

DUMMYUNIONNAME.DeleteCompletion

DUMMYUNIONNAME.DeleteCompletion.Flags

占位符删除完成标志。 它设置为 CF_CALLBACK_DELETE_COMPLETION_FLAG_NONE。

DUMMYUNIONNAME.Rename

DUMMYUNIONNAME.Rename.Flags

重命名占位符标志。 可以将其设置为以下值：

  • 如果占位符是目录，则设置CF_CALLBACK_RENAME_FLAG_IS_DIRECTORY。
  • 如果要重命名或移动的链接位于同步进程管理的同步根目录中，则设置CF_CALLBACK_RENAME_FLAG_SOURCE_IN_SCOPE。
  • 如果重命名或移动目标位于源路径的同一同步根目录中，则设置CF_CALLBACK_RENAME_FLAG_TARGET_IN_SCOPE。

DUMMYUNIONNAME.Rename.TargetPath

相对于卷的完整重命名/移动目标路径。

DUMMYUNIONNAME.RenameCompletion

DUMMYUNIONNAME.RenameCompletion.Flags

重命名完成占位符标志。 它设置为 CF_CALLBACK_RENAME_COMPLETION_FLAG_NONE。

DUMMYUNIONNAME.RenameCompletion.SourcePath

相对于卷的完整源链接路径。

要求

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

另请参阅

CfHydratePlaceholder

CF_CALLBACK_TYPE

CF_CALLBACK_DEHYDRATION_REASON