IVssBackupComponents：：AddAlternativeLocationMapping 方法 (vsbackup.h)

  • 项目

AddAlternativeLocationMapping 方法由请求者用来指示使用备用位置映射来还原给定组件中文件集的所有成员。

语法

HRESULT AddAlternativeLocationMapping(
  [in] VSS_ID             writerId,
  [in] VSS_COMPONENT_TYPE componentType,
  [in] LPCWSTR            wszLogicalPath,
  [in] LPCWSTR            wszComponentName,
  [in] LPCWSTR            wszPath,
  [in] LPCWSTR            wszFilespec,
  [in] bool               bRecursive,
  [in] LPCWSTR            wszDestination
);

参数

[in] writerId

导出组件的编写器类的全局唯一标识符 (GUID) 。

[in] componentType

组件的类型。 此参数的可能值由 VSS_COMPONENT_TYPE 枚举定义。

[in] wszLogicalPath

以 Null 结尾的宽字符串，其中包含组件的逻辑路径。

有关详细信息，请参阅 组件的逻辑路径。

逻辑路径可以为 NULL。

对于可以出现在非 NULL 逻辑路径中的字符没有限制。

[in] wszComponentName

包含组件名称的以 Null 结尾的宽字符串。

对于可以出现在非 NULL 逻辑路径中的字符没有限制。

[in] wszPath

以 Null 结尾的宽字符串，其中包含最初包含要重新定位文件的目录的路径。 此路径可以是 VSS 计算机的本地路径，也可以是远程文件服务器上的文件共享目录。

路径可以包含环境变量 (例如 %SystemRoot%) ，但不能包含通配符。 支持 UNC 路径。

不要求路径以反斜杠 (“”) 结尾。 由应用程序来检索此信息以检查。

[in] wszFilespec

包含原始文件规范的以 Null 结尾的宽字符串。

文件规范不能包含目录规范 (例如，没有反斜杠) 但可以包含 ？ 和 * 通配符。

[in] bRecursive

一个布尔值，指示 wszPath 参数指定的路径是仅标识单个目录，还是指示要以递归方式遍历的目录层次结构。 如果将路径视为要以递归方式遍历的目录层次结构，则应将此参数设置为 true ;否则应设置为 false 。

有关遍历已装载文件夹的信息，请参阅 使用装载的文件夹和重新分析点。

[in] wszDestination

以 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之前，不支持远程文件共享。

writerId、componentType、wszLogicalPath 和 wszComponentName 参数标识特定组件，wszPath、wszFilespec 和 bRecursive 参数标识属于该组件的文件集。

路径、文件规范和递归标志的组合 (wszPath、wszFilespec、 和 bRecursive 分别) 提供给 AddAlternativeLocationMapping 进行映射，必须与使用 IVssCreateWriterMetadata：：AddFilesToFileGroup、IVssCreateWriterMetadata：：AddDatabaseFiles 或 IVssCreateWriterMetadata：：AddDatabaseLogFiles 添加到组件的文件集之一相匹配。

由于 AddAlternativeLocationMapping 用于通知编写器已使用备用位置还原组件中的所有文件，因此不应为组件中未指定备用位置映射的任何组件或文件调用它。

还原时，wszPath 的值将映射到 wszDestination;但是，原始路径下的文件名和子目录保留相同的名称。

在还原期间 ，AddAlternativeLocationMapping 的典型用法可能如下：

  1. 从备份介质中检索存储的编写器元数据文档，并使用 IVssExamineWriterMetadata：：LoadFromXML 加载该信息。
  2. 调用 IVssExamineWriterMetadata：：GetAlternateLocationMapping 以获取包含映射信息的 IVssWMFiledesc 接口，并使用 IVssWMFiledesc：：GetAlternateLocation 获取备用位置。
  3. 检查 filedesc 信息，以启发式方式确定应将此备用位置映射应用于哪个组件。
  4. 调用 IVssBackupComponents：：AddAlternativeLocationMapping 以传达文件还原的位置。
如果以下任一情况为 true，应始终将文件还原到其备用位置映射：
  • VSS_RME_RESTORE_TO_ALTERNATE_LOCATION备份时 (设置还原方法) 。
  • 其还原目标在还原时 () 设置为VSS_RT_ALTERNATE。
在任一情况下，如果未定义有效的备用位置映射，则构成编写器错误。

如果符合以下任一条件，则文件可以还原到备用位置映射：

  • 还原方法VSS_RME_RESTORE_IF_NOT_THERE并且磁盘上已存在文件的某个版本。
  • 还原方法VSS_RME_RESTORE_IF_CAN_REPLACE并且磁盘上存在文件版本，无法替换。
同样，如果未定义有效的备用位置映射，则构成编写器错误。

备用位置映射仅在还原操作期间使用，不应与仅在备份操作期间使用的备用路径混淆。

要求

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

另请参阅

IVssBackupComponents

IVssWMFiledesc：：GetAlternateLocation

VSS_COMPONENT_TYPE