Interface IVssComponent

Interface containing methods for examining and modifying information about components contained in a requester's Backup Components Document.

Inherited Members

IDisposable.Dispose()

Namespace: Alphaleonis.Win32.Vss

Assembly: AlphaVSS.Common.dll

Syntax

public interface IVssComponent : IDisposable

Remarks

IVssComponent objects can be obtained only for those components that have been explicitly added to the Backup Components Document during a backup operation by the AddComponent(Guid, Guid, VssComponentType, String, String) method.

Information about components explicitly added during a restore operation using AddRestoreSubcomponent(Guid, VssComponentType, String, String, String, String) are not available through the IVssComponent interface.

For more information, see the MSDN documentation on the IVssComponent Interface.

Properties

AdditionalRestores

The AdditionalRestores is used by a writer during incremental or differential restore operations to determine whether a given component will require additional restore operations to completely retrieve it, but can also be called by a requester.

Declaration

bool AdditionalRestores { get; }

Property Value

Type	Description
Boolean	If true, additional restores will occur for the current component. If false, additional restores will not occur.

AlternateLocationMappings

A collection of mapping information for the file set's alternate location for file restoration.

Declaration

IList<VssWMFileDescriptor> AlternateLocationMappings { get; }

Property Value

Type	Description
IList<VssWMFileDescriptor>	A read-only list containing the alternate location to which files were actually restored. caution This list must not be accessed after the IVssComponent from which it was obtained has been disposed.

Remarks

See the MSDN documentation on the IVssComponent::GetAlternateLocationMapping method for more information.

BackupOptions

The backup options specified to the writer that manages the currently selected component or component set by a requester using SetBackupOptions(Guid, VssComponentType, String, String, String).

Declaration

string BackupOptions { get; }

Property Value

Type	Description
String	The backup options for the current writer.

BackupStamp

The backup stamp string stored by a writer for a given component.

Declaration

string BackupStamp { get; }

Property Value

Type	Description
String	The backup stamp indicating the time at which the component was backed up.

BackupSucceeded

The status of a complete attempt at backing up all the files of a selected component or component set as a VssFileRestoreStatus enumeration.

Declaration

bool BackupSucceeded { get; }

Property Value

Type	Description
Boolean	true if the backup was successful and false if it was not.

ComponentName

The logical name of this component.

Declaration

string ComponentName { get; }

Property Value

Type	Description
String	The logical name of this component.

ComponentType

The type of this component in terms of the ComponentType enumeration.

Declaration

VssComponentType ComponentType { get; }

Property Value

Type	Description
VssComponentType	The type of this component.

DifferencedFiles

Information about the file sets (specified file or files) to participate in an incremental or differential backup or restore as a differenced file — that is, backup and restores associated with it are to be implemented as if entire files are copied to and from backup media (as opposed to using partial files).

Declaration

IList<VssDifferencedFileInfo> DifferencedFiles { get; }

Property Value

Type	Description
IList<VssDifferencedFileInfo>	A read only list containing the diffrenced files associated with this component. caution This list must not be accessed after the IVssComponent from which it was obtained has been disposed.

Remarks

Windows XP: This method requires Windows Server 2003 or later

DirectedTargets

Information stored by a writer, at backup time, to the Backup Components Document to indicate that when a file is to be restored, it (the source file) should be remapped. The file may be restored to a new restore target and/or ranges of its data restored to different locations with the restore target.

Declaration

IList<VssDirectedTargetInfo> DirectedTargets { get; }

Property Value

Type	Description
IList<VssDirectedTargetInfo>	A read-only list containing the directed targets of this component. caution This list must not be accessed after the IVssComponent from which it was obtained has been disposed.

Failure

VSS requesters read this property to retrieve component-level errors reported by writers. VSS writers set this property to report errors at the component level.

Declaration

VssComponentFailure Failure { get; set; }

Property Value

Type	Description
VssComponentFailure	An instance of VssComponentFailure containing the information reported by the writer.

Remarks

Minimum supported client: Windows 7, Minimum supported server: Windows Server 2008 R2

Exceptions

Type	Condition
VssBadStateException	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.

FileRestoreStatus

The status of a completed attempt to restore all the files of a selected component or component set as a VssFileRestoreStatus enumeration.

Declaration

VssFileRestoreStatus FileRestoreStatus { get; }

Property Value

Type	Description
VssFileRestoreStatus	A value of the VssFileRestoreStatus enumeration that specifies whether all files were successfully restored.

IsAuthoritativeRestore

Gets a value indicating whether a requester has marked the restore of a component as authoritative for a replicated data store.

Declaration

bool IsAuthoritativeRestore { get; }

Property Value

Type	Description
Boolean	true if the restore is authoritative; otherwise, false.

Remarks

A writer indicates that it supports authoritative restore by setting the AuthoritativeRestore flag in its backup schema mask.

For more information, see Setting VSS Restore Options.

note

Windows XP and Windows 2003: This property requires Windows Vista or later and will always return false on unsupported operating systems.

IsSelectedForRestore

Determines whether the current component has been selected to be restored.

Declaration

bool IsSelectedForRestore { get; }

Property Value

Type	Description
Boolean	If the returned value of this parameter is true, the component has been selected to be restored. If false, it has not been selected.

LogicalPath

The logical path of this component.

Declaration

string LogicalPath { get; }

Property Value

Type	Description
String	The logical path of this component.

NewTargets

The new file restoration locations for the selected component or component set.

Declaration

IList<VssWMFileDescriptor> NewTargets { get; }

Property Value

Type	Description
IList<VssWMFileDescriptor>	A read-only list contianing the new file restoration locations for the selected component or component set. caution This list must not be accessed after the IVssComponent from which it was obtained has been disposed.

PartialFiles

Information about any partial files associated with this component.

Declaration

IList<VssPartialFileInfo> PartialFiles { get; }

Property Value

Type	Description
IList<VssPartialFileInfo>	A read-only list containing information about any partial files associated with this component. caution This list must not be accessed after the IVssComponent from which it was obtained has been disposed.

PostRestoreFailureMsg

The failure message generated by a writer while handling the PostRestore event if one was set.

Declaration

string PostRestoreFailureMsg { get; }

Property Value

Type	Description
String	The failure message that describes an error that occurred while processing the PostRestore event.

PostSnapshotFailureMsg

Gets the PostSnapshot failure message string that a writer has set for a given component.

Declaration

string PostSnapshotFailureMsg { get; }

Property Value

Type	Description
String	A string containing the failure message that describes an error that occurred while processing a PostSnapshot event, or null if no value was set or the method is not supported on the current operating system.

Remarks

Both writers and requesters can call this method.

note

Windows XP and Windows 2003: This property requires Windows Vista or later and will always return false on unsupported operating systems.

PrepareForBackupFailureMsg

Gets the PrepareForBackup failure message string that a writer has set for a given component.

Declaration

string PrepareForBackupFailureMsg { get; }

Property Value

Type	Description
String	A string containing the failure message that describes an error that occurred while processing a PrepareForBackup event, or null if no failure message was set for this component, or if the property is not supported on the current operating system.

Remarks

Both writers and requesters can call this method.

note

Windows XP and Windows 2003: This property requires Windows Vista or later and will always return false on unsupported operating systems.

PreRestoreFailureMsg

The failure message generated by a writer while handling the PreRestore event if one was set.

Declaration

string PreRestoreFailureMsg { get; }

Property Value

Type	Description
String	The failure message that describes an error that occurred while processing the PreRestore event.

PreviousBackupStamp

A previous backup stamp loaded by a requester in the Backup Components Document. The value is used by a writer when deciding if files should participate in differential or incremental backup operation.

Declaration

string PreviousBackupStamp { get; }

Property Value

Type	Description
String	The time stamp of a previous backup so that a differential or incremental backup can be correctly implemented.

RestoreName

Obtains the logical name assigned to a component that is being restored.

Declaration

string RestoreName { get; }

Property Value

Type	Description
String	A string containing the restore name for the component, or null if the operation is not supported on the current operating system.

Remarks

The RestoreName property can only be accessed during a restore operation.

A writer indicates that it supports this method by setting the RestoreRename flag in its backup schema mask.

For more information, see Setting VSS Restore Options.

note

Windows XP and Windows 2003: This property requires Windows Vista or later and will always return false on unsupported operating systems.

RestoreOptions

The restore options specified to the current writer by a requester using SetRestoreOptions(Guid, VssComponentType, String, String, String).

Declaration

string RestoreOptions { get; }

Property Value

Type	Description
String	The restore options of the writer.

RestoreSubcomponents

The subcomponents associated with this component.

Declaration

IList<VssRestoreSubcomponentInfo> RestoreSubcomponents { get; }

Property Value

Type	Description
IList<VssRestoreSubcomponentInfo>	A read only list containing the subcomponents associated with this component. caution This list must not be accessed after the IVssComponent from which it was obtained has been disposed.

RestoreTarget

The restore target (in terms of the VssRestoreTarget enumeration) for the current component. Can only be called during a restore operation.

Declaration

VssRestoreTarget RestoreTarget { get; }

Property Value

Type	Description
VssRestoreTarget	A value from the VssRestoreTarget enumeration containing the restore target information.

RollForwardRestorePoint

Obtains the restore point for a partial roll-forward operation.

Declaration

string RollForwardRestorePoint { get; }

Property Value

Type	Description
String	A string specifying the roll-forward restore point, or null if the property is not supported in the current context.

Remarks

The RollForwardRestorePoint property can only be accessed during a restore operation.

A writer indicates that it supports this method by setting the RollForwardRestore flag in its backup schema mask.

For more information, see Setting VSS Restore Options.

note

Windows XP and Windows 2003: This property requires Windows Vista or later and will always return Undefined on unsupported operating systems.

RollForwardType

Obtains the roll-forward operation type for a component.

Declaration

VssRollForwardType RollForwardType { get; }

Property Value

Type	Description
VssRollForwardType	A VssRollForwardType enumeration value indicating the type of roll-forward operation to be performed, or Undefined if the property is not supported in the current context.

Remarks

The RollForwardType property can only be accessed during a restore operation.

A writer indicates that it supports this method by setting the RollForwardRestore flag in its backup schema mask.

For more information, see Setting VSS Restore Options.

note

Windows XP and Windows 2003: This property requires Windows Vista or later and will always return Undefined on unsupported operating systems.