IVssBackupComponents::AddComponent method (vsbackup.h)

Article
10/13/2021

The AddComponent method is used to explicitly add to the backup set in the Backup Components Document all required components (nonselectable for backup components without a selectable for backup ancestor), and such optional (selectable for backup) components as the requester considers necessary. Members of component sets (components with a selectable for backup ancestor) are implicitly included in the backup set, but are not explicitly added to the Backup Components Document.

Syntax

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

Parameters

[in] instanceId

Identifies a specific instance of a writer.

[in] writerId

Writer class identifier.

[in] ct

Identifies the type of the component. Refer to the documentation for VSS_COMPONENT_TYPE for permitted input values.

[in] wszLogicalPath

Null-terminated wide character string containing the logical path of the selectable for backup component. For more information, see Logical Pathing of Components.

A logical path is not required when adding a component. Therefore, the value of this parameter can be NULL.

There are no restrictions on the characters that can appear in a non-NULL logical path.

[in] wszComponentName

Null-terminated wide character string containing the name of the selectable for backup component.

The value of this parameter cannot be NULL.

There are no restrictions on the characters that can appear in a non-NULL logical path.

Return value

The following are the valid return codes for this method.

Value	Meaning
S_OK	Successfully added the component.
E_INVALIDARG	One of the parameter values is not valid.
E_OUTOFMEMORY	The caller is out of memory or other system resources.
VSS_E_BAD_STATE	The backup components object is not initialized, this method has been called during a restore operation, or this method has not been called within the correct sequence.
VSS_E_INVALID_XML_DOCUMENT	The XML document is not valid. Check the event log for details. For more information, see Event and Error Handling Under VSS.
VSS_E_OBJECT_ALREADY_EXISTS	The object is a duplicate. A component with the same logical path and component name already exists.
VSS_E_UNEXPECTED	Unexpected error. The error code is logged in the error log file. For more information, see Event and Error Handling Under VSS. Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: This value is not supported until Windows Server 2008 R2 and Windows 7. E_UNEXPECTED is used instead.

Remarks

The AddComponent method has meaning only if the backup operation takes place in component mode.

Only these kinds of components should be added to the Backup Components Document using AddComponent.

Components that are selectable for backup (see selectability for backup).
Nonselectable-for-backup components with no selectable-for-backup ancestors.

Nonselectable for backup components that have a selectable for backup ancestor in the hierarchy of their logical paths are part of a component set defined by the selectable for backup ancestor. These components are implicitly added to the Backup Components Document when the ancestor is added and should never be explicitly added to a requester's Backup Components Document by using AddComponent.The result of doing so is undefined (see Working with Selectability and Logical Paths).

Selectable for backup components with selectable for backup ancestors are also subcomponents in a component set. They can be implicitly selected if their ancestor is selected (in which case they are not added to the Backup Components Document using AddComponent), or they can be explicitly selected using AddComponent.

The combination of logical path and name for each component of a given instance of a given class of writer must be unique. Attempting to call AddComponent twice with the same values of wszLogicalPath and wszComponentName results in a VSS_E_OBJECT_ALREADY_EXISTS error.

The distinction between the instanceId and the writerID is necessary because it is possible to run multiple copies for the same writer.

A writer's class identifier and instance can be found by calling IVssExamineWriterMetadata::GetIdentity.

Before it calls AddComponent, a requester must have been initialized for backup by calling IVssBackupComponents::InitializeForBackup and IVssBackupComponents::GatherWriterMetadata. See Overview of Backup Initialization.

The requester must call AddComponent to add the required components to the shadow copy before calling IVssBackupComponents::DoSnapshotSet to create the shadow copy. See Overview of the Backup Discovery Phase and Overview of Pre-Backup Tasks.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	vsbackup.h (include VsBackup.h, Vss.h, VsWriter.h)
Library	VssApi.lib