IVssBackupComponents::AddComponent method (vsbackup.h)
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 |
|---|---|
|
Successfully added the component. |
|
One of the parameter values is not valid. |
|
The caller is out of memory or other system resources. |
|
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. |
|
The XML document is not valid. Check the event log for details. For more information, see Event and Error Handling Under VSS. |
|
The object is a duplicate. A component with the same logical path and component name already exists. |
|
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 |
See also
IVssBackupComponents::PrepareForBackup