cfRegisterSyncRoot 函式 (cfapi.h)

發行項
02/26/2024

執行一次同步根註冊，讓同步提供者可以宣告整個目錄樹狀結構，以同步 處理RootPath 做為自己的管理。

語法

HRESULT CfRegisterSyncRoot(
  [in] LPCWSTR                    SyncRootPath,
  [in] const CF_SYNC_REGISTRATION *Registration,
  [in] const CF_SYNC_POLICIES     *Policies,
  [in] CF_REGISTER_FLAGS          RegisterFlags
);

參數

[in] SyncRootPath

要註冊之同步根目錄的路徑。

[in] Registration

包含同步提供者和要註冊之同步根目錄的相關信息。

ProviderName 和 ProviderVersion 是使用者面向的字串，每個字串長度上限為 255 個字元。

SyncRootIdentity 和 FileIdentity 都是選擇性的，若未提供對應的緩衝區長度，也應該設定為 0 。它們是同步提供者持續關聯任意數據與同步根目錄的方法。

平臺會在同步提供者的任何回呼中，將 SyncRootIdentity 提供給同步提供者。只有在回呼的主旨是同步根目錄本身時，才會提供同步根 FileIdentity Blob。

這項功能僅供同步提供者方便使用，而且這兩個 Blob 在同步提供者之外沒有特殊意義。

FileIdentity 的最大允許長度為 4KB，而 SyncRootIdentity 的最大允許長度為 64KB。超過長度上限時，API 會失敗 ，並ERROR_INVALID_PARAMETER 。

ProviderId 是用來識別特定同步提供者的 GUID。此為選用項目。如果未提供，平臺會使用 ProviderName 字串的 MD5 哈希產生 GUID。此資訊僅用於遙測，因此平臺可以更有效率且更精確地將相同同步提供者的活動相互關聯，即使同步提供者向不同的 ProviderName 字串註冊同步根。建議同步提供者一律為同步處理產品的所有版本提供相同的 GUID， (s) 。不過，同步提供者可以自由選擇不同的 ProviderName 字串，以獲得最佳用戶體驗。

[in] Policies

要註冊之同步根目錄的原則。

[in] RegisterFlags

註冊先前和新的同步根目錄的旗標。

旗標	描述
CF_REGISTER_FLAG_UPDATE	同步提供者可以傳遞 CF_REGISTER_FLAG_UPDATE ，以重新註冊先前註冊的同步根身分識別和原則。
CF_REGISTER_FLAG_DISABLE_ON_DEMAND_POPULATION_ON_ROOT	隨選目錄/資料夾母體擴展行為是由母體原則全域控制。此旗標可讓同步提供者只針對同步根本身退出退出隨選母體擴展行為，同時保留同步根目錄下所有其他目錄的隨選母體擴展。當同步提供者想要預先填入同步根目錄的立即子檔案/目錄時，這非常有用。
CF_REGISTER_FLAG_MARK_IN_SYNC_ON_ROOT	此旗標可讓同步提供者在註冊時同時註冊同步根目錄。替代方法是稍後在同步根目錄上呼叫 CfSetInSyncState 。

傳回值

如果函式成功，則會傳 S_OK回。否則，它會傳回 HRESULT 錯誤碼。

備註

這可以在同步提供者安裝時間、第一次為個別使用者設定，或當使用者設定另一個同步根 (時，如果支援此案例) 。

注意

不允許兩個同步根樹重疊。因為文件系統禁止目錄硬式連結，所以兩個同步根重疊的唯一方式是，如果兩個同步根具有直接上階/子系關聯性，平臺負責持續記住在指定磁碟區上註冊的所有同步根目錄，並無法嘗試建立重疊的同步根目錄。

同步提供者 應該具有WRITE_DATA 或 WRITE_DAC 要註冊的同步根目錄存取權，否則註冊將會失敗 並ERROR_CLOUD_FILE_ACCESS_DENIED。

同步提供者應該提供註冊記錄，其中包含同步提供者本身的各種身分識別和要註冊的同步根目錄、平臺用來根據每個同步根目錄調整其行為的一組原則，以及一組註冊旗標，以允許同步提供者更精細地控制註冊作業。

除非明確呼叫為選擇性，否則所有欄位都是必要欄位，但未提供這些欄位會導致 API 呼叫失敗，並出現無效的參數錯誤。

預期未來延伸的所有結構都是從 StructSize 欄位開始。呼叫端負責結構大小的精確會計。

平臺目前支援五種類型的原則：

凍結原則

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

主要凍結原則有四個不同的值：

原則	描述
ALWAYS_FULL	平臺會失敗 (，ERROR_CLOUD_FILE_INVALID_REQUEST) 任何可能導致未完全凍結佔位符的佔位符作業失敗，其中包括 CfCreatePlaceholders、 CfDehydratePlaceholder、 CfUpdatePlaceholder 與 dehydrate 選項，以及具有解除凍結選項的 CfConvertToPlaceholder 。
FULL	平台會允許佔位元元解除凍結。當平臺偵測到已凍結佔位符的存取權時，它可確保佔位元的完整內容可在本機使用，再完成使用者 IO 要求，即使要求只要求 1 個字節也一樣。
進步	平台會允許佔位元元解除凍結。當平臺偵測到解除凍結佔位符的存取權時，它會在判斷從同步提供者收到足夠的數據時，立即完成使用者 IO 要求。不過，平台承諾會從背景的同步提供者繼續要求佔位元元中剩餘的內容，直到佔位符的完整內容可在本機使用，或佔位元上的最後一個使用者句柄關閉為止。注意：加入加入 PROGRESSIVE 的同步提供者可能不會假設凍結回呼會依序從位移 `0`抵達。換句話說，同步提供者與 PROGRESSIVE 原則預期會在佔位元上處理隨機搜尋。
PARTIAL	此原則與 PROGRESSIVE 非常類似，唯一的差異在於背景中缺少連續凍結。

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

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

母體原則

母體原則可讓同步提供者控制平台應該如何建立目錄和檔案 (占位元命名空間) 。目前沒有定義修飾詞的主要原則有三個：

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

InSync 追蹤原則

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

Hardlink 原則

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

佔位元管理原則

根據預設，只有同步提供者可以在同步根目錄中執行佔位元元管理作業。只有在同步根目錄非使用中時，非同步提供者進程才能執行佔位元管理作業，亦即當同步根未由任何同步提供者連線時。啟用時，這些原則允許非同步提供者進程在作用中同步根目錄中執行個別的佔位元元管理作業。 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	在註冊期間指定此原則時，任何進程都可以藉由呼叫 CfUpdatePlaceholder 來更新作用中同步根目錄中的佔位符。

注意

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

規格需求

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