cfConvertToPlaceholder 函式 (cfapi.h)
將同步根目錄樹狀結構下的現有非佔位元檔案或目錄轉換為佔位元。 例如，在用戶端上出現新的本機檔案或目錄之後，同步提供者已完成同步處理至雲端，這非常有用。 請注意，沒有參數可用來傳入文件系統元數據 (時間戳、檔案大小等。) ;這些檔案會逐字從本機檔案取得。
語法
HRESULT CfConvertToPlaceholder(
[in] HANDLE FileHandle,
[in, optional] LPCVOID FileIdentity,
[in] DWORD FileIdentityLength,
[in] CF_CONVERT_FLAGS ConvertFlags,
[out, optional] USN *ConvertUsn,
[in, out, optional] LPOVERLAPPED Overlapped
);
參數
[in] FileHandle
要轉換之檔案或目錄的句柄。
[in, optional] FileIdentity
使用者模式緩衝區，其中包含呼叫端所提供的不透明檔案或目錄資訊。 如果呼叫端未同時解除凍結檔案，或呼叫端正在轉換目錄，則為選擇性。 FileIdentity 會傳回所有回呼中的同步提供者。 大小不能超過 4KB。
[in] FileIdentityLength
FileIdentity 的長度，以位元組為單位。
[in] ConvertFlags
佔位元轉換旗標。 ConvertFlags 可以設定為下列值：
| 旗標 | 描述 |
|---|---|
| CF_CONVERT_FLAG_MARK_IN_SYNC | 如果指定這個值，平臺會在成功轉換檔案時，將已轉換的佔位符標示為與雲端同步。 |
| CF_CONVERT_FLAG_DEHYDRATE | 這僅適用於檔案。 當指定時，平臺會在成功將檔案轉換成佔位元元之後將檔案解除凍結。 呼叫端必須在指定這個旗標或數據損毀時取得獨佔句柄。 請注意，平臺不會驗證句柄的獨佔性。 |
| CF_CONVERT_FLAG_ENABLE_ON_DEMAND_POPULATION | 這僅適用於目錄。 指定時，它會標示部分填入已轉換的佔位元目錄，讓未來存取它會導致傳送給同步提供者 FETCH_PLACEHOLDERS 回呼。 |
| CF_CONVERT_FLAG_ALWAYS_FULL | 這隻適用於佔位符檔案。 一旦檔案轉換為具有此旗標的佔位元元，佔位元就會一律標示為完整。 任何將這類佔位元解除凍結的嘗試都會失敗，並出現錯誤碼 ERROR_CLOUD_FILE_DEHYDRATION_DISALLOWED。 |
| CF_CONVERT_FLAG_FORCE_CONVERT_TO_CLOUD_FILE | 指定時，平臺可讓同步處理引擎以不可部分完成的方式轉換非雲端檔案佔位元， (另一個重新剖析卷標/數據) 至雲端檔案佔位符。 請注意，API 通常會無法將任何非佔位元檔案轉換成佔位元。 組合 (CF_CONVERT_FLAG_FORCE_CONVERT_TO_CLOUD_FILE |當 某些提供者從另一個平臺移轉至雲端檔案平臺，而且想要將較舊平臺上的已凍結佔位元轉換為雲端檔案平臺上不可部分凍結的佔位元元時，CF_CONVERT_FLAG_DEHYDRATE) 特别有用。 只應該傳遞此旗標，以將完整佔位元轉換為雲端檔案佔位元。 如果較舊的平臺將完整檔案實作為一般、非佔位符檔案，則不需要此旗標。 在目錄上傳遞此旗標也會將目錄轉換成雲端檔案，但 DEHYDRATE 旗標不適用於目錄。 即使已使用 CfRegisterSyncRoot 指定原則CF_PLACEHOLDER_MANAGEMENT_POLICY_CONVERT_TO_UNRESTRICTED，也只允許已註冊/連線至雲端檔案同步根目錄的進程指定此旗標。 注意：只有在從 CfGetPlatformInfo 取得的 為 0x500 或更新版本時PlatformVersion.IntegrationNumber，才支援旗標。 |
[out, optional] ConvertUsn
指定時，這是執行轉換動作之後的最終USN值。
[in, out, optional] Overlapped
當指定並結合異步 FileHandle 時， 重疊 可讓平臺以異步方式執行 CfConvertToPlaceholder 呼叫。 如需詳細資訊 ，請參閱 。
如果未指定，不論句柄的建立方式為何，平臺都會同步執行 API 呼叫。
傳回值
如果函式成功，則會傳 S_OK回 。 否則，它會傳回 HRESULT 錯誤碼。
備註
在檔案案例中，如果呼叫端也想要同時解除凍結檔案，或可能發生數據損毀，則呼叫端必須取得檔案的獨佔句柄。 若要將對使用者應用程式的影響降到最低，強烈建議呼叫者透過 CfOpenFileWithOplock) ，使用適當的 oplock (取得獨佔性，而不是使用無共用句柄。
若要轉換佔位元：
- 要轉換的檔案或目錄必須包含在已註冊的同步根樹中;它可以是同步根目錄本身或任何子系目錄;否則， 使用 HRESULT (ERROR_CLOUD_FILE_NOT_UNDER_SYNC_ROOT) 失敗的 呼叫。
- 如果要求解除凍結，則必須向未 CF_HYDRATION_POLICY_ALWAYS_FULL的有效凍結原則註冊同步根目錄;否則，呼叫將會因為 HRESULT (ERROR_CLOUD_FILE_NOT_SUPPORTED) 而失敗。
- 如果要求解除凍結，則佔位元元不得固定在本機，或呼叫失敗， 且 HRESULT (ERROR_CLOUD_FILE_PINNED) 。
- 如果要求解除凍結，佔位元必須處於同步狀態，否則會因為 HRESULT (ERROR_CLOUD_FILE_NOT_IN_SYNC) 而失敗呼叫。
- 呼叫端必須具有要轉換之檔案或目錄 的WRITE_DATA 或 WRITE_DAC 存取權。 否則作業將會因為 HRESULT (ERROR_CLOUD_FILE_ACCESS_DENIED) 而失敗。
如果 API 以異步方式使用重疊時傳回HRESULT_FROM_WIN32 (ERROR_IO_PENDING) ，則呼叫端可以使用 GetOverlappedResult 等候。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows 10 1709 版 [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows Server 2016 [僅限傳統型應用程式] |
| 目標平台 | Windows |
| 標頭 | cfapi.h |
| 程式庫 | CldApi.lib |
| Dll | CldApi.dll |