cfCreatePlaceholders 函式 (cfapi.h)

在同步根目錄樹狀結構下建立一或多個新的佔位元檔案或目錄。

語法

HRESULT CfCreatePlaceholders(
  [in]      LPCWSTR                    BaseDirectoryPath,
  [in, out] CF_PLACEHOLDER_CREATE_INFO *PlaceholderArray,
  [in]      DWORD                      PlaceholderCount,
  [in]      CF_CREATE_FLAGS            CreateFlags,
  [out]     PDWORD                     EntriesProcessed
);

參數

[in] BaseDirectoryPath

建立佔位元之本機目錄的路徑。 指定路徑時，請記住下列事項：

• 此路徑必須包含在已註冊的同步根樹狀結構中。 它可以是同步根目錄本身或任何子系目錄。 否則，呼叫將會因為 STATUS_CLOUD_FILE_NOT_UNDER_SYNC_ROOT而失敗。
• 同步根目錄必須向未 CF_HYDRATION_POLICY_ALWAYS_FULL的有效凍結原則註冊，否則呼叫將會失敗併產生 STATUS_CLOUD_FILE_NOT_SUPPORTED。
• 呼叫端必須具有 WRITE_DATA 或 WRITE_DAC 存取即將建立佔位元的基底目錄。 否則作業將會因為 STATUS_CLOUD_FILE_ACCESS_DENIED而失敗。

[in, out] PlaceholderArray

成功建立時， PlaceholderArray 會包含最終的USN值和 STATUS_OK 訊息。 傳回時，此陣列包含 HRESULT 值，描述是否建立佔位元。 PlaceholderArray 指向要建立的佔位符陣列，相對於 BaseDirectoryPath。 陣列中的每個項目都包含下列欄位：

• RelativeFileName 是要建立的檔案和目錄之子佔位符的名稱。
• FsMetadata 包含有關要建立之佔位符的文件系統元數據，包括所有時間戳、檔案屬性和檔案大小， (目錄) 選擇性 。
• FileIdentity 和 FileIdentityLength 描述使用者模式緩衝區，其中包含同步提供者所提供的不透明檔案資訊。 FileIdentity Blob 不應超過定義為大小為 4KB) CF_PLACEHOLDER_MAX_FILE_IDENTITY_LENGTH (。 FileIdentity 會傳回所有回呼中的同步提供者。 這是檔案的必要欄位。

同步提供者可以根據每個佔位元選擇下列旗標或組合：

• CF_PLACEHOLDER_CREATE_FLAG_DISABLE_ON_DEMAND_POPULATION - 此旗標僅適用於子佔位元目錄。 當旗標存在時，新建立的子佔位元目錄會被視為在其本機存在所有子系，因此未來存取它將不會觸發任何 FETCH_PLACEHOLDERS回 呼。 當旗標不存在時，新建立的佔位元目錄會被視為部分，而未來的存取將會觸發 FETCH_PLACEHOLDERS。
• CF_PLACEHOLDER_CREATE_FLAG_MARK_IN_SYNC - 此旗標適用於佔位元檔案和目錄。 出現此旗標時，新建立的佔位元將會標示為同步處理，作為 TRANSFER_PLACEHOLDERS 作業的一部分。
• CF_PLACEHOLDER_CREATE_FLAG_ALWAYS_FULL - 此旗標只會在佔位符檔案上強制執行。 它可以在佔位元目錄上設定，但沒有任何作用。 當此旗標存在時，新建立的佔位元將會標示為永遠已滿。 一旦凍結，任何嘗試解除凍結這類檔案佔位元將會失敗，並出現錯誤碼 ERROR_CLOUD_FILE_DEHYDRATION_DISALLOWED。

[in] PlaceholderCount

PlaceholderArray 中的佔位元計數。

[in] CreateFlags

用於設定佔位元建立的旗標。 CreateFlags 可以設定為下列值：

• CF_CREATE_FLAG_NONE 是預設模式，即使發生錯誤，API 也會處理陣列中的所有專案。
• CF_CREATE_FLAG_STOP_ON_ERROR 會導致 API 在建立佔位元失敗時立即傳回。 在此情況下，API 會傳回失敗碼。

[out] EntriesProcessed

已處理的項目數目，包括失敗的專案。 如果 CreateFlags 中未指定CF_CREATE_FLAG_STOP_ON_ERROR，API 會傳回遇到的第一個失敗碼，但會繼續處理盡可能多的專案;接著，呼叫端必須檢查陣列，以查看 () 失敗的佔位元建立。

傳回值

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

備註

相較於使用 CreateFile 建立新檔案，然後使用 CfConvertToPlaceholder 將它轉換成佔位元，最好使用此函式建立佔位符;這兩者都適用於效率，因為它會消除檔案不是佔位元的時間範圍。 函式也可以在批次中建立多個檔案或目錄，這也可以更有效率。

當從雲端向下同步處理檔案或目錄到用戶端，或從雲端同步處理新建立的單一檔案或目錄時，此函式很有用。

規格需求

另請參閱

CreateFile

CfConvertToPlaceholder