IVssComponent::AddDirectedTarget method (vswriter.h)

Article
10/13/2021

The AddDirectedTarget method allows a writer to indicate at restore time that when a file is to be restored, it (the source file) should be remapped. The file can be restored to a new restore location and/or ranges of its data restored to different offsets within the restore location.

This method can be called by a writer only during a restore operation.

This method cannot be called while handling a BackupComplete (CVssWriter::OnBackupComplete) or BackupShutdown (CVssWriter::OnBackupShutdown) event.

Syntax

HRESULT AddDirectedTarget(
  [in] LPCWSTR wszSourcePath,
  [in] LPCWSTR wszSourceFilename,
  [in] LPCWSTR wszSourceRangeList,
  [in] LPCWSTR wszDestinationPath,
  [in] LPCWSTR wszDestinationFilename,
  [in] LPCWSTR wszDestinationRangeList
);

Parameters

[in] wszSourcePath

Null-terminated wide character string containing the path to the directory at restore time containing the file to be restored (the source file). This path should match or be beneath the path of a file set already in the component (or one of its subcomponents if the component defines a component set).

[in] wszSourceFilename

Null-terminated wide character string containing the name of the file (at backup time) that will be remapped at restore time (the source file). The name of the file (wszSourceFilename) cannot contain wildcard characters (* or ?) and must be consistent with the file specification of a file set containing the source path (wszSourcePath).

[in] wszSourceRangeList

A null-terminated wide character string containing a comma-separated list of file offsets and lengths indicating the source file support range (the sections of the file to actually be restored).

The number and length of the source file support ranges must match the number and size of destination file support ranges.

[in] wszDestinationPath

Null-terminated wide character string containing the path to which source file data will be remapped at restore time.

[in] wszDestinationFilename

Null-terminated wide character string containing the name of the file to which source file data will be remapped at restore time. The name of the file (wszDestinationFilename) cannot contain wildcard characters (* or ?).

[in] wszDestinationRangeList

A null-terminated wide character string containing a comma-separated list of file offsets and lengths indicating the destination file support range (locations to which the sections of the source file are to be restored).

The number and length of the destination file support ranges must match the number and size of source file support ranges.

Return value

The following are the valid return codes for this method.

Value	Meaning
S_OK	Successfully set the item.
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	This method was not called by a writer or, if called by a writer, it either was not called during a restore operation or was called while handling a BackupComplete or BackupShutdown event.

Remarks

Only a writer can call AddDirectedTarget, and only during restore operations.

A requester will use the directed target information stored in the Backup Components Document only if the restore target is VSS_RT_DIRECTED.

The AddDirectedTarget method can be applied to any file managed in the current component or, if the component defines a component set, in any of its nonselectable subcomponents.

Source and destination file specifications may point to the same file. This would allow remapping of a file into itself at restore time.

The syntax of the range listing (wszSourceRanges and wszDestinationRanges) is that of a comma-separated list of the form offset1:length1, offset2:length2, where each offset and length is a 64-bit integer specifying a byte offset and length in bytes, respectively. The offset and length can be expressed either as hexadecimal or decimal values.

The number of entries and their sizes must match in the source and destination range arguments.

AddDirectedTarget can use as its source file any file already managed by the component or one of its subcomponents if the component defines a component set.

Partial files may be added as directed targets, if the partial file ranges to be backed up match the directed target source ranges (see IVssComponent::AddPartialFile). This will allow you to remap partial files at restore time.

In this case, the requester retrieves the directed target information by calling the IVssComponent::GetDirectedTarget method and uses that to implement the remapping of the backed-up data during restore.

Requirements

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