CF_CALLBACK_PARAMETERS 結構 (cfapi.h)

發行項
03/18/2023

此結構包含回呼特定參數，例如檔案位移、長度、旗標等。

語法

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。
如果使用者要求因使用者明確終止從應用程式起始的下載快顯通知解除凍結，就會設定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

共用方式為

CF_CALLBACK_PARAMETERS 結構 (cfapi.h)

語法

成員

規格需求

另請參閱

意見反應

其他資源