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

Artigo
08/27/2023

O método AddComponent é usado para adicionar explicitamente ao conjunto de backup no Documento de Componentes de Backup todos os componentes necessários (não selecionáveis para componentes de backup sem um ancestral de backup) e componentes opcionais (selecionáveis para backup), como o solicitante considera necessários. Membros de conjuntos de componentes (componentes com um ancestral de backup selecionável) são incluídos implicitamente no conjunto de backup, mas não são adicionados explicitamente ao Documento de Componentes de Backup.

Sintaxe

HRESULT AddComponent(
  [in] VSS_ID             instanceId,
  [in] VSS_ID             writerId,
  [in] VSS_COMPONENT_TYPE ct,
  [in] LPCWSTR            wszLogicalPath,
  [in] LPCWSTR            wszComponentName
);

Parâmetros

[in] instanceId

Identifica uma instância específica de um gravador.

[in] writerId

Identificador de classe de gravador.

[in] ct

Identifica o tipo do componente. Consulte a documentação de VSS_COMPONENT_TYPE para obter valores de entrada permitidos.

[in] wszLogicalPath

Cadeia de caracteres largos terminada em nulo que contém o caminho lógico do selecionável para o componente de backup. Para obter mais informações, consulte Caminhos lógicos de componentes.

Um caminho lógico não é necessário ao adicionar um componente. Portanto, o valor desse parâmetro 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 selecionável para o componente de backup.

O valor desse parâmetro não pode ser NULL.

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

Retornar valor

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

Valor	Significado
S_OK	O componente foi adicionado com êxito.
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, esse método foi chamado durante uma operação de restauração ou esse método não foi chamado dentro da sequência correta.
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_ALREADY_EXISTS	O objeto é duplicado. Já existe um componente com o mesmo caminho lógico e o nome do 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

O método AddComponent terá significado somente se a operação de backup ocorrer no modo de componente.

Somente esses tipos de componentes devem ser adicionados ao Documento de Componentes de Backup usando AddComponent.

Componentes selecionáveis para backup (consulte selectability for backup).
Componentes não selecionáveis para backup sem ancestrais selecionáveis para backup.

Não reelecionáveis para componentes de backup que têm um ancestral de backup selecionável na hierarquia de seus caminhos lógicos fazem parte de um conjunto de componentes definido pelo selectable para o ancestral do backup. Esses componentes são adicionados implicitamente ao Documento de Componentes de Backup quando o ancestral é adicionado e nunca deve ser adicionado explicitamente ao Documento de Componentes de Backup de um solicitante usando AddComponent. O resultado de fazer isso é indefinido (consulte Trabalhando com selebilidade e caminhos lógicos).

Selecionável para componentes de backup com selecionável para ancestrais de backup também são subcomponentes em um conjunto de componentes. Elas podem ser selecionadas implicitamente se seu ancestral estiver selecionado (nesse caso, eles não são adicionados ao Documento de Componentes de Backup usando AddComponent) ou podem ser explicitamente selecionados usando AddComponent.

A combinação de caminho lógico e nome para cada componente de uma determinada instância de uma determinada classe de gravador deve ser exclusiva. Tentar chamar AddComponent duas vezes com os mesmos valores de wszLogicalPath e wszComponentName resulta em um erro de VSS_E_OBJECT_ALREADY_EXISTS.

A distinção entre o instanceId e o writerID é necessária porque é possível executar várias cópias para o mesmo gravador.

O identificador de classe e a instância de um gravador podem ser encontrados chamando IVssExamineWriterMetadata::GetIdentity.

Antes de chamar AddComponent, um solicitante deve ter sido inicializado para backup chamando IVssBackupComponents::InitializeForBackup e IVssBackupComponents::GatherWriterMetadata. Confira Visão geral da Inicialização de Backup.

O solicitante deve chamar AddComponent para adicionar os componentes necessários à cópia de sombra antes de chamar IVssBackupComponents::D oSnapshotSet para criar a cópia de sombra. Confira Visão geral da fase de descoberta de backup e visão geral das tarefas de pré-backup.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [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