CF_SYNC_POLICIES 結構 (cfapi.h)

  • 發行項

定義同步根目錄所使用的同步處理原則。

語法

typedef struct CF_SYNC_POLICIES {
  ULONG                            StructSize;
  CF_HYDRATION_POLICY              Hydration;
  CF_POPULATION_POLICY             Population;
  CF_INSYNC_POLICY                 InSync;
  CF_HARDLINK_POLICY               HardLink;
  CF_PLACEHOLDER_MANAGEMENT_POLICY PlaceholderManagement;
} CF_SYNC_POLICIES;

成員

StructSize

結構的大小 CF_SYNC_POLICIES 。

Hydration

凍結原則可讓同步提供者控制平臺應如何凍結佔位符檔案。 它包含主要原則和一組原則修飾詞。

主要原則有四個可能的值：

原則 描述
ALWAYS_FULL 選取時ALWAYS_FULL，平臺將會失敗，並出現 HRESULT ERROR_CLOUD_FILE_INVALID_REQUEST，任何可能導致未完全凍結佔位符的佔位符作業，包括 CfCreatePlaceholders、CfDehydratePlaceholder、CfUpdatePlaceholder 與 dehydrate 選項，以及具有解除凍結選項的CfConvertPlaceholder。
FULL 選取時 FULL ，平台會允許解除凍結佔位元。 當平臺偵測到解除凍結佔位符的存取權時，它可確保佔位元的完整內容可在本機使用，再完成使用者 IO 要求，即使要求只要求 1 個字節也一樣。
進步 選取時 PROGRESSIVE ，平台會允許解除凍結佔位元。 當平臺偵測到解除凍結佔位符的存取權時，它會在判斷從同步提供者收到足夠的數據時立即完成使用者 IO 要求。 不過，平台承諾從背景的同步提供者繼續要求佔位元中的剩餘內容，直到佔位元的完整內容可在本機使用，或佔位元上的最後一個使用者句柄關閉為止。

請注意，加入加入 PROGRESSIVE 的同步提供者可能不會假設凍結回呼會循序從位移 0 抵達。 換句話說，同步提供者與 PROGRESSIVE 原則預期會在佔位元上處理隨機搜尋。
PARTIAL 此 PARTIAL 原則非常類似於 PROGRESSIVE。 這兩者的唯一差異在於在背景 PARTIAL 中缺少原則的持續凍結。

目前支援三個原則修飾詞： VALIDATION_REQUIRED、 STREAMING_ALLOWED和 AUTO_DEHYDRATION_ALLOWED。 一般而言，只要組合不是自我衝突，修飾詞就可以混合並與任何主要原則和其他原則修飾詞進行比對。

原則修飾詞 Description
VALIDATION_REQUIRED 此原則修飾詞可為同步提供者提供兩項保證。 首先，它保證同步提供者傳回的數據一律會保存在磁碟上，再將它傳回給用戶應用程式。 其次，它可讓同步提供者擷取先前傳回給平臺的相同數據，並驗證其完整性。 只有在同步提供者成功確認完整性時，平臺才會完成使用者 IO 要求。 此修飾詞可協助支援端對端數據完整性，但代價是額外的磁碟 IO。
STREAMING_ALLOWED 此原則修飾詞會授與平台許可權，以不儲存同步提供者在本機磁碟上傳回的任何數據。 此原則修飾詞與 VALIDATION_REQUIRED互斥。 指定這兩個旗標時，API 會失敗 ERROR_INVALID_PARAMETER 。
AUTO_DEHYDRATION_ALLOWED 此原則修飾詞會授與平臺解除凍結同步處理雲端檔案佔位符的許可權，而不需要同步提供者的協助。 如果沒有此旗標，則不允許平臺直接呼叫 CfDehydratePlaceholder 。 相反地，解除凍結雲端檔案佔位符的唯一支援方式是清除檔案的釘選屬性，並設定檔案的未釘選屬性。 然後，同步處理引擎會在收到兩個屬性上的目錄變更通知之後，以異步方式執行實際的解除凍結。 指定此旗標時，平臺將可直接在任何同步處理的雲端檔案佔位符上叫用 CfDehydratePlaceholder 。 建議同步提供者支持自動解除凍結。
ALLOW_FULL_RESTART_HYDRATION 此原則修飾詞會授與平台許可權，以在攔截AV篩選程式嘗試掃描檔案時同步凍結檔案。 想要使用 RestartHydration 從 FetchData 回呼變更 fileSize 的同步提供者，必須選擇加入原則ALLOW_FULL_RESTART_HYDRATION，以避免使用防病毒軟體和防病毒軟體嘗試掃描檔案的可能死結，以及嘗試使用 RestartHydration 進行變更fileSize的提供者。

注意：只有當從 CfGetPlatformInfo 取得的 為0x500或更新版本時PlatformVersion.IntegrationNumber，才支援此修飾詞。

Population

母體擴展原則可讓同步提供者控制平臺應如何建立佔位符命名空間，以及目錄和檔案。 目前有三個主要原則未定義修飾詞：

原則 描述
ALWAYS_FULL 選取時 ALWAYS_FULL ，平臺會假設完整名稱空間一律可在本機使用。 它永遠不會將任何目錄列舉要求轉送至同步提供者。
FULL FULL使用母體擴展原則時，當平臺偵測到未填入目錄的存取權時，它會在完成使用者要求之前，要求同步提供者傳回目錄下的所有專案。
PARTIAL PARTIAL使用母體擴展原則時，當平臺偵測到未完全填入目錄的存取權時，它只會向同步提供者要求使用者應用程式所需的專案。

InSync

此 InSync 原則可讓同步提供者控制平臺何時應清除佔位元上的同步處理狀態。 除了一律清除任何數據修改的同步處理之外，平臺目前可以在 ReadOnly、 System 和 Hidden) (和 CreateTime 和 LastWriteTime) (三個檔案屬性的任何組合變更時清除同步處理。 這些原則可以個別套用至檔案和目錄。

HardLink

根據預設，平台不允許在任何佔位元上建立硬式連結。 不過，能夠處理硬式連結的同步提供者可以指示平臺透過 ALLOWED 原則啟用支援。 透過此原則，只要鏈接位於相同的同步根目錄或沒有同步根目錄下，應用程式就可以建立與文件系統支援的一樣多硬式連結。 當引進第一個同步根連結時，平臺會強制解除凍結佔位符，並在移除其最後一個同步根連結時，將佔位符還原為一般檔案。 與原則不相容的硬連結建立將會因為 HRESULT ERROR_CLOUD_FILES_INCOMPATIBLE_HARDLINKS而失敗。 與原則不相容的佔位符作業也會失敗 ERROR_CLOUD_FILES_INCOMPATIBLE_HARDLINKS。

PlaceholderManagement

根據預設，只有同步提供者可以在同步根目錄中執行佔位元元管理作業。 非同步提供者進程只有在同步根目錄處於非作用中 (時，才能執行佔位元元管理作業，亦即當沒有同步提供者連線到同步根時。) 啟用時，允許非同步提供者進程在作用中的同步根目錄中執行個別的佔位符管理作業。 CF_PLACEHOLDER_MANAGEMENT_POLICY_DEFAULT 是默認原則，只允許連線的同步提供者執行任何佔位元元管理作業。 下列三個原則可以任意組合來指定：

原則 描述
CF_PLACEHOLDER_MANAGEMENT_POLICY_CREATE_UNRESTRICTED 在註冊期間指定此原則時，任何進程都可以藉由呼叫 CfCreatePlaceholders，在作用中的同步根目錄中建立佔位符。
CF_PLACEHOLDER_MANAGEMENT_POLICY_CONVERT_UNRESTRICTED 在註冊期間指定此原則時，任何進程都可以呼叫 CfConvertToPlaceholder，將作用中同步根目錄內的檔案或目錄轉換成佔位符。
CF_PLACEHOLDER_MANAGEMENT_POLICY_UPDATE_UNRESTRICTED 在註冊期間指定此原則時，任何進程都可以透過 API CfUpdatePlaceholder 更新作用中同步根目錄中的佔位符。

注意

只有在從 CfGetPlatformInfo 取得的 為0x310或更新版本時PlatformVersion.IntegrationNumber，才支持這些旗標。

規格需求

需求 值
最低支援的用戶端 Windows 10 版本 1709 [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2016 [僅限傳統型應用程式]
標頭 cfapi.h

另請參閱

CfCreatePlaceholders

CfConvertToPlaceholder

CfGetPlatformInfo