Método IVssBackupComponents::AddNewTarget (vsbackup.h)

Artículo
03/03/2024

Un solicitante usa el método AddNewTarget durante una operación de restauración para indicar que la aplicación de copia de seguridad planea restaurar archivos en una nueva ubicación.

Sintaxis

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
);

Parámetros

[in] writerId

Identificador único global (GUID) de la clase writer que contiene los archivos que van a recibir un nuevo destino.

[in] ct

Identifica el tipo del componente. Consulte la documentación de VSS_COMPONENT_TYPE para conocer los posibles valores devueltos.

[in] wszLogicalPath

Cadena de caracteres anchos terminada en NULL que contiene la ruta de acceso lógica del componente que contiene los archivos que van a recibir un nuevo destino de restauración. Para obtener más información, consulte Ruta de acceso lógica de componentes.

El valor de la cadena que contiene la ruta de acceso lógica usada aquí debe ser el mismo que se usó cuando se agregó el componente al conjunto de copia de seguridad mediante IVssBackupComponents::AddComponent.

La ruta de acceso lógica puede ser NULL.

No hay restricciones en los caracteres que pueden aparecer en una ruta lógica que no sea NULL .

[in] wszComponentName

Cadena de caracteres anchos terminada en NULL que contiene el nombre del componente que contiene los archivos que van a recibir un nuevo destino de restauración.

La cadena no debe ser NULL y debe contener el mismo nombre de componente que se usó cuando se agregó el componente al conjunto de copia de seguridad mediante IVssBackupComponents::AddComponent.

No hay restricciones en los caracteres que pueden aparecer en una ruta lógica que no sea NULL .

[in] wszPath

Cadena de caracteres anchos terminada en NULL que contiene el nombre del directorio o jerarquía de directorios que contiene los archivos para recibir un nuevo destino de restauración.

El directorio puede ser un directorio local en la máquina VSS o puede ser un directorio de recursos compartidos de archivos en un servidor de archivos remoto.

La ruta de acceso puede contener variables de entorno (por ejemplo, %SystemRoot%) pero no puede contener caracteres comodín. Se admiten rutas de acceso UNC.

No es necesario que la ruta de acceso termine con una barra diagonal inversa (""). Es necesario que las aplicaciones recuperen esta información para comprobarla.

[in] wszFileName

Cadena de caracteres anchos terminada en NULL que contiene la especificación de archivo de los archivos para recibir un nuevo destino de restauración.

Una especificación de archivo no puede contener especificaciones de directorio (por ejemplo, sin barras diagonales inversas), pero puede contener ? y * caracteres comodín.

[in] bRecursive

Boolean que indica si solo los archivos del directorio definido por wszPath y que coinciden con la especificación de archivo proporcionada por wszFileName van a recibir un nuevo destino de restauración, o si todos los archivos de la jerarquía definidas por wszPath y coinciden con la especificación de archivo proporcionada por wszFileName van a recibir un nuevo destino de restauración.

Para obtener información sobre cómo recorrer carpetas montadas, vea Trabajar con carpetas montadas y puntos de reanálisis.

[in] wszAlternatePath

Cadena de caracteres anchos terminada en NULL que contiene la ruta de acceso completa del nuevo directorio de destino de restauración.

El directorio puede ser un directorio local en la máquina VSS o puede ser un directorio de recursos compartidos de archivos en un servidor de archivos remoto.

Se admiten rutas de acceso UNC.

Valor devuelto

A continuación se muestran los códigos de retorno válidos para este método.

Valor	Significado
S_OK	Se agregó correctamente el nuevo destino de restauración.
E_INVALIDARG	Uno de los valores de parámetro no es válido.
E_OUTOFMEMORY	El autor de la llamada no tiene memoria u otros recursos del sistema.
VSS_E_BAD_STATE	El objeto de componentes de copia de seguridad no se inicializa o se ha llamado a este método durante una operación de restauración.
VSS_E_INVALID_XML_DOCUMENT	El documento XML no es válido. Compruebe el registro de eventos para obtener más información. Para obtener más información, consulte Control de eventos y errores en VSS.
VSS_E_OBJECT_NOT_FOUND	El componente no existe o la ruta de acceso y la especificación de archivo no coinciden con una especificación de componente y archivo en el componente.
VSS_E_UNEXPECTED	error inesperado. El código de error se registra en el archivo de registro de errores. Para obtener más información, consulte Control de eventos y errores en VSS. Windows Server 2008, Windows Vista, Windows Server 2003 y Windows XP: Este valor no se admite hasta Windows Server 2008 R2 y Windows 7. E_UNEXPECTED se usa en su lugar.

Comentarios

Windows 7, Windows Server 2008 R2, Windows Vista, Windows Server 2008, Windows XP y Windows Server 2003: Los recursos compartidos de archivos remotos no se admiten hasta Windows 8 y Windows Server 2012.

El nombre del componente especificado como argumento para AddNewTarget (wszComponentName) debe coincidir con un componente que ya se haya agregado al documento componentes de copia de seguridad.

Por lo tanto, wszComponentName puede ser el nombre de cualquier componente incluido explícitamente en el documento componentes de copia de seguridad.

Agregar un nuevo destino para el archivo en un subcomponente debe realizarse con el nombre del componente que define el conjunto de componentes que contiene el subcomponente.

Al especificar un archivo o archivos para que su destino de restauración cambie, un solicitante debe asegurarse de que la combinación de ruta de acceso, especificación de archivo y marca de recursión (wszPath, wszFileSpec y bRecursive, respectivamente) proporcionada a AddNewTarget debe coincidir con la de uno de los conjuntos de archivos agregados a un componente mediante IVssCreateWriterMetadata::AddFilesToFileGroup, IVssCreateWriterMetadata::AddDatabaseFiles o IVssCreateWriterMetadata::AddDatabaseLogFiles.

Cuando un solicitante llama a AddNewTarget, debe hacerlo antes de llamar a IVssBackupComponents::P reRestore. Para obtener más información, vea Información general sobre la preparación de la restauración.

La información de ruta de acceso y descriptor de archivo se puede obtener del documento de metadatos del escritor mediante el objeto IVssWMFiledesc devuelto por IVssWMComponent::GetFile, IVssWMComponent::GetDatabaseFile o IVssWMComponent::GetDatabaseLogFile. El objeto IVssWMComponent se obtiene del documento de metadatos del escritor mediante el método IVssExamineWriterMetadata::GetComponent .

Los escritores pueden determinar si los archivos se han restaurado en nuevas ubicaciones mediante los métodos IVssComponent::GetNewTargetCount e IVssComponent::GetNewTarget .

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	vsbackup.h (incluya VsBackup.h, Vss.h, VsWriter.h)
Library	VssApi.lib