Export (0) Print
Expand All
5 out of 5 rated this helpful - Rate this topic

IVssBackupComponents::AddNewTarget method

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

writerId [in]

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

ct [in]

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

wszLogicalPath [in]

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.

wszComponentName [in]

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.

wszPath [in]

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.

wszFileName [in]

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.

bRecursive [in]

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.

wszAlternatePath [in]

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.

ValueMeaning
S_OK

Successfully added the new restore target.

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, or this method has been called during a restore operation.

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_NOT_FOUND

The component does not exist or the path and file specification do not match a component and file specification in the component.

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

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

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

VsBackup.h (include VsBackup.h, Vss.h, or VsWriter.h)

Library

VssApi.lib

See also

IVssBackupComponents
VSS_COMPONENT_TYPE
IVssBackupComponents::AddComponent
IVssCreateWriterMetadata::AddFilesToFileGroup
IVssCreateWriterMetadata::AddDatabaseFiles
IVssCreateWriterMetadata::AddDatabaseLogFiles
IVssWMFiledesc
IVssWMComponent::GetFile
IVssWMComponent::GetDatabaseFile
IVssWMComponent::GetDatabaseLogFile
IVssWMComponent
IVssExamineWriterMetadata::GetComponent
IVssComponent::GetNewTargetCount
IVssComponent::GetNewTarget

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.