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

Artigo
08/27/2023

O método AddNewTarget é usado por um solicitante durante uma operação de restauração para indicar que o aplicativo de backup planeja restaurar arquivos para um novo local.

Sintaxe

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

GUID (identificador global exclusivo) da classe de gravador que contém os arquivos que devem receber um novo destino.

[in] ct

Identifica o tipo do componente. Consulte a documentação de VSS_COMPONENT_TYPE para obter possíveis valores retornados.

[in] wszLogicalPath

Cadeia de caracteres largos terminada em nulo que contém o caminho lógico do componente que contém os arquivos que devem receber um novo destino de restauração. Para obter mais informações, consulte Caminhos lógicos de componentes.

O valor da cadeia de caracteres que contém o caminho lógico usado aqui deve ser o mesmo usado quando o componente foi adicionado ao conjunto de backup usando IVssBackupComponents::AddComponent.

O caminho lógico pode ser NULL.

Não há restrições nos caracteres que podem aparecer em um caminho lógico não NULL .

[in] wszComponentName

Cadeia de caracteres largos terminada em nulo que contém o nome do componente que contém os arquivos que devem receber um novo destino de restauração.

A cadeia de caracteres não deve ser NULL e deve conter o mesmo nome de componente que foi usado quando o componente foi adicionado ao conjunto de backup usando IVssBackupComponents::AddComponent.

Não há restrições nos caracteres que podem aparecer em um caminho lógico não NULL .

[in] wszPath

Cadeia de caracteres largos terminada em nulo que contém o nome do diretório ou hierarquia de diretório que contém os arquivos para receber um novo destino de restauração.

O diretório pode ser um diretório local no computador VSS ou pode ser um diretório de compartilhamento de arquivos em um servidor de arquivos remoto.

O caminho pode conter variáveis de ambiente (por exemplo, %SystemRoot%), mas não pode conter caracteres curinga. Há suporte para caminhos UNC.

Não há nenhum requisito de que o caminho termine com uma barra invertida (""). Cabe aos aplicativos que recuperam essas informações marcar.

[in] wszFileName

Cadeia de caracteres largos terminada em nulo que contém a especificação de arquivo dos arquivos para receber um novo destino de restauração.

Uma especificação de arquivo não pode conter especificações de diretório (por exemplo, sem barras invertidas), mas pode conter o ? e * caracteres curinga.

[in] bRecursive

Boolean indicando se apenas os arquivos no diretório definido por wszPath e que correspondem à especificação de arquivo fornecida por wszFileName devem receber um novo destino de restauração ou se todos os arquivos na hierarquia definida por wszPath e correspondentes à especificação de arquivo fornecida por wszFileName receberão um novo destino de restauração.

Para obter informações sobre como percorrer pastas montadas, consulte Trabalhando com pastas montadas e pontos de nova análise.

[in] wszAlternatePath

Cadeia de caracteres largos terminada em nulo que contém o caminho totalmente qualificado do novo diretório de destino de restauração.

O diretório pode ser um diretório local no computador VSS ou pode ser um diretório de compartilhamento de arquivos em um servidor de arquivos remoto.

Há suporte para caminhos UNC.

Retornar valor

Veja a seguir os códigos de retorno válidos para esse método.

Valor	Significado
S_OK	Adicionado com êxito o novo destino de restauração.
E_INVALIDARG	Um dos valores de parâmetro não é válido.
E_OUTOFMEMORY	O chamador está sem memória ou outros recursos do sistema.
VSS_E_BAD_STATE	O objeto de componentes de backup não é inicializado ou esse método foi chamado durante uma operação de restauração.
VSS_E_INVALID_XML_DOCUMENT	O documento XML não é válido. Verifique o log de eventos para obter detalhes. Para obter mais informações, consulte Tratamento de eventos e erros em VSS.
VSS_E_OBJECT_NOT_FOUND	O componente não existe ou o caminho e a especificação de arquivo não correspondem a um componente e uma especificação de arquivo no componente.
VSS_E_UNEXPECTED	Erro inesperado. O código de erro é registrado no arquivo de log de erros. Para obter mais informações, consulte Tratamento de eventos e erros em VSS. Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Esse valor não tem suporte até o Windows Server 2008 R2 e o Windows 7. E_UNEXPECTED é usado.

Comentários

Windows 7, Windows Server 2008 R2, Windows Vista, Windows Server 2008, Windows XP e Windows Server 2003: Não há suporte para compartilhamentos de arquivos remotos até Windows 8 e Windows Server 2012.

O nome do componente especificado como um argumento para AddNewTarget (wszComponentName) deve corresponder a um componente que já foi adicionado ao Documento de Componentes de Backup.

Portanto, wszComponentName pode ser o nome de qualquer componente explicitamente incluído no Documento de Componentes de Backup.

A adição de um novo destino para o arquivo em um subcomponente deve ser feita usando o nome do componente que define o conjunto de componentes que contém o subcomponente.

Ao especificar um arquivo ou arquivos para que o destino de restauração seja alterado, um solicitante deve garantir que a combinação de caminho, especificação de arquivo e sinalizador de recursão (wszPath, wszFileSpec e bRecursive, respectivamente) fornecida a AddNewTarget deve corresponder à de um dos conjuntos de arquivos adicionados a um componente usando IVssCreateWriterMetadata::AddFilesToFileGroup, IVssCreateWriterMetadata::AddDatabaseFiles, ou IVssCreateWriterMetadata::AddDatabaseLogFiles.

Quando um solicitante chama AddNewTarget, ele deve fazer isso antes de chamar IVssBackupComponents::P reRestore. Para obter mais informações, consulte Visão geral da preparação para restauração.

As informações do descritor de caminho e arquivo podem ser obtidas do Documento de Metadados do Gravador usando o objeto IVssWMFiledesc retornado por IVssWMComponent::GetFile, IVssWMComponent::GetDatabaseFile ou IVssWMComponent::GetDatabaseLogFile. O objeto IVssWMComponent é obtido do Documento de Metadados do Gravador pelo método IVssExamineWriterMetadata::GetComponent .

Os gravadores podem determinar se os arquivos foram restaurados para novos locais usando os métodos IVssComponent::GetNewTargetCount e IVssComponent::GetNewTarget .

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	vsbackup.h (inclua VsBackup.h, Vss.h, VsWriter.h)
Biblioteca	VssApi.lib