IVssBackupComponents::AddNewTarget method (vsbackup.h)

The AddNewTarget method is used by a requester during a restore operation to indicate that the backup application plans to restore files to a new location.

Syntax

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

Parameters

[in] writerId

Globally unique identifier (GUID) of the writer class containing the files that are to receive a new target.

[in] ct

Identifies the type of the component. Refer to the documentation for VSS_COMPONENT_TYPE for possible return values.

[in] wszLogicalPath

Null-terminated wide character string containing the logical path of the component containing the files that are to receive a new restore target. For more information, see Logical Pathing of Components.

The value of the string containing the logical path used here should be the same as was used when the component was added to the backup set using IVssBackupComponents::AddComponent.

The logical path 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 component containing the files that are to receive a new restore target.

The string should not be NULL and should contain the same component name as was used when the component was added to the backup set using IVssBackupComponents::AddComponent.

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

[in] wszPath

Null-terminated wide character string containing the name of the directory or directory hierarchy containing the files to receive a new restore target.

The directory can be a local directory on the VSS machine, or it can be a file share directory on a remote file server.

The path can contain environment variables (for example, %SystemRoot%) but cannot contain wildcard characters. UNC paths are supported.

There is no requirement that the path end with a backslash (""). It is up to applications that retrieve this information to check.

[in] wszFileName

Null-terminated wide character string containing the file specification of the files to receive a new restore target.

A file specification cannot contain directory specifications (for example, no backslashes) but can contain the ? and * wildcard characters.

[in] bRecursive

Boolean indicating whether only the files in the directory defined by wszPath and matching the file specification provided by wszFileName are to receive a new restore target, or if all files in the hierarchy defined by wszPath and matching the file specification provided by wszFileName are to receive a new restore target.

For information on traversing mounted folders, see Working with Mounted Folders and Reparse Points.

[in] wszAlternatePath

Null-terminated wide character string containing the fully qualified path of the new restore target directory.

The directory can be a local directory on the VSS machine, or it can be a file share directory on a remote file server.

UNC paths are supported.

Return value

The following are the valid return codes for this method.

Remarks

Windows 7, Windows Server 2008 R2, Windows Vista, Windows Server 2008, Windows XP and Windows Server 2003:  Remote file shares are not supported until Windows 8 and Windows Server 2012.

The component name specified as an argument to AddNewTarget (wszComponentName) must match a component that has already been added to the Backup Components Document.

Therefore, wszComponentName can be the name of any component explicitly included in the Backup Components Document.

Adding a new target for file in a subcomponent must be done using the name of the component that defines the component set containing the subcomponent.

When specifying a file or files to have their restore target changed, a requester must ensure that the combination of path, file specification, and recursion flag (wszPath, wszFileSpec, and bRecursive, respectively) provided to AddNewTarget must match that of one of the file sets added to a component using IVssCreateWriterMetadata::AddFilesToFileGroup, IVssCreateWriterMetadata::AddDatabaseFiles, or IVssCreateWriterMetadata::AddDatabaseLogFiles.

When a requester calls AddNewTarget, it must do so before calling IVssBackupComponents::PreRestore. For more information, see Overview of Preparing for Restore.

Path and file descriptor information can be obtained from the Writer Metadata Document by using the IVssWMFiledesc object returned by IVssWMComponent::GetFile, IVssWMComponent::GetDatabaseFile, or IVssWMComponent::GetDatabaseLogFile. The IVssWMComponent object is obtained from Writer Metadata Document by the IVssExamineWriterMetadata::GetComponent method.

Writers can determine if files have been restored to new locations by using the IVssComponent::GetNewTargetCount and IVssComponent::GetNewTarget methods.

Requirements

See also

IVssBackupComponents

IVssBackupComponents::AddComponent

IVssComponent::GetNewTarget

IVssComponent::GetNewTargetCount

IVssCreateWriterMetadata::AddDatabaseFiles

IVssCreateWriterMetadata::AddDatabaseLogFiles

IVssCreateWriterMetadata::AddFilesToFileGroup

IVssExamineWriterMetadata::GetComponent

IVssWMComponent

IVssWMComponent::GetDatabaseFile

IVssWMComponent::GetDatabaseLogFile

IVssWMComponent::GetFile

IVssWMFiledesc

VSS_COMPONENT_TYPE