共用方式為

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

佔位元Info 所指向緩衝區的大小，以位元組為單位。

[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 時，它看不到 foo.txt。 如果嘗試開啟檔案，則開啟會失敗並出現ERROR_FILE_NOT_FOUND。

規格需求

需求 值
最低支援的用戶端 Windows 10 版本 1809 [僅限傳統型應用程式]
最低支援的伺服器 Windows Server [僅限傳統型應用程式]
目標平台 Windows
標頭 projectedfslib.h