CfUpdatePlaceholder 函式 (cfapi.h)
此 API 會變更現有佔位元的特性。 最可能使用此 API 的時機是在雲端中修改檔案，而同步提供者想要將該修改的效果納入佔位元。 為了支援此案例，呼叫端可能會傳入新的文件系統元數據， (時間戳、檔案大小等 ) 套用，以及/或新的 FileIdentity Blob。
語法
HRESULT CfUpdatePlaceholder(
[in] HANDLE FileHandle,
[in, optional] const CF_FS_METADATA *FsMetadata,
[in, optional] LPCVOID FileIdentity,
[in] DWORD FileIdentityLength,
[in, optional] const CF_FILE_RANGE *DehydrateRangeArray,
[in] DWORD DehydrateRangeCount,
[in] CF_UPDATE_FLAGS UpdateFlags,
[in, out, optional] USN *UpdateUsn,
[in, out, optional] LPOVERLAPPED Overlapped
);
參數
[in] FileHandle
FileHandle 是要更新其元數據之檔案或目錄的句柄。 在檔案的情況下，如果呼叫端也想要同時將檔案解除凍結，或數據損毀，則呼叫端必須取得檔案的獨佔句柄。 若要將對使用者應用程式的影響降到最低，強烈建議呼叫者透過 CfOpenFileWithOplock 取得適當的 oplock (的獨佔性) ，而不是使用無共用句柄。
[in, optional] FsMetadata
FsMetadata 包含要更新之佔位元的相關文件系統元數據，包括所有時間戳、檔案屬性和檔案大小， (目錄) 的選擇性檔案大小。 這是選擇性欄位。 如果未提供，這些欄位都會在呼叫之後保持不變。
0時間戳欄位中的值 (CreationTime、LastAccessTime、LastWriteTime 和 ChangeTime) 表示檔案上目前的時間戳沒有任何變更。0FileAttributes 中的值表示檔案上目前檔案屬性沒有任何變更。- FileSize 中沒有特殊值;
0FileSize 中的值會將檔案大小截斷為0。
[in, optional] FileIdentity
FileIdentity 是使用者模式緩衝區，其中包含呼叫端所提供的不透明檔案或目錄資訊。 FileIdentity Blob 的大小不應超過 4 KB。 FileIdentity 會在所有回呼中傳回至同步提供者。 如果不需要更新，或呼叫端想要從要更新的佔位符中移除 FileIdentity Blob，這是選擇性的。
[in] FileIdentityLength
FileIdentity 的長度，以位元組為單位。
[in, optional] DehydrateRangeArray
此陣列會指定現有佔位元的範圍，這些佔位元在更新之後將不再被視為有效。
此參數最簡單的用法是傳遞單一範圍，告知平臺整個位元組的數據範圍現在無效。 這個參數的較複雜用法是提供一系列的離散範圍，以視為無效。 這表示同步提供者可以區分子檔案層級上的變更。 所有位移和長度都應該 PAGE_SIZE 對齊。 平台可確保指定的所有範圍都會在更新過程中解除凍結。 如果任何範圍的解除凍結失敗，API 將會失敗，而不是導致損毀的檔案內容。
注意
傳遞具有 Offset 0 和 Length CF_EOF 的單一範圍將會使整個檔案失效 - 這與改為傳遞旗標的效果相同 CF_UPDATE_FLAG_DEHYDRATE 。 此外，傳遞 CF_UPDATE_FLAG_DEHYDRATE 會導致 DehydrateRangeArray 以無訊息方式卸除
[in] DehydrateRangeCount
佔位元數據的一系列離散 DehydrateRangeArray 分割區計數。
[in] UpdateFlags
更新佔位元的旗標。 UpdateFlags 可以設定為下列值：
| 旗標 | 描述 |
|---|---|
| CF_UPDATE_FLAG_VERIFY_IN_SYNC | 如果目前未在佔位元元上設定 IN_SYNC 屬性，更新將會失敗。 這是為了避免將雲端變更同步處理到本機佔位元元，以及佔位符的數據流在本機修改之間的競爭。 |
| CF_UPDATE_FLAG_MARK_IN_SYNC | 平臺會在成功更新佔位元元作業時，將佔位元符標示為同步處理。 |
| CF_UPDATE_FLAG_DEHYDRATE | 僅適用於檔案。 指定時，平臺會在成功更新佔位符之後解除凍結檔案。 呼叫端必須在指定此旗標或數據損毀時取得獨佔句柄。 請注意，平臺不會驗證句柄的獨佔性。 |
| CF_UPDATE_FLAG_ENABLE_ON_DEMAND_POPULATION | 僅適用於目錄。 指定時，它會標示部分填入更新的佔位元目錄，讓未來存取它會導致 FETCH_PLACEHOLDERS 回呼傳送給同步提供者。 |
| CF_UPDATE_FLAG_DISABLE_ON_DEMAND_POPULATION | 僅適用於目錄。 指定時，它會標示已完整填入更新的佔位元目錄，讓平台處理任何未來的存取權，而不會對同步提供者進行任何回呼。 |
| CF_UPDATE_FLAG_REMOVE_FILE_IDENTITY | FileIdentity 和 FileIdentityLength 會被忽略，而且平臺會在成功更新呼叫時移除佔位符上的現有檔案識別 Blob。 |
| CF_UPDATE_FLAG_CLEAR_IN_SYNC | 平臺會在成功更新佔位元元作業時，將佔位元符標示為未同步。 |
| CF_UPDATE_FLAG_REMOVE_PROPERTY | 平臺會移除佔位元上所有現有的外部屬性。 |
| CF_UPDATE_FLAG_PASSTHROUGH_FS_METADATA | 平臺會將 CF_FS_METADATA 傳遞至文件系統，而不需要任何篩選;否則，平臺會略過設定其值為 0的任何欄位。 |
| CF_UPDATE_FLAG_ALWAYS_FULL | 僅適用於佔位符檔案。 指定時，要更新的佔位元一律會標示為已滿。 一旦凍結，任何嘗試將這類佔位符檔案解除凍結將會失敗，並出現錯誤碼 ERROR_CLOUD_FILE_DEHYDRATION_DISALLOWED。 |
| CF_UPDATE_FLAG_ALLOW_PARTIAL | 僅適用於佔位符檔案。 指定時，佔位符檔案上的一律完整狀態會清除，因此可再次解除凍結。 指定此旗標以及 CF_UPDATE_FLAG_ALWAYS_FULL 並傳回錯誤碼 ERROR_CLOUD_FILE_INVALID_REQUEST 結果無效。 |
[in, out, optional] UpdateUsn
在輸入時， UpdateUsn 會指示平臺只有在檔案仍然有與傳入的相同 USN 值時，才執行更新。 這與 CF_UPDATE_FLAG_VERIFY_IN_SYNC 類似，但也包含本機元數據變更。 將指標傳遞至輸入上的USN值 0 ，與傳遞 NULL 指標相同。
傳回時， UpdateUsn 會在執行更新動作之後收到最終USN值。
[in, out, optional] Overlapped
當指定並結合異步 FileHandle 時， 重疊 可讓平臺以異步方式執行 CfUpdatePlaceholder 呼叫。 如需詳細資訊，請參閱。
如果未指定，不論句柄的建立方式為何，平臺都會同步執行 API 呼叫。
傳回值
如果函式成功，則會傳 S_OK回 。 否則，它會傳回 HRESULT 錯誤碼。
備註
若要更新佔位元：
- 要更新的佔位元必須包含在已註冊的同步根樹狀結構中;它可以是同步根目錄本身或任何子系目錄;否則，呼叫將會因為 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 |