Interface IVssDifferentialSoftwareSnapshotManagement

The IVssDifferentialSoftwareSnapshotManagement interface contains methods that allow applications to query and manage shadow copy storage areas generated by the system shadow copy provider.

Namespace: Alphaleonis.Win32.Vss

Assembly: AlphaVSS.Common.dll

Syntax

public interface IVssDifferentialSoftwareSnapshotManagement

Remarks

note

Windows XP: This interface requires Windows Server 2003 or later.

Methods

| Improve this Doc View Source

AddDiffArea(String, String, Int64)

The AddDiffArea(String, String, Int64) method adds a shadow copy storage area association for the specified volume. If the association is not supported, an exception will be thrown.

Declaration

void AddDiffArea(string volumeName, string diffAreaVolumeName, long maximumDiffSpace)

Parameters

Type	Name	Description
String	volumeName	Name of the volume that will be the source of shadow copies that is to be associated with a shadow copy storage area on the `volumeName` volume. The name of the volume must be in one of the following formats: The path of a volume mount point with a backslash (\) A drive letter with backslash (\), for example, `D:\` A unique volume name of the form `\\?\Volume{GUID}\` (where GUID is the unique global identifier of the volume) with a backslash (\)
String	diffAreaVolumeName	Name of the volume that will contain the shadow copy storage area to be associated with the `volumeName` volume. The name of the volume must be in one of the following formats: The path of a volume mount point with a backslash (\) A drive letter with backslash (\), for example, `D:\` A unique volume name of the form `\\?\Volume{GUID}\` (where GUID is the unique global identifier of the volume) with a backslash (\)
Int64	maximumDiffSpace	Specifies the maximum size, in bytes, of the shadow copy storage area on the volume. This value must be at least 300 MB, up to the system-wide limit. Windows Server 2003: Prior to Windows Server 2003 SP1 the shadow copy storage area size was fixed at 100 MB.

Remarks

note

Windows XP: This method is not supported until Windows Server 2003.

Exceptions

Type	Condition
UnauthorizedAccessException	Caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	The caller is out of memory or other system resources.
ArgumentException	One of the parameter values is not valid.
ArgumentNullException	One of the arguments was null
SystemException	Unexpected error. The error code is logged in the error log file.
VssObjectAlreadyExistsException	The association between the `volumeName` and `diffAreaVolumeName` volumes already exists.
VssProviderVetoException	Expected provider error. The provider logged the error in the event log.
VssVolumeNotSupportedException	The `diffAreaVolumeName` volume is not NTFS or has insufficient free space.
VssMaximumDiffAreaAssociationsReachedException	The maximum number of shadow copy storage areas has been added to the shadow copy source volume. The specified shadow copy storage volume was not associated with the specified shadow copy source volume.

| Improve this Doc View Source

ChangeDiffAreaMaximumSize(String, String, Int64)

The ChangeDiffAreaMaximumSize(String, String, Int64) method updates the shadow copy storage area maximum size for a certain volume. This may not have an immediate effect.

Declaration

void ChangeDiffAreaMaximumSize(string volumeName, string diffAreaVolumeName, long maximumDiffSpace)

Parameters

Type	Name	Description
String	volumeName	Name of the volume that is the source of shadow copies that are associated with a shadow copy storage area on the `diffAreaVolumeName` volume. The name of the volume must be in one of the following formats: The path of a volume mount point with a backslash (\) A drive letter with backslash (\), for example, `D:\` A unique volume name of the form `\\?\Volume{GUID}\` (where GUID is the unique global identifier of the volume) with a backslash (\)
String	diffAreaVolumeName	Name of the volume that contains the shadow copy storage area associated with the `volumeName` volume. The name of the volume must be in one of the following formats: The path of a volume mount point with a backslash (\) A drive letter with backslash (\), for example, `D:\` A unique volume name of the form `\\?\Volume{GUID}\` (where GUID is the unique global identifier of the volume) with a backslash (\)
Int64	maximumDiffSpace	Specifies the maximum size, in bytes, for the shadow copy storage area to use for the volume. If this value is zero, the shadow copy storage area will be disabled.

Exceptions

Type	Condition
UnauthorizedAccessException	Caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	The caller is out of memory or other system resources.
ArgumentException	One of the parameter values is not valid.
ArgumentNullException	One of the arguments was null
SystemException	Unexpected error. The error code is logged in the error log file.
VssObjectNotFoundException	The association between the `volumeName` and `diffAreaVolumeName` volumes was not found.
VssProviderVetoException	Expected provider error. The provider logged the error in the event log.
VssInsufficientStorageException	The `diffAreaVolumeName` volume does not have sufficient free space.
VssVolumeInUseException	A shadow copy is currently using the shadow copy storage area.

| Improve this Doc View Source

ChangeDiffAreaMaximumSize(String, String, Int64, Boolean)

The ChangeDiffAreaMaximumSize(String, String, Int64) method updates the shadow copy storage area maximum size for a certain volume. This may not have an immediate effect.

Declaration

void ChangeDiffAreaMaximumSize(string volumeName, string diffAreaVolumeName, long maximumDiffSpace, bool isVolatile)

Parameters

Type	Name	Description
String	volumeName	Name of the volume that is the source of shadow copies that are associated with a shadow copy storage area on the `diffAreaVolumeName` volume. The name of the volume must be in one of the following formats: The path of a volume mount point with a backslash (\) A drive letter with backslash (\), for example, `D:\` A unique volume name of the form `\\?\Volume{GUID}\` (where GUID is the unique global identifier of the volume) with a backslash (\)
String	diffAreaVolumeName	Name of the volume that contains the shadow copy storage area associated with the `volumeName` volume. The name of the volume must be in one of the following formats: The path of a volume mount point with a backslash (\) A drive letter with backslash (\), for example, `D:\` A unique volume name of the form `\\?\Volume{GUID}\` (where GUID is the unique global identifier of the volume) with a backslash (\)
Int64	maximumDiffSpace	Specifies the maximum size, in bytes, for the shadow copy storage area to use for the volume. If this value is zero, the shadow copy storage area will be disabled.
Boolean	isVolatile	true to indicate that the effect of calling the ChangeDiffAreaMaximumSize(String, String, Int64) method should not continue if the computer is rebooted; otherwise, false. If the `maximumDiffSpace` parameter is zero, the `isVolatile` parameter must be false.

Exceptions

Type	Condition
UnauthorizedAccessException	Caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	The caller is out of memory or other system resources.
ArgumentException	One of the parameter values is not valid.
ArgumentNullException	One of the arguments was null
SystemException	Unexpected error. The error code is logged in the error log file.
VssObjectNotFoundException	The association between the `volumeName` and `diffAreaVolumeName` volumes was not found.
VssProviderVetoException	Expected provider error. The provider logged the error in the event log.
VssInsufficientStorageException	The `diffAreaVolumeName` volume does not have sufficient free space.
VssVolumeInUseException	A shadow copy is currently using the shadow copy storage area.

| Improve this Doc View Source

ClearVolumeProtectFault(String)

Clears the protection fault state for the specified volume.

Declaration

void ClearVolumeProtectFault(string volumeName)

Parameters

Type	Name	Description
String	volumeName	The name of the volume. This parameter is required and cannot be null. The name of the volume must be in one of the following formats: The path of a volume mount point with a backslash (\) A drive letter with backslash (\), for example, `D:\` A unique volume name of the form `\\?\Volume{GUID}\` (where GUID is the unique global identifier of the volume) with a backslash (\)

Remarks

The ClearVolumeProtectFault(String) method dismounts the volume and resets the volume's protection fault member to false to allow normal I/O to continue on the volume. If the volume is not in a faulted state, this method does nothing.

note

Windows XP, Windows Server 2003 and Windows Vista: This method requires Windows Server 2008.

Exceptions

Type	Condition
UnauthorizedAccessException	Caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	The caller is out of memory or other system resources.
ArgumentException	One of the parameter values is not valid.
ArgumentNullException	One of the arguments was null
NotImplementedException	The provider for the volume does not support shadow copy protection.
VssProviderVetoException	Expected provider error. The provider logged the error in the event log.
VssObjectNotFoundException	The specified volume was not found.

| Improve this Doc View Source

DeleteUnusedDiffAreas(String)

Deletes all shadow copy storage areas (also called diff areas) on the specified volume that are not in use.

Declaration

void DeleteUnusedDiffAreas(string diffAreaVolumeName)

Parameters

Type	Name	Description
String	diffAreaVolumeName	The name of the volume. This parameter is required and cannot be null. The name of the volume must be in one of the following formats: The path of a volume mount point with a backslash (\) A drive letter with backslash (\), for example, `D:\` A unique volume name of the form `\\?\Volume{GUID}\` (where GUID is the unique global identifier of the volume) with a backslash (\)

Remarks

Unused shadow copy storage area files are found on storage area volumes when the associated original volume is offline due to a protection fault. In certain cases, the original volume may be permanently lost, and calling the DeleteUnusedDiffAreas(String) method is the only way to recover the abandoned storage area space.

note

Windows XP, Windows Server 2003 and Windows Vista: This method requires Windows Server 2008.

Exceptions

Type	Condition
UnauthorizedAccessException	Caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	The caller is out of memory or other system resources.
ArgumentException	One of the parameter values is not valid.
ArgumentNullException	One of the arguments was null
NotImplementedException	The provider for the volume does not support shadow copy protection.
VssProviderVetoException	Expected provider error. The provider logged the error in the event log.
VssObjectNotFoundException	The specified volume was not found.

| Improve this Doc View Source

GetVolumeProtectionLevel(String)

Gets the shadow copy protection level and status for the specified volume.

Declaration

VssVolumeProtectionInfo GetVolumeProtectionLevel(string volumeName)

Parameters

Type	Name	Description
String	volumeName	The name of the volume. This parameter is required and cannot be null. The name of the volume must be in one of the following formats: The path of a volume mount point with a backslash (\) A drive letter with backslash (\), for example, `D:\` A unique volume name of the form `\\?\Volume{GUID}\` (where GUID is the unique global identifier of the volume) with a backslash (\)

Returns

Type	Description
VssVolumeProtectionInfo	A VssVolumeProtectionInfo class instance that contains information about the volume's shadow copy protection level.

Remarks

The GetVolumeProtectionLevel(String) method gets information about the volume's current protection level. If the volume is in a faulted state, the ProtectionFault member of the VssVolumeProtectionInfo structure contains the current protection fault, and the FailureStatus member contains the reason why the volume is in a faulted state. If the volume is not in a faulted state, the ProtectionFault and FailureStatus members will be zero.

Exceptions

Type	Condition
UnauthorizedAccessException	Caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	The caller is out of memory or other system resources.
ArgumentException	One of the parameter values is not valid.
ArgumentNullException	One of the arguments was null
NotImplementedException	The provider for the volume does not support shadow copy protection.
VssProviderVetoException	Expected provider error. The provider logged the error in the event log.
VssObjectNotFoundException	The specified volume was not found.

| Improve this Doc View Source

QueryDiffAreasForSnapshot(Guid)

The QueryDiffAreasForSnapshot(Guid) method queries shadow copy storage areas in use by the original volume associated with the input shadow copy.

Declaration

IList<VssDiffAreaProperties> QueryDiffAreasForSnapshot(Guid snapshotId)

Parameters

Type	Name	Description
Guid	snapshotId	The snapshot id.

Returns

Type	Description
IList<VssDiffAreaProperties>	A list of VssDiffAreaProperties describing the shadow copy storage areas in use by the shadow copy specified.

Exceptions

Type	Condition
UnauthorizedAccessException	Caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	The caller is out of memory or other system resources.
ArgumentException	One of the parameter values is not valid.
ArgumentNullException	One of the arguments was null
SystemException	Unexpected error. The error code is logged in the error log file.
VssProviderVetoException	Expected provider error. The provider logged the error in the event log.

| Improve this Doc View Source

QueryDiffAreasForVolume(String)

The QueryDiffAreasForVolume(String) method queries shadow copy storage areas in use by the volume specified.

Declaration

IList<VssDiffAreaProperties> QueryDiffAreasForVolume(string volumeName)

Parameters

Type	Name	Description
String	volumeName	Name of the volume that contains shadow copy storage areas. The name of the volume must be in one of the following formats: The path of a volume mount point with a backslash (\) A drive letter with backslash (\), for example, `D:\` A unique volume name of the form `\\?\Volume{GUID}\` (where GUID is the unique global identifier of the volume) with a backslash (\)

Returns

Type	Description
IList<VssDiffAreaProperties>	A list containing VssDiffAreaProperties objects describing the shadow copy storage areas in use by the volume specified.

Exceptions

Type	Condition
UnauthorizedAccessException	Caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	The caller is out of memory or other system resources.
ArgumentException	One of the parameter values is not valid.
ArgumentNullException	One of the arguments was null
SystemException	Unexpected error. The error code is logged in the error log file.
VssProviderVetoException	Expected provider error. The provider logged the error in the event log.

| Improve this Doc View Source

QueryDiffAreasOnVolume(String)

The QueryDiffAreasOnVolume(String) method queries shadow copy storage areas that physically reside on the given volume

Declaration

IList<VssDiffAreaProperties> QueryDiffAreasOnVolume(string volumeName)

Parameters

Type	Name	Description
String	volumeName	Name of the volume that contains shadow copy storage areas. The name of the volume must be in one of the following formats: The path of a volume mount point with a backslash (\) A drive letter with backslash (\), for example, `D:\` A unique volume name of the form `\\?\Volume{GUID}\` (where GUID is the unique global identifier of the volume) with a backslash (\)

Returns

Type	Description
IList<VssDiffAreaProperties>	A list of VssDiffAreaProperties objects describing the shadow copy storage areas that physically reside on the given volume.

Exceptions

Type	Condition
UnauthorizedAccessException	Caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	The caller is out of memory or other system resources.
ArgumentException	One of the parameter values is not valid.
ArgumentNullException	One of the arguments was null
SystemException	Unexpected error. The error code is logged in the error log file.
VssProviderVetoException	Expected provider error. The provider logged the error in the event log.

| Improve this Doc View Source

QueryVolumesSupportedForDiffAreas(String)

The QueryVolumesSupportedForDiffAreas(String) method queries volumes that support shadow copy storage areas (including volumes with disabled shadow copy storage areas).

Declaration

IList<VssDiffVolumeProperties> QueryVolumesSupportedForDiffAreas(string originalVolumeName)

Parameters

Type	Name	Description
String	originalVolumeName	Name of the original volume that is the source of the shadow copies. The name of the volume must be in one of the following formats: The path of a volume mount point with a backslash (\) A drive letter with backslash (\), for example, `D:\` A unique volume name of the form `\\?\Volume{GUID}\` (where GUID is the unique global identifier of the volume) with a backslash (\)

Returns

Type	Description
IList<VssDiffVolumeProperties>	A list of VssDiffVolumeProperties describing the volumes that support shadow copy storage areas (including volumes with disabled shadow copy storage areas).

Exceptions

Type	Condition
UnauthorizedAccessException	Caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	The caller is out of memory or other system resources.
ArgumentException	One of the parameter values is not valid.
ArgumentNullException	One of the arguments was null
SystemException	Unexpected error. The error code is logged in the error log file.
VssProviderVetoException	Expected provider error. The provider logged the error in the event log.

| Improve this Doc View Source

SetVolumeProtectionLevel(String, VssProtectionLevel)

Sets the shadow copy protection level for an original volume or a shadow copy storage area volume.

Declaration

void SetVolumeProtectionLevel(string volumeName, VssProtectionLevel protectionLevel)

Parameters

Type	Name	Description
String	volumeName	The name of the volume. This parameter is required and cannot be null. The name of the volume must be in one of the following formats: The path of a volume mount point with a backslash (\) A drive letter with backslash (\), for example, `D:\` A unique volume name of the form `\\?\Volume{GUID}\` (where GUID is the unique global identifier of the volume) with a backslash (\)
VssProtectionLevel	protectionLevel	A value from the VssProtectionLevel enumeration that specifies the shadow copy protection level.

Remarks

The SetVolumeProtectionLevel(String, VssProtectionLevel) method checks the current shadow copy protection level of the volume. If the volume is in a faulted state and OriginalVolume is specified for the protectionLevel parameter, SetVolumeProtectionLevel(String, VssProtectionLevel) dismounts the volume before setting the protection level.

If the current protection level of the volume is the same as the value of the protectionLevel parameter, SetVolumeProtectionLevel(String, VssProtectionLevel) does nothing.

note

Windows XP, Windows Server 2003 and Windows Vista: This method requires Windows Server 2008.

Exceptions

Type	Condition
UnauthorizedAccessException	Caller does not have sufficient backup privileges or is not an administrator.
OutOfMemoryException	The caller is out of memory or other system resources.
ArgumentException	One of the parameter values is not valid.
ArgumentNullException	One of the arguments was null
NotImplementedException	The provider for the volume does not support shadow copy protection.
VssProviderVetoException	Expected provider error. The provider logged the error in the event log.
VssObjectNotFoundException	The specified volume was not found.