PrjUpdateFileIfNeeded 函數 （projectedfslib.h）

可讓提供者更新已在本機檔案系統上快取的專案。

語法

HRESULT PrjUpdateFileIfNeeded(
  [in]            PRJ_NAMESPACE_VIRTUALIZATION_CONTEXT namespaceVirtualizationContext,
  [in]            PCWSTR                               destinationFileName,
  [in]            const PRJ_PLACEHOLDER_INFO           *placeholderInfo,
  [in]            UINT32                               placeholderInfoSize,
  [in, optional]  PRJ_UPDATE_TYPES                     updateFlags,
  [out, optional] PRJ_UPDATE_FAILURE_CAUSES            *failureReason
);

參數

[in] namespaceVirtualizationContext

虛擬化執行個體的不透明控制碼。

[in] destinationFileName

以 Null 結尾的 Unicode 字串，指定相對於虛擬化根目錄的路徑，以至要更新的檔案或目錄。

[in] placeholderInfo

指向 PRJ_PLACEHOLDER_INFO 緩衝區的指標，其中包含檔案或目錄的更新中繼資料。

如果 placeholderInfo-VersionInfo.ContentID> 包含的內容識別碼與檔案/目錄上已有的內容識別碼相同的內容識別碼，則呼叫會成功，而且不會發生任何更新。 否則，如果呼叫成功，placeholderInfo-VersionInfo.ContentID> 會取代檔案上現有的內容識別碼。

[in] placeholderInfoSize

placeholderInfo 所指向的緩衝區大小 （以位元組為單位）。

[in, optional] updateFlags

控制更新的旗標。

如果專案是已變更預留位置、完整檔案或標記，而且提供者未指定適當的旗標 （） ，則此常式將無法更新預留位置

[out, optional] failureReason

選擇性指標，用於接收描述更新失敗原因的程式碼。

返回值

如果傳回 HRESULT_FROM_WIN32 （ERROR_FILE_SYSTEM_VIRTUALIZATION_INVALID_OPERATION） 錯誤，則更新會因為項目的狀態和 updateFlags 的值而失敗。 failureReason，如果指定，則會描述失敗的原因。

備註

如果提供者的支援存放區中專案的資訊已變更，而且更新應該反映在本機檔案系統中快取的專案中，則提供者會使用此常式來更新本機檔案系統中的專案。

無法在虛擬檔案/目錄上呼叫此常式。 如果要更新的檔案/目錄處於「預留位置」以外的任何狀態，提供者必須在 updateFlags 參數中指定適當的PRJ_UPDATE_TYPES值組合。 這有助於防止意外遺失資料，因為從此常式成功傳回時，專案會成為具有更新中繼資料的預留位置;自建立預留位置以來已變更的任何中繼資料，或其中包含的任何檔案資料都會被捨棄。

提供者會使用本機檔案系統作為其管理項目的快取。 項目 （檔案或目錄） 可以處於本端檔案系統上的六種狀態之一。

虛擬 - 專案不存在於磁碟本機上。 它是在其父目錄列舉期間投影的，即合成的。 虛擬專案會與磁碟上可能存在的任何專案合併，以呈現父目錄的完整內容。

預留位置 - 對於檔案：檔案的內容 （主要資料流） 不存在於磁碟上。 檔案的中繼資料（名稱、大小、時間戳記、屬性等）會快取在磁碟上。 對於目錄：目錄的部分或全部直系後代（目錄中的檔案和目錄）不存在於磁碟上，即它們仍然是虛擬的。 目錄的中繼資料（名稱、時間戳記、屬性等）快取在磁碟上。

水合預留位置 - 對於檔案：檔案的內容和中繼資料已快取到磁碟。 也稱為「部分檔案」。 對於目錄：目錄從來都不是水合預留位置。 在磁碟上建立為預留位置的目錄永遠不會成為水合預留位置目錄。 這可讓提供者從其備份存放區中的目錄中新增或移除專案，並讓這些變更反映在本機快取中。

髒預留位置 （水合或未水合） - 專案的中繼資料已在本機修改，且不再是提供者存放區中狀態的快取。 請注意，在預留位置目錄下建立或刪除檔案或目錄會導致該預留位置目錄變髒。

完整檔案/目錄 - 對於檔案：檔案的內容（主要資料流）已被修改。 檔案不再是提供者存放區中狀態的快取。 在本機檔案系統上建立的檔案 （亦即，提供者存放區中根本不存在） 也會被視為完整檔案。 對於目錄：在本機檔案系統上建立的目錄（即完全不存在於提供者的存放區中）被視為完整目錄。 在磁碟上建立為預留位置的目錄永遠不會成為完整目錄。

標記 - 特殊的隱藏預留位置，代表已從本機檔案系統中刪除的專案。 列舉目錄時，ProjFS 會將本機專案集 （預留位置、完整檔案等） 與虛擬投影專案集合併。 如果項目同時出現在本端和投影集中，則本端項目優先。 如果檔案不存在，則沒有本機狀態，因此會出現在列舉中。 不過，如果該專案已刪除，則將其出現在列舉中會是非預期的。 以刪除刪除的項目取代會產生下列效果：

• 不顯示專案的列舉
• 預期項目存在的檔案開啟會失敗，例如「找不到檔案」。
• 只有在專案不存在時才預期成功的檔案建立成功;ProjFS 會在作業中移除墓碑。

若要說明上述狀態，請考慮下列順序，假設 ProjFS 提供者具有位於虛擬化根目錄 C：\root 中的單一檔案 「foo.txt」。

• 應用程式列舉 C：\root。 它看到虛擬檔案「foo.txt」。 由於尚未存取檔案，因此磁碟上不存在該檔案。
• 應用程式會開啟 C:\root\foo.txt的句柄。 ProjFS 會告知提供者為其建立預留位置。
• 該應用程序讀取文件的內容。 提供者會將檔案內容提供給 ProjFS，並快取至 C:\root\foo.txt。 檔案現在是水合預留位置。
• 應用程式會更新上次修改時間戳記。 檔案現在是髒水合預留位置。
• 應用程式會開啟檔案的寫入存取權控制碼。 C:\root\foo.txt 現在是一個完整的文件。
• 應用程式會刪除 C:\root\foo.txt。 ProjFS 會以墓碑取代檔案。 現在，當應用程式列舉 C:\root it does not see foo.txt時。 如果嘗試開啟檔案，開啟會失敗並ERROR_FILE_NOT_FOUND。

需求