IVssBackupComponents：：AddNewTarget 方法 (vsbackup.h)

项目
08/27/2023

在还原操作期间，请求者使用 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 可以是备份组件文档中显式包含的任何组件的名称。

必须为子组件中的文件添加新目标，必须使用定义包含子组件的组件集的组件的名称。

指定一个或多个文件以更改其还原目标时，请求者必须确保路径的组合，分别) 提供给 AddNewTarget 的文件规范和 (wszPath、wszFileSpec 和 bRecursive 标志必须与使用 IVssCreateWriterMetadata：：AddFilesToFileGroup、IVssCreateWriterMetadata：：AddDatabaseFiles 添加到组件的其中一个文件集匹配，或者IVssCreateWriterMetadata：：AddDatabaseLogFiles。

当请求者调用 AddNewTarget 时，它必须在调用 IVssBackupComponents：:P reRestore 之前执行此操作。有关详细信息，请参阅准备还原概述。

可以使用 IVssWMComponent：：GetFile、IVssWMComponent：：GetDatabaseFile 或 IVssWMComponent：：GetDatabaseLogFile 返回的 IVssWMFiledesc 对象从编写器元数据文档获取路径和文件描述符信息。 IVssWMComponent 对象由 IVssExamineWriterMetadata：：GetComponent 方法从编写器元数据文档获取。

编写器可以使用 IVssComponent：：GetNewTargetCount 和 IVssComponent：：GetNewTarget 方法确定是否将文件还原到新位置。

要求

要求	值
最低受支持的客户端	Windows Vista [仅限桌面应用]
最低受支持的服务器	Windows Server 2003 [仅限桌面应用]
目标平台	Windows
标头	vsbackup.h (包括 VsBackup.h、Vss.h、VsWriter.h)
Library	VssApi.lib