IVssBackupComponents：：AddNewTarget 方法 (vsbackup.h)

發行項
03/03/2024

AddNewTarget 方法會在還原作業期間由要求者使用，以指出備份應用程式計劃將檔案還原至新位置。

語法

HRESULT AddNewTarget(
  [in] VSS_ID             writerId,
  [in] VSS_COMPONENT_TYPE ct,
  [in] LPCWSTR            wszLogicalPath,
  [in] LPCWSTR            wszComponentName,
  [in] LPCWSTR            wszPath,
  [in] LPCWSTR            wszFileName,
  [in] bool               bRecursive,
  [in] LPCWSTR            wszAlternatePath
);

參數

[in] writerId

寫入器類別的全域唯一標識碼 (GUID) ，其中包含要接收新目標的檔案。

[in] ct

識別元件的類型。如需可能的傳回值，請參閱VSS_COMPONENT_TYPE 檔。

[in] wszLogicalPath

Null 終止的寬字元字串，包含包含要接收新還原目標的檔案之元件的邏輯路徑。如需詳細資訊，請參閱元件的邏輯路徑。

包含此處之邏輯路徑的字串值應該與使用 IVssBackupComponents：：AddComponent 新增至備份集時所使用的相同。

邏輯路徑可以是 NULL。

在非 NULL 邏輯路徑中出現的字元沒有任何限制。

[in] wszComponentName

以 Null 結尾的寬字元字串，包含包含要接收新還原目標的檔案之元件名稱。

字串不應該是 NULL ，而且應該包含與使用 IVssBackupComponents：：AddComponent 新增至備份集時所使用的元件名稱相同。

在非 NULL 邏輯路徑中出現的字元沒有任何限制。

[in] wszPath

以 Null 結尾的寬字元字串，包含包含要接收新還原目標的檔案之目錄或目錄階層的名稱。

目錄可以是 VSS 電腦上的本機目錄，也可以是遠端檔案檔案上的檔案共享目錄。

路徑可以包含環境變數 (，例如%SystemRoot%) ，但不能包含通配符。支援 UNC 路徑。

路徑結尾不需要反斜杠 (“”) 。這是擷取此資訊以檢查的應用程式。

[in] wszFileName

以 Null 終止的寬字元字串，其中包含要接收新還原目標的檔案規格。

例如，檔案規格不能包含目錄規格 (，沒有反斜杠) 但可以包含？和 * 通配符。

[in] bRecursive

布爾值，指出是否只有 wszPath 所定義的目錄中檔案，以及比對 wszFileName 所提供的檔案規格來接收新的還原目標，或者 wszPath 所定義的階層中的所有檔案，以及 符合 wszFileName 所提供的檔案規格，是否要接收新的還原目標。

如需周遊掛接資料夾的資訊，請參閱使用掛接的資料夾和重新分析點。

[in] wszAlternatePath

以 Null 結尾的寬字元字串，其中包含新還原目標目錄的完整路徑。

目錄可以是 VSS 電腦上的本機目錄，也可以是遠端檔案檔案上的檔案共享目錄。

支援 UNC 路徑。

傳回值

以下是此方法的有效傳回碼。

值	意義
S_OK	已成功新增新的還原目標。
E_INVALIDARG	其中一個參數值無效。
E_OUTOFMEMORY	呼叫端記憶體不足或其他系統資源。
VSS_E_BAD_STATE	備份元件物件未初始化，或在還原作業期間呼叫此方法。
VSS_E_INVALID_XML_DOCUMENT	XML 檔無效。請檢查事件記錄檔以取得詳細數據。如需詳細資訊，請參閱 VSS 下的事件和錯誤處理。
VSS_E_OBJECT_NOT_FOUND	元件不存在，或路徑和檔案規格不符合元件中的元件和檔案規格。
VSS_E_UNEXPECTED	非預期的錯誤。錯誤碼會記錄在錯誤記錄檔中。如需詳細資訊，請參閱 VSS 下的事件和錯誤處理。 Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP：在 Windows Server 2008 R2 和 Windows 7 之前，不支援此值。改用E_UNEXPECTED。

備註

Windows 7、Windows Server 2008 R2、Windows Vista、Windows Server 2008、Windows XP 和 Windows Server 2003： 在 Windows 8 和 Windows Server 2012 之前，不支援遠端檔案共用。

指定為 AddNewTarget (wszComponentName) 的元件名稱必須符合已新增至備份元件檔的元件。

因此， wszComponentName 可以是備份元件文件中明確包含的任何元件名稱。

若要在子元件中新增檔案的新目標，必須使用定義包含子元件之元件集的元件名稱來完成。

指定檔案或檔案以變更其還原目標時，要求者必須確定路徑的組合。檔案規格和遞歸旗標 (wszPath、 wszFileSpec 和 bRecursive 分別) 提供給 AddNewTarget 的檔案集必須符合使用 IVssCreateWriterMetadata：：AddFilesToFileGroup、 IVssCreateWriterMetadata：：AddDatabaseFiles 或IVssCreateWriterMetadata：：AddDatabaseLogFiles。

當要求者呼叫 AddNewTarget 時，必須先這麼做，才能呼叫 IVssBackupComponents：:P reRestore。如需詳細資訊，請參閱準備還原的概觀。

您可以使用 IVssWMComponent：：GetFile、IVssWMComponent：：GetFile、IVssWMComponent：：GetDatabaseFile 或 IVssWMComponent：：GetDatabaseFile 傳回的 IVssWMFiledesc 物件，從寫入器元數據檔取得路徑和檔案描述元資訊。 IVssWMComponent 物件是由 IVssExriterMetadata：：GetComponent 方法從寫入器元數據檔取得。

寫入器可以使用 IVssComponent：：GetNewTargetCount 和 IVssComponent：：GetNewTarget 方法，判斷檔案是否已還原到新的位置。

規格需求

需求	值
最低支援的用戶端	Windows Vista [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限傳統型應用程式]
目標平台	Windows
標頭	vsbackup.h (包括 VsBackup.h、Vss.h、VsWriter.h)
程式庫	VssApi.lib