Метод 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, содержащая полный путь к новому целевому каталогу восстановления.

Поддерживаются 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.

Имя компонента, указанное в качестве аргумента addNewTarget (wszComponentName), должно соответствовать компоненту, который уже был добавлен в документ компонентов резервного копирования.

Таким образом, wszComponentName может быть именем любого компонента, явно включенного в документ о компонентах резервного копирования.

Добавление нового целевого объекта для файла в подкомпоненте должно выполняться с помощью имени компонента, определяющего набор компонентов, содержащий подкомпонент.

При указании файла или файлов для изменения целевого объекта восстановления инициатор запроса должен убедиться, что сочетание пути, спецификации файла и флага рекурсии (wszPath, wszFileSpec и bRecursive соответственно), предоставленное в AddNewTarget , должно соответствовать одному из наборов файлов, добавленных в компонент с помощью IVssCreateWriterMetadata::AddFilesToFileGroup, IVssCreateWriterMetadata::AddDatabaseFiles, или IVssCreateWriterMetadata::AddDatabaseLogFiles.

Когда инициатор запроса вызывает AddNewTarget, он должен сделать это перед вызовом IVssBackupComponents::P reRestore. Дополнительные сведения см. в статье Общие сведения о подготовке к восстановлению.

Сведения о пути и дескрипторе файла можно получить из документа метаданных модуля записи с помощью объекта IVssWMFiledesc , возвращаемого IVssWMComponent::GetFile, IVssWMComponent::GetDatabaseFile или IVssWMComponent::GetDatabaseLogFile. Объект IVssWMComponent получается из документа метаданных модуля записи методом IVssExamineWriterMetadata::GetComponent .

Средства записи могут определить, были ли файлы восстановлены в новые расположения, с помощью методов IVssComponent::GetNewTargetCount и IVssComponent::GetNewTarget .

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	vsbackup.h (включая VsBackup.h, Vss.h, VsWriter.h)
Библиотека	VssApi.lib