diff --git a/PInvoke/VssApi/vdslun.cs b/PInvoke/VssApi/vdslun.cs new file mode 100644 index 00000000..d26f50c8 --- /dev/null +++ b/PInvoke/VssApi/vdslun.cs @@ -0,0 +1,444 @@ +using System; +using System.Runtime.InteropServices; + +namespace Vanara.PInvoke.VssApi +{ + /// + /// + /// [Beginning with Windows 8 and Windows Server 2012, the Virtual Disk Service COM interface is superseded by the Windows Storage + /// Management API.] + /// + /// Defines the set of the valid address types of a physical interconnect. + /// + /// + /// + /// The VDS_INTERCONNECT structure includes a VDS_INTERCONNECT_ADDRESS_TYPE value as a member to indicate an interconnect address type. + /// + /// + /// Note Additional constants might be added to the VDS_INTERCONNECT_ADDRESS_TYPE enumeration in future Windows versions. + /// For this reason, your application must be designed to gracefully handle an unrecognized VDS_INTERCONNECT_ADDRESS_TYPE + /// enumeration constant. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vdslun/ne-vdslun-vds_interconnect_address_type typedef enum + // _VDS_INTERCONNECT_ADDRESS_TYPE { VDS_IA_UNKNOWN, VDS_IA_FCFS, VDS_IA_FCPH, VDS_IA_FCPH3, VDS_IA_MAC, VDS_IA_SCSI } VDS_INTERCONNECT_ADDRESS_TYPE; + [PInvokeData("vdslun.h", MSDNShortId = "NE:vdslun._VDS_INTERCONNECT_ADDRESS_TYPE")] + public enum VDS_INTERCONNECT_ADDRESS_TYPE + { + /// This value is reserved. + VDS_IA_UNKNOWN = 0, + + /// The address type is FCFS. + VDS_IA_FCFS, + + /// The address type is FCPH. + VDS_IA_FCPH, + + /// The address type is FCPH3. + VDS_IA_FCPH3, + + /// The address type is MAC. + VDS_IA_MAC, + + /// The address type is SCSI. + VDS_IA_SCSI, + } + + /// + /// + /// [Beginning with Windows 8 and Windows Server 2012, the Virtual Disk Service COM interface is superseded by the Windows Storage + /// Management API.] + /// + /// Defines the set of valid bus types of a storage device. + /// + /// + /// + /// The VDS_LUN_INFORMATION, VDS_DISK_PROP, VDS_DISK_PROP2, and VDS_DRIVE_PROP2 structures include a VDS_STORAGE_BUS_TYPE value + /// as a member to specify the bus type of a LUN, disk, or drive. + /// + /// + /// Note The type specified in these structures matches the type that the driver or drivers reported and may not exactly match + /// the hardware. + /// + /// + /// Note Additional constants might be added to the VDS_STORAGE_BUS_TYPE enumeration in future Windows versions. For this + /// reason, your application must be designed to gracefully handle an unrecognized VDS_STORAGE_BUS_TYPE enumeration constant. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vdslun/ne-vdslun-vds_storage_bus_type typedef enum _VDS_STORAGE_BUS_TYPE { + // VDSBusTypeUnknown, VDSBusTypeScsi, VDSBusTypeAtapi, VDSBusTypeAta, VDSBusType1394, VDSBusTypeSsa, VDSBusTypeFibre, VDSBusTypeUsb, + // VDSBusTypeRAID, VDSBusTypeiScsi, VDSBusTypeSas, VDSBusTypeSata, VDSBusTypeSd, VDSBusTypeMmc, VDSBusTypeMax, VDSBusTypeVirtual, + // VDSBusTypeFileBackedVirtual, VDSBusTypeSpaces, VDSBusTypeNVMe, VDSBusTypeScm, VDSBusTypeUfs, VDSBusTypeMaxReserved } VDS_STORAGE_BUS_TYPE; + [PInvokeData("vdslun.h", MSDNShortId = "NE:vdslun._VDS_STORAGE_BUS_TYPE")] + public enum VDS_STORAGE_BUS_TYPE + { + /// This value is reserved. + VDSBusTypeUnknown = 0, + + /// The storage bus type is SCSI. + VDSBusTypeScsi, + + /// The storage bus type is ATAPI. + VDSBusTypeAtapi, + + /// The storage bus type is ATA. + VDSBusTypeAta, + + /// The storage bus type is IEEE 1394. + VDSBusType1394, + + /// The storage bus type is SSA. + VDSBusTypeSsa, + + /// The storage bus type is Fibre Channel. + VDSBusTypeFibre, + + /// The storage bus type is USB. + VDSBusTypeUsb, + + /// The storage bus type is RAID. + VDSBusTypeRAID, + + /// The storage bus type is iSCSI. + VDSBusTypeiScsi, + + /// The storage bus type is Serial Attached SCSI (SAS). + VDSBusTypeSas, + + /// The storage bus type is SATA. + VDSBusTypeSata, + + /// + /// The storage bus type is Secure Digital (SD). + /// Windows Server 2008, Windows Vista and Windows Server 2003: + /// Not supported. + /// + VDSBusTypeSd, + + /// + /// The storage bus type is MultiMedia Card (MMC). + /// Windows Server 2008, Windows Vista and Windows Server 2003: + /// Not supported. + /// + VDSBusTypeMmc, + + /// + /// This value is reserved for system use. + /// Windows Server 2008, Windows Vista and Windows Server 2003: + /// Not supported. + /// + VDSBusTypeMax, + + /// + VDSBusTypeVirtual = 0xe, + + /// + /// The storage bus type is file-backed virtual. + /// Windows Server 2008, Windows Vista and Windows Server 2003: + /// Not supported. + /// + VDSBusTypeFileBackedVirtual, + + /// + VDSBusTypeSpaces, + + /// + VDSBusTypeNVMe, + + /// + VDSBusTypeScm, + + /// + VDSBusTypeUfs, + + /// The maximum value of the storage bus type range. + VDSBusTypeMaxReserved = 0x7f, + } + + /// + /// + /// [Beginning with Windows 8 and Windows Server 2012, the Virtual Disk Service COM interface is superseded by the Windows Storage + /// Management API.] + /// + /// Defines the set of the valid code sets (encodings) of a storage identifier. + /// + /// + /// + /// The VDS_STORAGE_IDENTIFIER structure includes a VDS_STORAGE_IDENTIFIER_CODE_SET value as a member to indicate the code set of + /// a storage identifier. + /// + /// + /// Note Additional constants might be added to the VDS_STORAGE_IDENTIFIER_CODE_SET enumeration in future Windows + /// versions. For this reason, your application must be designed to gracefully handle an unrecognized + /// VDS_STORAGE_IDENTIFIER_CODE_SET enumeration constant. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vdslun/ne-vdslun-vds_storage_identifier_code_set typedef enum + // _VDS_STORAGE_IDENTIFIER_CODE_SET { VDSStorageIdCodeSetReserved, VDSStorageIdCodeSetBinary, VDSStorageIdCodeSetAscii, + // VDSStorageIdCodeSetUtf8 } VDS_STORAGE_IDENTIFIER_CODE_SET; + [PInvokeData("vdslun.h", MSDNShortId = "NE:vdslun._VDS_STORAGE_IDENTIFIER_CODE_SET")] + public enum VDS_STORAGE_IDENTIFIER_CODE_SET + { + /// This value is reserved. + VDSStorageIdCodeSetReserved = 0, + + /// The storage identifier is encoded as binary data. + VDSStorageIdCodeSetBinary, + + /// The storage identifier is encoded as ASCII data. + VDSStorageIdCodeSetAscii, + + /// + /// The storage identifier is encoded as UTF-8. + /// Windows Vista and Windows Server 2003: + /// Not supported before Windows Vista with SP1 and Windows Server 2008. + /// + VDSStorageIdCodeSetUtf8, + } + + /// + /// + /// [Beginning with Windows 8 and Windows Server 2012, the Virtual Disk Service COM interface is superseded by the Windows Storage + /// Management API.] + /// + /// Defines the set of valid types for a storage identifier. + /// + /// + /// + /// The VDS_STORAGE_IDENTIFIER structure includes a VDS_STORAGE_IDENTIFIER_TYPE value as a member to indicate the storage + /// identifier type. + /// + /// + /// Note Additional constants might be added to the VDS_STORAGE_IDENTIFIER_TYPE enumeration in future Windows versions. + /// For this reason, your application must be designed to gracefully handle an unrecognized VDS_STORAGE_IDENTIFIER_TYPE + /// enumeration constant. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vdslun/ne-vdslun-vds_storage_identifier_type typedef enum + // _VDS_STORAGE_IDENTIFIER_TYPE { VDSStorageIdTypeVendorSpecific, VDSStorageIdTypeVendorId, VDSStorageIdTypeEUI64, + // VDSStorageIdTypeFCPHName, VDSStorageIdTypePortRelative, VDSStorageIdTypeTargetPortGroup, VDSStorageIdTypeLogicalUnitGroup, + // VDSStorageIdTypeMD5LogicalUnitIdentifier, VDSStorageIdTypeScsiNameString } VDS_STORAGE_IDENTIFIER_TYPE; + [PInvokeData("vdslun.h", MSDNShortId = "NE:vdslun._VDS_STORAGE_IDENTIFIER_TYPE")] + public enum VDS_STORAGE_IDENTIFIER_TYPE + { + /// The storage identifier type is vendor specific. + VDSStorageIdTypeVendorSpecific = 0, + + /// The storage identifier is the same as the vendor identifier. + VDSStorageIdTypeVendorId, + + /// The storage identifier type follows the IEEE 64-bit Extended Unique Identifier (EUI-64) standard. + VDSStorageIdTypeEUI64, + + /// + /// The storage identifier type follows the Fibre Channel Physical and Signaling Interface (FC-PH) naming + /// convention. + /// + VDSStorageIdTypeFCPHName, + + /// + /// VDS 1.1: + /// The storage identifier type is dependent on the port. + /// + VDSStorageIdTypePortRelative, + + /// + VDSStorageIdTypeTargetPortGroup, + + /// + VDSStorageIdTypeLogicalUnitGroup, + + /// + VDSStorageIdTypeMD5LogicalUnitIdentifier, + + /// + VDSStorageIdTypeScsiNameString, + } + + /// + /// + /// [Beginning with Windows 8 and Windows Server 2012, the Virtual Disk Service COM interface is superseded by the Windows Storage + /// Management API.] + /// + /// Defines the address data of a physical interconnect. + /// + /// + /// The VDS_LUN_INFORMATION structure includes this structure as a member to specify an interconnect by which a LUN can be accessed. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vdslun/ns-vdslun-vds_interconnect typedef struct _VDS_INTERCONNECT { + // VDS_INTERCONNECT_ADDRESS_TYPE m_addressType; ULONG m_cbPort; BYTE *m_pbPort; ULONG m_cbAddress; BYTE *m_pbAddress; } VDS_INTERCONNECT; + [PInvokeData("vdslun.h", MSDNShortId = "NS:vdslun._VDS_INTERCONNECT")] + [StructLayout(LayoutKind.Sequential)] + public struct VDS_INTERCONNECT + { + /// The interconnect address type enumerated by VDS_INTERCONNECT_ADDRESS_TYPE. + public VDS_INTERCONNECT_ADDRESS_TYPE m_addressType; + + /// The size of the interconnect address data for the LUN port ( m_pbPort), in bytes. + public uint m_cbPort; + + /// Pointer to the interconnect address data for the LUN port. + public IntPtr m_pbPort; + + /// The size of the interconnect address data for the LUN ( m_pbAddress), in bytes. + public uint m_cbAddress; + + /// Pointer to the interconnect address data for the LUN. + public IntPtr m_pbAddress; + } + + /// + /// + /// [Beginning with Windows 8 and Windows Server 2012, the Virtual Disk Service COM interface is superseded by the Windows Storage + /// Management API.] + /// + /// Defines information about a LUN or disk. Applications can use this structure to uniquely identify a LUN at all times. + /// + /// + /// + /// The VDS_LUN_INFORMATION structure includes fields from the SCSI Inquiry Data and Vital Product Data pages 0x80 and 0x83. The + /// GetIdentificationData method on both the IVdsLun and IVdsDisk interfaces return this structure. It is also passed as an + /// argument in the IVdsHwProviderPrivate::QueryIfCreatedLun method to determine whether a given provider owns a specified LUN. + /// + /// + /// To get the LUN object, use the IVdsService::GetObject method. You can then use the IVdsLun::GetProperties method to get the LUN properties. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vdslun/ns-vdslun-vds_lun_information typedef struct _VDS_LUN_INFORMATION { ULONG + // m_version; BYTE m_DeviceType; BYTE m_DeviceTypeModifier; BOOL m_bCommandQueueing; VDS_STORAGE_BUS_TYPE m_BusType; char *m_szVendorId; + // char *m_szProductId; char *m_szProductRevision; char *m_szSerialNumber; GUID m_diskSignature; VDS_STORAGE_DEVICE_ID_DESCRIPTOR + // m_deviceIdDescriptor; ULONG m_cInterconnects; VDS_INTERCONNECT *m_rgInterconnects; } VDS_LUN_INFORMATION; + [PInvokeData("vdslun.h", MSDNShortId = "NS:vdslun._VDS_LUN_INFORMATION")] + [StructLayout(LayoutKind.Sequential)] + public struct VDS_LUN_INFORMATION + { + /// + public const uint VER_VDS_LUN_INFORMATION = 1; + + /// The version of this structure. The current value is the constant VER_VDS_LUN_INFORMATION. + public uint m_version; + + /// The SCSI-2 device type of the LUN. + public byte m_DeviceType; + + /// The SCSI-2 device type modifier of the LUN. For LUNs that have no device type modifier, the value is zero. + public byte m_DeviceTypeModifier; + + /// + /// If TRUE, the LUN supports multiple outstanding commands; otherwise, FALSE. The synchronization of the queue is the + /// responsibility of the port driver. + /// + [MarshalAs(UnmanagedType.Bool)] + public bool m_bCommandQueueing; + + /// The bus type of the LUN enumerated by VDS_STORAGE_BUS_TYPE. + public VDS_STORAGE_BUS_TYPE m_BusType; + + /// + /// Pointer to the LUN vendor identifier; a zero-terminated, human-readable string. For devices that have no vendor identifier, the + /// value is zero. + /// + [MarshalAs(UnmanagedType.LPStr)] + public string m_szVendorId; + + /// + /// Pointer to the LUN product identifier, typically a model number; a zero-terminated, human-readable string. For devices that have + /// no product identifier, the value is zero. + /// + [MarshalAs(UnmanagedType.LPStr)] + public string m_szProductId; + + /// + /// Pointer to the LUN product revision; a zero-terminated, human-readable string. For devices that have no product revision, the + /// value is zero. + /// + [MarshalAs(UnmanagedType.LPStr)] + public string m_szProductRevision; + + /// + /// Pointer to the LUN serial number; a zero-terminated, human-readable string. For devices that have no serial number, the value is zero. + /// + [MarshalAs(UnmanagedType.LPStr)] + public string m_szSerialNumber; + + /// + /// The signature of the LUN. For disks that use the Master Boot Record (MBR) partitioning structure, the first 32 bits of the GUID + /// comprise the disk signature, and the remaining bits are zeros. For disks that use the GUID Partition Table (GPT) partitioning + /// structure, the GUID consists of the GPT disk identifier. If this value is zero, the disk is uninitialized or the hardware + /// provider was unable to retrieve the signature. + /// + public Guid m_diskSignature; + + /// + /// Array containing the LUN descriptor in various formats, such as "VDSStorageIdTypeFCPHName" and "VDSStorageIdTypeVendorSpecific". + /// Providers can use "VDSStorageIdTypeVendorSpecific" to store an arbitrary byte string of the vendor's choosing to uniquely + /// identify the LUN. See the VDS_STORAGE_DEVICE_ID_DESCRIPTOR structure and the VDS_STORAGE_IDENTIFIER structure. + /// + public VDS_STORAGE_DEVICE_ID_DESCRIPTOR m_deviceIdDescriptor; + + /// The number of interconnect ports specified in m_rgInterconnects. + public uint m_cInterconnects; + + /// + /// Pointer to an array of the interconnect ports by which the LUN can be accessed. See the structure. + /// + public IntPtr m_rgInterconnects; + } + + /// + /// + /// [Beginning with Windows 8 and Windows Server 2012, the Virtual Disk Service COM interface is superseded by the Windows Storage + /// Management API.] + /// + /// Defines one or more storage identifiers for a storage device (typically an instance, as opposed to a class, of device). + /// + /// + /// Storage devices can have multiple identifiers, and each of these identifiers can have a different code set and type. The + /// VDS_LUN_INFORMATION structure includes this structure as a member to specify the storage device identifiers of a LUN. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vdslun/ns-vdslun-vds_storage_device_id_descriptor typedef struct + // _VDS_STORAGE_DEVICE_ID_DESCRIPTOR { ULONG m_version; ULONG m_cIdentifiers; VDS_STORAGE_IDENTIFIER *m_rgIdentifiers; } VDS_STORAGE_DEVICE_ID_DESCRIPTOR; + [PInvokeData("vdslun.h", MSDNShortId = "NS:vdslun._VDS_STORAGE_DEVICE_ID_DESCRIPTOR")] + [StructLayout(LayoutKind.Sequential)] + public struct VDS_STORAGE_DEVICE_ID_DESCRIPTOR + { + /// The version of this structure. + public uint m_version; + + /// The number of identifiers specified in m_rgIdentifiers. + public uint m_cIdentifiers; + + /// Pointer to structure. + public IntPtr m_rgIdentifiers; + } + + /// + /// + /// [Beginning with Windows 8 and Windows Server 2012, the Virtual Disk Service COM interface is superseded by the Windows Storage + /// Management API.] + /// + /// Defines a storage device using a particular code set and type. + /// + /// + /// The VDS_STORAGE_DEVICE_ID_DESCRIPTOR structure includes this structure as a member to specify a particular storage device identifier + /// for a LUN. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vdslun/ns-vdslun-vds_storage_identifier typedef struct _VDS_STORAGE_IDENTIFIER { + // VDS_STORAGE_IDENTIFIER_CODE_SET m_CodeSet; VDS_STORAGE_IDENTIFIER_TYPE m_Type; ULONG m_cbIdentifier; BYTE *m_rgbIdentifier; } VDS_STORAGE_IDENTIFIER; + [PInvokeData("vdslun.h", MSDNShortId = "NS:vdslun._VDS_STORAGE_IDENTIFIER")] + [StructLayout(LayoutKind.Sequential)] + public struct VDS_STORAGE_IDENTIFIER + { + /// The encoding type of m_rgbIdentifier enumerated by VDS_STORAGE_IDENTIFIER_CODE_SET. + public VDS_STORAGE_IDENTIFIER_CODE_SET m_CodeSet; + + /// The type of m_rgbIdentifier enumerated by VDS_STORAGE_IDENTIFIER_TYPE. + public VDS_STORAGE_IDENTIFIER_TYPE m_Type; + + /// The size of the m_rgbIdentifier array, in bytes. + public uint m_cbIdentifier; + + /// Pointer to the identifier data. + public IntPtr m_rgbIdentifier; + } +} \ No newline at end of file diff --git a/PInvoke/VssApi/vsadmin.cs b/PInvoke/VssApi/vsadmin.cs new file mode 100644 index 00000000..ddf938f5 --- /dev/null +++ b/PInvoke/VssApi/vsadmin.cs @@ -0,0 +1,152 @@ +using System; +using System.Runtime.InteropServices; + +namespace Vanara.PInvoke.VssApi +{ + /// The IVssAdmin interface manages providers registered with VSS. + // https://docs.microsoft.com/en-us/windows/win32/api/vsadmin/nn-vsadmin-ivssadmin + [PInvokeData("vsadmin.h", MSDNShortId = "NN:vsadmin.IVssAdmin")] + [ComImport, Guid("77ED5996-2F63-11d3-8A39-00C04F72D8E3"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown), CoClass(typeof(VSSCoordinator))] + public interface IVssAdmin + { + /// The RegisterProvider method registers a new shadow copy provider. + /// + /// The VSS_ID that uniquely and persistently identifies the provider. After it is defined, the ProviderId parameter should + /// remain the same, even when the software revision is updated. A ProviderId parameter should be changed only when the + /// functionality changes enough that both providers would be active on the same system. A requester may use the ProviderId + /// parameter to request that a specific provider be used in a shadow copy creation. + /// + /// The CLSID of the provider. + /// The name of the provider. + /// + /// A VSS_PROVIDER_TYPE enumeration value that specifies the provider type. Note that VSS_PROV_HARDWARE is not a valid + /// provider type on Windows client operating system versions. Hardware providers will run only on Windows server operating system versions. + /// + /// The version of the provider. + /// + /// The VSS_ID that uniquely identifies this version of the provider. The combination of the pProviderId and + /// ProviderVersionId parameters should be unique. The ProviderVersionId parameter can be the same as the ProviderVersionId + /// parameter of another provider. + /// + /// + /// + /// If the hardware provider is updated, the setup application should call the UnregisterProvider method to unregister the outdated + /// version, and then call the RegisterProvider method to register the updated provider. + /// + /// Note Hardware providers can only be registered on Windows Server operating systems. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsadmin/nf-vsadmin-ivssadmin-registerprovider HRESULT RegisterProvider( [in] + // VSS_ID pProviderId, [in] CLSID ClassId, [in] VSS_PWSZ pwszProviderName, [in] VSS_PROVIDER_TYPE eProviderType, [in] VSS_PWSZ + // pwszProviderVersion, [in] VSS_ID ProviderVersionId ); + void RegisterProvider(Guid pProviderId, Guid ClassId, [MarshalAs(UnmanagedType.LPWStr)] string pwszProviderName, + VSS_PROVIDER_TYPE eProviderType, [MarshalAs(UnmanagedType.LPWStr)] string pwszProviderVersion, Guid ProviderVersionId); + + /// The UnregisterProvider method unregisters an existing provider. + /// The VSS_ID of the provider. + // https://docs.microsoft.com/en-us/windows/win32/api/vsadmin/nf-vsadmin-ivssadmin-unregisterprovider HRESULT UnregisterProvider( + // [in] VSS_ID ProviderId ); + void UnregisterProvider(Guid ProviderId); + + /// The QueryProviders method queries all registered providers. + /// The address of an IVssEnumObject interface pointer, which is initialized on return. Callers must release the interface. + /// + /// Calling the IVssEnumObject::Next method on the IVssEnumObject interface returned though the ppEnum parameter will return + /// VSS_OBJECT_PROP structures containing a VSS_PROVIDER_PROP structure for each registered provider. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsadmin/nf-vsadmin-ivssadmin-queryproviders HRESULT QueryProviders( [out] + // IVssEnumObject **ppEnum ); + IVssEnumObject QueryProviders(); + + /// + /// Not supported. + /// This method is reserved for system use. + /// + /// None + // https://docs.microsoft.com/en-us/windows/win32/api/vsadmin/nf-vsadmin-ivssadmin-abortallsnapshotsinprogress HRESULT AbortAllSnapshotsInProgress(); + void AbortAllSnapshotsInProgress(); + } + + /// Undocumented. + [ComImport, Guid("7858A9F8-B1FA-41a6-964F-B9B36B8CD8D8"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown), CoClass(typeof(VSSCoordinator))] + public interface IVssAdminEx : IVssAdmin + { + /// The RegisterProvider method registers a new shadow copy provider. + /// + /// The VSS_ID that uniquely and persistently identifies the provider. After it is defined, the ProviderId parameter should + /// remain the same, even when the software revision is updated. A ProviderId parameter should be changed only when the + /// functionality changes enough that both providers would be active on the same system. A requester may use the ProviderId + /// parameter to request that a specific provider be used in a shadow copy creation. + /// + /// The CLSID of the provider. + /// The name of the provider. + /// + /// A VSS_PROVIDER_TYPE enumeration value that specifies the provider type. Note that VSS_PROV_HARDWARE is not a valid + /// provider type on Windows client operating system versions. Hardware providers will run only on Windows server operating system versions. + /// + /// The version of the provider. + /// + /// The VSS_ID that uniquely identifies this version of the provider. The combination of the pProviderId and + /// ProviderVersionId parameters should be unique. The ProviderVersionId parameter can be the same as the ProviderVersionId + /// parameter of another provider. + /// + /// + /// + /// If the hardware provider is updated, the setup application should call the UnregisterProvider method to unregister the outdated + /// version, and then call the RegisterProvider method to register the updated provider. + /// + /// Note Hardware providers can only be registered on Windows Server operating systems. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsadmin/nf-vsadmin-ivssadmin-registerprovider HRESULT RegisterProvider( [in] + // VSS_ID pProviderId, [in] CLSID ClassId, [in] VSS_PWSZ pwszProviderName, [in] VSS_PROVIDER_TYPE eProviderType, [in] VSS_PWSZ + // pwszProviderVersion, [in] VSS_ID ProviderVersionId ); + new void RegisterProvider(Guid pProviderId, Guid ClassId, [MarshalAs(UnmanagedType.LPWStr)] string pwszProviderName, + VSS_PROVIDER_TYPE eProviderType, [MarshalAs(UnmanagedType.LPWStr)] string pwszProviderVersion, Guid ProviderVersionId); + + /// The UnregisterProvider method unregisters an existing provider. + /// The VSS_ID of the provider. + // https://docs.microsoft.com/en-us/windows/win32/api/vsadmin/nf-vsadmin-ivssadmin-unregisterprovider HRESULT UnregisterProvider( + // [in] VSS_ID ProviderId ); + new void UnregisterProvider(Guid ProviderId); + + /// The QueryProviders method queries all registered providers. + /// The address of an IVssEnumObject interface pointer, which is initialized on return. Callers must release the interface. + /// + /// Calling the IVssEnumObject::Next method on the IVssEnumObject interface returned though the ppEnum parameter will return + /// VSS_OBJECT_PROP structures containing a VSS_PROVIDER_PROP structure for each registered provider. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsadmin/nf-vsadmin-ivssadmin-queryproviders HRESULT QueryProviders( [out] + // IVssEnumObject **ppEnum ); + new IVssEnumObject QueryProviders(); + + /// + /// Not supported. + /// This method is reserved for system use. + /// + /// None + // https://docs.microsoft.com/en-us/windows/win32/api/vsadmin/nf-vsadmin-ivssadmin-abortallsnapshotsinprogress HRESULT AbortAllSnapshotsInProgress(); + new void AbortAllSnapshotsInProgress(); + + /// Inform caller of features that provider supports + /// The provider identifier. + /// The original capability mask + VSS_PROVIDER_CAPABILITIES GetProviderCapability(Guid pProviderId); + + /// Retrieve persistent context of given provider + /// The provider identifier. + /// The context + int GetProviderContext(Guid ProviderId); + + /// + /// Set persistent context of specified provider The setting is persisted in registry by VSS It is automatically applied to the + /// snapshot context Requestors should NOT call this method + /// + /// The provider identifier. + /// The context. + void SetProviderContext(Guid ProviderId, int lContext); + } + + /// CLSID_VSSCoordinator. + [ComImport, Guid("E579AB5F-1CC4-44b4-BED9-DE0991FF0623"), ClassInterface(ClassInterfaceType.None)] + public class VSSCoordinator + { } +} \ No newline at end of file diff --git a/PInvoke/VssApi/vsbackup.cs b/PInvoke/VssApi/vsbackup.cs index 11adb263..eb3883aa 100644 --- a/PInvoke/VssApi/vsbackup.cs +++ b/PInvoke/VssApi/vsbackup.cs @@ -1,3496 +1,25 @@ using System; +using System.Collections.Generic; using System.Runtime.InteropServices; -using Vanara.Extensions; -namespace Vanara.PInvoke +namespace Vanara.PInvoke.VssApi { - public static partial class VssApi + /// Status of a writer. + public struct VssWriterStatus { + /// The address of a caller-allocated variable that receives the instance identifier of the writer. + public Guid pidInstance; + /// The address of a caller-allocated variable that receives the identifier for the writer class. + public Guid pidWriter; /// - /// - /// The IVssBackupComponents interface is used by a requester to poll writers about file status and to run backup/restore operations. - /// - /// Applications obtain an instance of the IVssBackupComponents interface by calling CreateVssBackupComponents. - /// An IVssBackupComponents object can be used for only a single backup, restore, or Query operation. - /// - /// After the backup, restore, or Query operation has either successfully finished or been explicitly terminated, a requester must - /// release the IVssBackupComponents object by calling IVssBackupComponents::Release. An IVssBackupComponents - /// object must not be reused. For example, you cannot perform a backup or restore operation with the same - /// IVssBackupComponents object that you have already used for a Query operation. - /// + /// The address of a caller-allocated variable that receives a string containing the name of the specified writer. /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nl-vsbackup-ivssbackupcomponents - [PInvokeData("vsbackup.h", MSDNShortId = "NL:vsbackup.IVssBackupComponents")] - [ComImport, Guid("665c1d5f-c218-414d-a05d-7fef5f9d5c86"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IVssBackupComponents - { - /// - /// The GetWriterComponentsCount method returns the number of writers whose components have been added to a requester's - /// Backup Components Document. - /// - /// The number of writers whose components have been stored. - /// - /// The count returned by GetWriterComponentsCount is that of writers that have had at least one of their components - /// stored in the Backup Components Document by earlier calls to IVssBackupComponents::AddComponent. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-getwritercomponentscount HRESULT - // GetWriterComponentsCount( [out] UINT *pcComponents ); - uint GetWriterComponentsCount(); - - /// - /// The GetWriterComponents method is used to return information about those components of a given writer that have been - /// stored in a requester's Backup Components Document. - /// - /// - /// The index of the writer being queried. It is a number between 0 and n-1, where n is the value returned by IVssBackupComponents::GetWriterComponentsCount. - /// - /// An IVssWriterComponentsExt interface object that will receive the returned component information. - /// - /// The caller of this method must call IUnknown::Release when it finishes accessing the component information. - /// - /// GetWriterComponents retrieves component information for a component stored in the Backup Components Document by - /// earlier calls to IVssBackupComponents::AddComponent. - /// - /// - /// The information in the components stored in the Backup Components Document is not static. If a writer updates a component - /// during a restore, that change will be reflected in the component retrieved by GetWriterComponents. This is in - /// contrast with component information found in the IVssWMComponent object returned by IVssExamineWriterMetadata::GetComponent. - /// That information is read-only and comes from the Writer Metadata Document of a writer process. - /// - /// - /// The IVssWriterComponentsExt interface pointer that is returned in the pWriterComponents parameter should not be cached, - /// because the following IVssBackupComponents methods cause the interface pointer that is returned by - /// GetWriterComponents to be no longer valid: - /// - /// - /// IVssBackupComponents::PrepareForBackup IVssBackupComponents::DoSnapshotSet IVssBackupComponents::BackupComplete - /// IVssBackupComponents::PreRestore IVssBackupComponents::PostRestore If you call one of these methods after you have retrieved - /// an IVssWriterComponentsExt interface pointer by calling GetWriterComponents, you cannot reuse that pointer, because - /// it is no longer valid. Instead, you must call GetWriterComponents again to retrieve a new - /// IVssWriterComponentsExt interface pointer. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-getwritercomponents HRESULT - // GetWriterComponents( [in] UINT iWriter, [out] IVssWriterComponentsExt **ppWriter ); - /*IVssWriterComponentsExt*/ IntPtr GetWriterComponents(uint iWriter); - - /// The InitializeForBackup method initializes the backup components metadata in preparation for backup. - /// - /// Optional. During imports of transported shadow copies, this parameter must be the original document generated when creating - /// the saved shadow copy and saved using IVssBackupComponents::SaveAsXML. - /// - /// - /// - /// The XML document supplied to this method initializes the IVssBackupComponents object with metadata previously stored by a - /// call to IVssBackupComponents::SaveAsXML. Users should not tamper with this metadata document. - /// - /// - /// For more information on how to use InitializeForBackup with transportable shadow copies, see Importing Transportable - /// Shadow Copied Volumes. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-initializeforbackup HRESULT - // InitializeForBackup( [in] BSTR bstrXML ); - void InitializeForBackup([Optional, MarshalAs(UnmanagedType.BStr)] string bstrXML); - - /// The SetBackupState method defines an overall configuration for a backup operation. - /// - /// Indicates whether a backup or restore operation will be in component mode. - /// - /// Operation in component mode supports selectively backing up designated individual components (which can allow their - /// exclusion), or only supports backing up all files and components on a volume. - /// - /// The Boolean is true if the operation will be conducted in component mode and false if not. - /// - /// Indicates whether a bootable system state backup is being performed. - /// A VSS_BACKUP_TYPE enumeration value indicating the type of backup to be performed. - /// - /// Optional. If the value of this parameter is true, partial file support is enabled. The default value for this - /// argument is false. - /// - /// Applications must call SetBackupState prior to calling IVssBackupComponents::PrepareForBackup. - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-setbackupstate HRESULT - // SetBackupState( [in] bool bSelectComponents, [in] bool bBackupBootableSystemState, [in] VSS_BACKUP_TYPE backupType, [in] bool - // bPartialFileSupport ); - void SetBackupState([MarshalAs(UnmanagedType.Bool)] bool bSelectComponents, [MarshalAs(UnmanagedType.Bool)] bool bBackupBootableSystemState, - VSS_BACKUP_TYPE backupType, [MarshalAs(UnmanagedType.Bool)] bool bPartialFileSupport = false); - - /// - /// The InitializeForRestore method initializes the IVssBackupComponents interface in preparation for a restore operation. - /// - /// - /// XML string containing the Backup Components Document generated by a backup operation and saved by IVssBackupComponents::SaveAsXML. - /// - /// - /// The XML document supplied to this method initializes the IVssBackupComponents object with metadata previously stored by a - /// call to IVssBackupComponents::SaveAsXML. Users should not tamper with this metadata document. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-initializeforrestore HRESULT - // InitializeForRestore( [in] BSTR bstrXML ); - void InitializeForRestore([MarshalAs(UnmanagedType.BStr)] string bstrXML); - - /// The SetRestoreState method defines an overall configuration for a restore operation. - /// A VSS_RESTORE_TYPE enumeration value indicating the type of restore to be performed. - /// - /// - /// Typically, most restore operations will not need to override the default restore type (VSS_RTYPE_UNDEFINED). Writers should - /// treat this restore type as if it were VSS_RTYPE_BY_COPY. - /// - /// If applications need to call SetRestoreState, it should be called prior to calling IVssBackupComponents::PreRestore. - /// - /// If SetRestoreState is not called prior to IVssBackupComponents::PreRestore, the default restore state () is used. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-setrestorestate HRESULT - // SetRestoreState( [in] VSS_RESTORE_TYPE restoreType ); - void SetRestoreState(VSS_RESTORE_TYPE restoreType); - - /// - /// The GatherWriterMetadata method prompts each writer to send the metadata they have collected. The method will - /// generate an Identify event to communicate with writers. - /// - /// An IVssAsync object containing the writer metadata. - /// - /// The caller is responsible for releasing the IVssAsync interface. - /// GatherWriterMetadata should be called only once during the lifetime of a given IVssBackupComponents object. - /// - /// GatherWriterMetadata generates an Identify event, which is handled by each instance of each writer through the - /// CVssWriter::OnIdentify method, which is used to fill the Writer Metadata Document. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-gatherwritermetadata HRESULT - // GatherWriterMetadata( [out] IVssAsync **pAsync ); - IVssAsync GatherWriterMetadata(); - - /// The GetWriterMetadataCount method returns the number of writers with metadata. - /// Number of writers with metadata. - /// - /// - /// A requester must call the asynchronous operation IVssBackupComponents::GatherWriterMetadata and wait for it to complete - /// prior to calling IVssBackupComponents::GetWriterMetadataCount. - /// - /// The number of writers returned by GetWriterMetadataCount should always be the same as that returned by IVssBackupComponents::GetWriterStatusCount. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-getwritermetadatacount HRESULT - // GetWriterMetadataCount( [out] UINT *pcWriters ); - uint GetWriterMetadataCount(); - - /// The GetWriterMetadata method returns the metadata for a specific writer running on the system. - /// - /// Index of the writer whose metadata is to be retrieved. The value of this parameter is an integer from 0 to n–1 inclusive, - /// where n is the total number of writers on the current system. The value of n is returned by IVssBackupComponents::GetWriterMetadataCount. - /// - /// Pointer to the instance identifier of the writer that collected the metadata. - /// Doubly indirect pointer to the instance of the IVssExamineWriterMetadata object that contains the returned metadata. - /// - /// - /// A requester must call the asynchronous operation IVssBackupComponents::GatherWriterMetadata and wait for it to complete - /// prior to calling GetWriterMetadata. - /// - /// - /// Although IVssBackupComponents::GatherWriterMetadata must be called prior to either a restore or backup operation, - /// GetWriterMetadata is not typically called for restores. - /// - /// - /// Component information retrieved (during backup operations) using IVssExamineWriterMetadata::GetComponent, where the - /// IVssExamineWriterMetadata interface has been returned by GetWriterMetadata, comes from the Writer Metadata Document - /// of a live writer process. - /// - /// - /// This is in contrast to the information returned by GetWriterComponents (during restore operations), which was stored in the - /// Backup Components Document by calls to AddComponent. - /// - /// When the caller of this method is finished accessing the metadata, it must call IUnknown::Release. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-getwritermetadata HRESULT - // GetWriterMetadata( [in] UINT iWriter, [out] VSS_ID *pidInstance, [out] IVssExamineWriterMetadata **ppMetadata ); - /*IVssExamineWriterMetadata*/ IntPtr GetWriterMetadata(uint iWriter, out Guid pidInstance); - - /// - /// The FreeWriterMetadata method frees system resources allocated when IVssBackupComponents::GatherWriterMetadata was called. - /// - /// - /// - /// This method should never be called prior to the completion of IVssBackupComponents::GatherWriterMetadata. The result of - /// calling the method prior to completion of the metadata gather is undefined. - /// - /// - /// Once writer metadata has been freed, it cannot be recovered by the current instance of the IVssBackupComponents interface. - /// It will be necessary to create a new instance of IVssBackupComponents, and call the - /// IVssBackupComponents::GatherWriterMetadata method again. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-freewritermetadata HRESULT FreeWriterMetadata(); - void FreeWriterMetadata(); - - /// - /// The AddComponent method is used to explicitly add to the backup set in the Backup Components Document all required - /// components (nonselectable for backup components without a selectable for backup ancestor), and such optional (selectable for - /// backup) components as the requester considers necessary. Members of component sets (components with a selectable for backup - /// ancestor) are implicitly included in the backup set, but are not explicitly added to the Backup Components Document. - /// - /// Identifies a specific instance of a writer. - /// Writer class identifier. - /// - /// Identifies the type of the component. Refer to the documentation for VSS_COMPONENT_TYPE for permitted input values. - /// - /// - /// - /// Null-terminated wide character string containing the logical path of the selectable for backup component. For more - /// information, see Logical Pathing of Components. - /// - /// A logical path is not required when adding a component. Therefore, the value of this parameter can be NULL. - /// There are no restrictions on the characters that can appear in a non- NULL logical path. - /// - /// - /// Null-terminated wide character string containing the name of the selectable for backup component. - /// The value of this parameter cannot be NULL. - /// There are no restrictions on the characters that can appear in a non- NULL logical path. - /// - /// - /// The AddComponent method has meaning only if the backup operation takes place in component mode. - /// Only these kinds of components should be added to the Backup Components Document using AddComponent. - /// - /// - /// Components that are selectable for backup (see selectability for backup). - /// - /// - /// Nonselectable-for-backup components with no selectable-for-backup ancestors. - /// - /// - /// - /// Nonselectable for backup components that have a selectable for backup ancestor in the hierarchy of their logical paths are - /// part of a component set defined by the selectable for backup ancestor. These components are implicitly added to the Backup - /// Components Document when the ancestor is added and should never be explicitly added to a requester's Backup Components - /// Document by using AddComponent.The result of doing so is undefined (see Working with Selectability and Logical Paths). - /// - /// - /// Selectable for backup components with selectable for backup ancestors are also subcomponents in a component set. They can be - /// implicitly selected if their ancestor is selected (in which case they are not added to the Backup Components Document using - /// AddComponent), or they can be explicitly selected using AddComponent. - /// - /// - /// The combination of logical path and name for each component of a given instance of a given class of writer must be unique. - /// Attempting to call AddComponent twice with the same values of wszLogicalPath and wszComponentName results in a - /// VSS_E_OBJECT_ALREADY_EXISTS error. - /// - /// - /// The distinction between the instanceId and the writerID is necessary because it is possible to run multiple copies for the - /// same writer. - /// - /// A writer's class identifier and instance can be found by calling IVssExamineWriterMetadata::GetIdentity. - /// - /// Before it calls AddComponent, a requester must have been initialized for backup by calling - /// IVssBackupComponents::InitializeForBackup and IVssBackupComponents::GatherWriterMetadata. See Overview of Backup Initialization. - /// - /// - /// The requester must call AddComponent to add the required components to the shadow copy before calling - /// IVssBackupComponents::DoSnapshotSet to create the shadow copy. See Overview of the Backup Discovery Phase and Overview of - /// Pre-Backup Tasks. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-addcomponent HRESULT - // AddComponent( [in] VSS_ID instanceId, [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] - // LPCWSTR wszComponentName ); - void AddComponent(Guid instanceId, Guid writerId, VSS_COMPONENT_TYPE ct, - [Optional, MarshalAs(UnmanagedType.LPWStr)] string wszLogicalPath, [MarshalAs(UnmanagedType.LPWStr)] string wszComponentName); - - /// - /// The PrepareForBackup method will cause VSS to generate a PrepareForBackup event, signaling writers to prepare for an - /// upcoming backup operation. This makes a requester's Backup Components Document available to writers. - /// - /// - /// Doubly indirect pointer to an instance of the IVssAsync interface that is used to determine when the asynchronous operation - /// is complete. - /// - /// - /// - /// PrepareForBackup generates a PrepareForBackup event, which is handled by each instance of each writer through the - /// CVssWriter::OnPrepareBackup method. - /// - /// Before PrepareForBackup can be called, IVssBackupComponents::SetBackupState must be called. - /// - /// The Backup Components Document can still be modified by writers in their PrepareForBackup event handler - /// (CVssWriter::OnPrepareBackup), and afterward until the generation of a BackupComplete event. - /// - /// The caller is responsible for releasing the IVssAsync interface. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-prepareforbackup HRESULT - // PrepareForBackup( [out] IVssAsync **ppAsync ); - IVssAsync PrepareForBackup(); - - /// - /// The AbortBackup method notifies VSS that a backup operation was terminated. - /// - /// This method must be called if a backup operation terminates after the creation of a shadow copy set with - /// IVssBackupComponents::StartSnapshotSet and before IVssBackupComponents::DoSnapshotSet returns. - /// - /// If AbortBackup is called and no shadow copy or backup operations are underway, it is ignored. - /// - /// - /// AbortBackup generates an Abort event, which is handled by each instance of each writer through the - /// CVssWriter::OnAbort method. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-abortbackup HRESULT AbortBackup(); - void AbortBackup(); - - /// The GatherWriterStatus method prompts each writer to send a status message. - /// Doubly indirect pointer to an IVssAsync object containing the writer status data. - /// - /// - /// The caller of this method should also call IVssBackupComponents::FreeWriterStatus after receiving the status of each writer. - /// - /// - /// After calling BackupComplete, requesters must call GatherWriterStatus to cause the writer session to be set to a - /// completed state. - /// - /// Note This is only necessary on Windows Server 2008 with Service Pack 2 (SP2) and earlier. - /// The CVssWriter class handles the status message sent by each writer. - /// The caller is responsible for releasing the IVssAsync interface. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-gatherwriterstatus HRESULT - // GatherWriterStatus( [out] IVssAsync **pAsync ); - IVssAsync GatherWriterStatus(); - - /// The GetWriterStatusCount method returns the number of writers with status. - /// The number of writers with status. - /// - /// - /// A requester must call the asynchronous operation IVssBackupComponents::GatherWriterStatus and wait for it to complete prior - /// to calling IVssBackupComponents::GetWriterStatusCount. - /// - /// The number of writers returned by GetWriterStatusCount should always be the same as that returned by IVssBackupComponents::GetWriterMetadataCount. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-getwriterstatuscount HRESULT - // GetWriterStatusCount( [out] UINT *pcWriters ); - uint GetWriterStatusCount(); - - /// The FreeWriterStatus method frees system resources allocated during the call to IVssBackupComponents::GatherWriterStatus. - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-freewriterstatus HRESULT FreeWriterStatus(); - void FreeWriterStatus(); - - /// The GetWriterStatus method returns the status of the specified writer. - /// - /// Index of the writer whose metadata is to be retrieved. The value of this parameter is an integer from 0 to n–1 inclusive, - /// where n is the total number of writers on the current system. The value of n is returned by IVssBackupComponents::GetWriterStatusCount. - /// - /// The address of a caller-allocated variable that receives the instance identifier of the writer. - /// The address of a caller-allocated variable that receives the identifier for the writer class. - /// - /// The address of a caller-allocated variable that receives a string containing the name of the specified writer. - /// - /// The address of a caller-allocated variable that receives a VSS_WRITER_STATE enumeration value. - /// - /// The address of a caller-allocated variable that receives the HRESULT failure code that was returned by the writer. - /// The following are the supported values for pHrResultFailure. - /// - /// - /// Value - /// Meaning - /// - /// - /// S_OK - /// The writer was successful. - /// - /// - /// VSS_E_WRITERERROR_INCONSISTENTSNAPSHOT - /// The shadow copy contains only a subset of the volumes needed by the writer to correctly back up the application component. - /// - /// - /// VSS_E_WRITERERROR_OUTOFRESOURCES - /// - /// The writer ran out of memory or other system resources. The recommended way to handle this error code is to wait ten minutes - /// and then repeat the operation, up to three times. - /// - /// - /// - /// VSS_E_WRITERERROR_TIMEOUT - /// - /// The writer operation failed because of a time-out between the Freeze and Thaw events. The recommended way to handle this - /// error code is to wait ten minutes and then repeat the operation, up to three times. - /// - /// - /// - /// VSS_E_WRITERERROR_RETRYABLE - /// - /// The writer failed due to an error that would likely not occur if the entire backup, restore, or shadow copy creation process - /// was restarted. The recommended way to handle this error code is to wait ten minutes and then repeat the operation, up to - /// three times. - /// - /// - /// - /// VSS_E_WRITERERROR_NONRETRYABLE - /// - /// The writer operation failed because of an error that might recur if another shadow copy is created. For more information, - /// see Event and Error Handling Under VSS. - /// - /// - /// - /// VSS_E_WRITER_NOT_RESPONDING - /// The writer is not responding. - /// - /// - /// VSS_E_WRITER_STATUS_NOT_AVAILABLE - /// - /// The writer status is not available for one or more writers. A writer may have reached the maximum number of available backup - /// and restore sessions. Windows Vista, Windows Server 2003 and Windows XP: This value is not supported. - /// - /// - /// - /// - /// - /// - /// A requester must call the asynchronous operation IVssBackupComponents::GatherWriterStatus and wait for it to complete prior - /// to calling GetWriterStatus. - /// - /// - /// When the caller has finished accessing the status information returned by this method, it should call SysFreeString to free - /// the memory held by the pbstrWriter parameter. - /// - /// - /// The VSS_E_WRITERERROR_XXX values returned in the pHrResultFailure parameter are generated by writers. - /// VSS_E_WRITER_NOT_RESPONDING and VSS_E_WRITER_STATUS_NOT_AVAILABLE are generated by VSS. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-getwriterstatus HRESULT - // GetWriterStatus( [in] UINT iWriter, [out] VSS_ID *pidInstance, [out] VSS_ID *pidWriter, [out] BSTR *pbstrWriter, [out] - // VSS_WRITER_STATE *pnStatus, [out] HRESULT *phResultFailure ); - void GetWriterStatus(uint iWriter, out Guid pidInstance, out Guid pidWriter, [MarshalAs(UnmanagedType.BStr)] out string pbstrWriter, - out VSS_WRITER_STATE pnStatus, out HRESULT phResultFailure); - - /// - /// The SetBackupSucceeded method indicates whether the backup of the specified component of a specific writer was successful. - /// - /// Globally unique identifier (GUID) of the writer instance. - /// Globally unique identifier (GUID) of the writer class. - /// Type of the component. See VSS_COMPONENT_TYPE for the possible values. - /// - /// Null-terminated wide character string containing the logical path of the component. - /// 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. - /// - /// - /// Null-terminated wide character string containing the name of the component. - /// - /// The string cannot be NULL and should contain the same component name as was used when the component was added to the - /// backup set using IVssBackupComponents::AddComponent. - /// - /// - /// - /// Set this parameter to true if the component was successfully backed up, or false otherwise. - /// - /// - /// - /// When working in component mode (when IVssBackupComponents::SetBackupState is called with its select components argument set - /// to true), writers check the state of each components backup using IVssComponent::GetBackupSucceeded. Therefore, a - /// well-behaved backup application (requester) must call SetBackupSucceeded after each component has been processed and - /// prior to calling IVssBackupComponents::BackupComplete. - /// - /// - /// Do not call this method if the call to IVssBackupComponents::DoSnapshotSet failed. For more information about how requesters - /// use DoSnapshotSet, SetBackupSucceeded, and BackupComplete in a backup operation, see Overview of Pre-Backup - /// Tasks and Overview of Actual Backup Of Files. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-setbackupsucceeded HRESULT - // SetBackupSucceeded( [in] VSS_ID instanceId, [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, - // [in] LPCWSTR wszComponentName, [in] bool bSucceded ); - void SetBackupSucceeded(Guid instanceId, Guid writerId, VSS_COMPONENT_TYPE ct, [Optional, MarshalAs(UnmanagedType.LPWStr)] string wszLogicalPath, - [MarshalAs(UnmanagedType.LPWStr)] string wszComponentName, [MarshalAs(UnmanagedType.Bool)] bool bSucceded); - - /// The SetBackupOptions method sets a string of private, or writer-dependent, backup parameters for a component. - /// Writer identifier. - /// Type of the component. See VSS_COMPONENT_TYPE for the possible values. - /// - /// Null-terminated wide character string containing the logical path of the component. - /// 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. - /// - /// - /// Null-terminated wide character string containing the name of the component. - /// - /// The string containing the name cannot be NULL and should contain the same component name as was used when the - /// component was added to the backup set using IVssBackupComponents::AddComponent. - /// - /// - /// Null-terminated wide character string containing the backup parameters to be set. - /// - /// The following are the valid return codes for this method. - /// - /// - /// Value - /// Meaning - /// - /// - /// S_OK - /// Successfully set the backup options. - /// - /// - /// 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, this method has been called during a restore operation, or this method has - /// not been called within the correct sequence. - /// - /// - /// - /// VSS_E_OBJECT_NOT_FOUND - /// The backup component does not exist. - /// - /// - /// 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_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. - /// - /// - /// - /// - /// - /// - /// The exact syntax and content of the backup options set by the wszBackupOptions parameter of the SetBackupOptions - /// method will depend on the specific writer being contacted. - /// - /// This method must be called before IVssBackupComponents::PrepareForBackup. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-setbackupoptions HRESULT - // SetBackupOptions( [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] LPCWSTR - // wszComponentName, [in] LPCWSTR wszBackupOptions ); - void SetBackupOptions(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional, MarshalAs(UnmanagedType.LPWStr)] string wszLogicalPath, - [MarshalAs(UnmanagedType.LPWStr)] string wszComponentName, [MarshalAs(UnmanagedType.LPWStr)] string wszBackupOptions); - - /// - /// The SetSelectedForRestore method indicates whether the specified selectable component is selected for restoration. - /// - /// Writer identifier. - /// Type of the component. See VSS_COMPONENT_TYPE for the possible values. - /// - /// - /// Null-terminated wide character string containing the logical path of the component. 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. - /// - /// The logical path can be NULL. - /// There are no restrictions on the characters that can appear in a non- NULL logical path. - /// - /// - /// Null-terminated wide character string containing the name of the component. - /// - /// The string cannot be NULL and should contain the same component name as was used when the component was added to the - /// backup set using IVssBackupComponents::AddComponent. - /// - /// - /// - /// If the value of this parameter is true, the selected component has been selected for restoration. If the value is - /// false, the selected component has not been selected for restoration. - /// - /// - /// SetSelectedForRestore has meaning only for restores taking place in component mode. - /// - /// SetSelectedForRestore can only be called for components that were explicitly added to the backup document at backup - /// time using IVssBackupComponents::AddComponent. Restoring a component that was implicitly selected for backup as part of a - /// component set must be done by calling SetSelectedForRestore on the closest ancestor component that was added to the - /// document. If only this component's data is to be restored, that should be accomplished through - /// IVssBackupComponents::AddRestoreSubcomponent; this can only be done if the component is selectable for restore (see Working - /// with Selectability and Logical Paths). - /// - /// This method must be called before IVssBackupComponents::PreRestore. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-setselectedforrestore HRESULT - // SetSelectedForRestore( [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] LPCWSTR - // wszComponentName, [in] bool bSelectedForRestore ); - void SetSelectedForRestore(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional, MarshalAs(UnmanagedType.LPWStr)] string wszLogicalPath, - [MarshalAs(UnmanagedType.LPWStr)] string wszComponentName, [MarshalAs(UnmanagedType.Bool)] bool bSelectedForRestore); - - /// - /// The SetRestoreOptions method sets a string of private, or writer-dependent, restore parameters for a writer component. - /// - /// Writer identifier. - /// Type of the component. See VSS_COMPONENT_TYPE for the possible values. - /// - /// - /// Null-terminated wide character string containing the logical path of the component. 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. - /// - /// - /// Null-terminated wide character string containing the name of the component. - /// - /// The string cannot be NULL and should contain the same component name as was used when the component was added to the - /// backup set using IVssBackupComponents::AddComponent. - /// - /// - /// - /// Null-terminated wide character string containing the private string of restore parameters. For more information see Setting - /// VSS Restore Options. - /// - /// - /// This method must be called before IVssBackupComponents::PreRestore. - /// - /// The exact syntax and content of the restore options set by the wszRestoreOptions parameter of the SetRestoreOptions - /// method will depend on the specific writer being contacted. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-setrestoreoptions HRESULT - // SetRestoreOptions( [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] LPCWSTR - // wszComponentName, [in] LPCWSTR wszRestoreOptions ); - void SetRestoreOptions(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional, MarshalAs(UnmanagedType.LPWStr)] string wszLogicalPath, - [MarshalAs(UnmanagedType.LPWStr)] string wszComponentName, [MarshalAs(UnmanagedType.LPWStr)] string wszRestoreOptions); - - /// - /// The SetAdditionalRestores method is used by a requester during incremental or differential restore operations to - /// indicate to writers that a given component will require additional restore operations to completely retrieve it. - /// - /// Writer identifier. - /// Type of the component. See VSS_COMPONENT_TYPE for the possible values. - /// - /// Null-terminated wide character string containing the logical path of the component to be added. - /// 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. - /// - /// - /// Null-terminated wide character string containing the name of the component. - /// - /// The value of the string should not be NULL, and should contain the same component as was used when the component was - /// added to the backup set using IVssBackupComponents::AddComponent. - /// - /// - /// - /// If the value of this parameter is true, additional restores of the component will follow this restore. If the value - /// is false, additional restores of the component will not follow this restore. - /// - /// - /// - /// The information provided by the SetAdditionalRestores method is typically used by writers that support an explicit - /// recovery mechanism as part of their PostRestore event handler (CVssWriter::OnPostRestore)—for instance, the Exchange Server, - /// and database applications such as SQL Server. For these applications, it is often not possible to perform additional - /// differential, incremental, or log restores after such a recovery is performed. - /// - /// - /// Therefore, if SetAdditionalRestores for a component is set to true, this means that such a writer should not - /// execute its explicit recovery mechanism and should expect that additional differential, incremental, or log restores will be done. - /// - /// - /// When SetAdditionalRestores on a component is set to false, then after the component is restored, the - /// application can complete its recovery operation and be brought back online. - /// - /// This method must be called before IVssBackupComponents::PreRestore. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-setadditionalrestores HRESULT - // SetAdditionalRestores( [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] LPCWSTR - // wszComponentName, [in] bool bAdditionalRestores ); - void SetAdditionalRestores(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional, MarshalAs(UnmanagedType.LPWStr)] string wszLogicalPath, - [MarshalAs(UnmanagedType.LPWStr)] string wszComponentName, [MarshalAs(UnmanagedType.Bool)] bool bAdditionalRestores); - - /// - /// - /// The SetPreviousBackupStamp method sets the backup stamp of an earlier backup operation, upon which a differential or - /// incremental backup operation will be based. - /// - /// The method can be called only during a backup operation. - /// - /// Writer identifier. - /// Type of the component. See VSS_COMPONENT_TYPE for the possible values. - /// - /// Null-terminated wide character string containing the logical path of the component. - /// 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. - /// - /// - /// Null-terminated wide character string containing the name of the component. - /// - /// The string cannot be NULL and should contain the same component name as was used when the component was added to the - /// backup set using IVssBackupComponents::AddComponent. - /// - /// - /// The backup stamp to be set. - /// - /// This method should be called before IVssBackupComponents::PrepareForBackup. - /// Only requesters can call this method. - /// - /// The backup stamp set by SetPreviousBackupStamp applies to all files in the component and any nonselectable - /// subcomponents it has. - /// - /// - /// Requesters merely store the backup stamps in the Backup Components Document. They cannot make direct use of the backup - /// stamps, do not know their format, and do not know how to generate them. - /// - /// - /// Therefore, the value set with SetPreviousBackupStamp should either be retrieved from the stored Backup Components - /// Document of an earlier backup operation (using IVssComponent::GetBackupStamp for the correct component), or from information - /// stored by the requester into its own internal records. - /// - /// - /// A writer will then obtain this value (using IVssComponent::GetPreviousBackupStamp) and using it will be able to mark the - /// appropriate files for participation in an incremental or differential backup. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-setpreviousbackupstamp HRESULT - // SetPreviousBackupStamp( [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] LPCWSTR - // wszComponentName, [in] LPCWSTR wszPreviousBackupStamp ); - void SetPreviousBackupStamp(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional, MarshalAs(UnmanagedType.LPWStr)] string wszLogicalPath, - [MarshalAs(UnmanagedType.LPWStr)] string wszComponentName, [MarshalAs(UnmanagedType.LPWStr)] string wszPreviousBackupStamp); - - /// - /// The SaveAsXML method saves the Backup Components Document containing a requester's state information to a specified - /// string. This XML document, which contains the Backup Components Document, should always be securely saved as part of a - /// backup operation. - /// - /// Pointer to a string to be used to store the Backup Components Document containing a requester's state information. - /// - /// - /// For a typical backup operation, SaveAsXML should not be called until after both writers and the requester are - /// finished modifying the Backup Components Document. - /// - /// - /// Writers can continue to modify the Backup Components Document until their successful return from handling the PostSnapshot - /// event (CVssWriter::OnPostSnapshot), or equivalently upon the completion of IVssBackupComponents::DoSnapshotSet. - /// - /// - /// Requesters will need to continue to modify the Backup Components Document as the backup progresses. In particular, a - /// requester will store a component-by-component record of the success or failure of the backup through calls to the - /// IVssBackupComponents::SetBackupSucceeded method. - /// - /// - /// Once the requester has finished modifying the Backup Components Document, the requester should use SaveAsXML to save - /// a copy of the document to the backup media. - /// - /// - /// A Backup Components Document can be saved at earlier points in the life cycle of a backup operation—for instance, to support - /// the generation of transportable shadow copies to be handled on remote machines. (See Importing Transportable Shadow Copied - /// Volumes for more information.) - /// - /// - /// However, SaveAsXML should never be called prior to IVssBackupComponents::PrepareForBackup, because the Backup - /// Components Document will not have been filled by the requester and the writers. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-saveasxml HRESULT SaveAsXML( - // [in] BSTR *pbstrXML ); - [return: MarshalAs(UnmanagedType.BStr)] - string SaveAsXML(); - - /// - /// The BackupComplete method causes VSS to generate a BackupComplete event, which signals writers that the backup - /// process has completed. - /// - /// Doubly indirect pointer to an IVssAsync instance. - /// - /// - /// When working in component mode (IVssBackupComponents::SetBackupState was called with a select components argument of - /// TRUE), writers can determine the success or failure of the backup of any component explicitly included in the Backup - /// Components Document components by using IVssComponent::GetBackupSucceeded. Therefore, a well-behaved backup application - /// (requester) must call IVssBackupComponents::SetBackupSucceeded after each component has been processed and prior to calling BackupComplete. - /// - /// - /// Do not call this method if the call to IVssBackupComponents::DoSnapshotSet failed. For more information about how requesters - /// use DoSnapshotSet, SetBackupSucceeded, and BackupComplete in a backup operation, see Overview of Pre-Backup - /// Tasks and Overview of Actual Backup Of Files. - /// - /// - /// This operation is asynchronous. The caller can use the QueryStatus interface method in the returned IVssAsync interface to - /// determine the status of the notification. - /// - /// - /// After calling BackupComplete, requesters must call GatherWriterStatus to cause the writer session to be set to a - /// completed state. - /// - /// Note This is only necessary on Windows Server 2008 with Service Pack 2 (SP2) and earlier. - /// The backup application can choose to abort the backup at any time after the shadow copy is created by calling IVssAsync::Cancel. - /// - /// The calling application is responsible for calling IUnknown::Release to release the resources held by the returned IVssAsync - /// when it is no longer needed. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-backupcomplete HRESULT - // BackupComplete( [out] IVssAsync **ppAsync ); - IVssAsync BackupComplete(); - - /// - /// The AddAlternativeLocationMapping method is used by a requester to indicate that an alternate location mapping was - /// used to restore all the members of a file set in a given component. - /// - /// Globally unique identifier (GUID) of the writer class that exported the component. - /// - /// Type of the component. The possible values of this parameter are defined by the VSS_COMPONENT_TYPE enumeration. - /// - /// - /// Null-terminated wide character string containing the logical path to the component. - /// For more information, see Logical Pathing of Components. - /// The logical path can be NULL. - /// There are no restrictions on the characters that can appear in a non- NULL logical path. - /// - /// - /// Null-terminated wide character string containing the component name. - /// There are no restrictions on the characters that can appear in a non- NULL logical path. - /// - /// - /// - /// Null-terminated wide character string containing the path to the directory that originally contained the file to be - /// relocated. This path can be local to 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. - /// - /// - /// - /// Null-terminated wide character string containing the original file specification. - /// - /// A file specification cannot contain directory specifications (for example, no backslashes) but can contain the ? and * - /// wildcard characters. - /// - /// - /// - /// - /// A Boolean value that indicates whether the path specified by the wszPath parameter identifies only a single directory or if - /// it indicates a hierarchy of directories to be traversed recursively. This parameter should be set to true if the path - /// is treated as a hierarchy of directories to be traversed recursively, or false if not. - /// - /// For information on traversing mounted folders, see Working with Mounted Folders and Reparse Points. - /// - /// - /// Null-terminated wide character string containing the name of the directory where the file will be relocated. This - /// path can be local to the VSS machine, or it can be a file share directory on a remote file server. UNC paths are supported. - /// - /// - /// - /// 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 writerId, componentType, wszLogicalPath, and wszComponentName parameters identify a particular component, and the - /// wszPath, wszFilespec, and bRecursive parameters identify the file set belonging to that component. - /// - /// - /// The combination of path, file specification, and recursion flag (wszPath, wszFilespec, and bRecursive, respectively) - /// provided to AddAlternativeLocationMapping to be mapped must match that of one of the file sets added to a component - /// using either IVssCreateWriterMetadata::AddFilesToFileGroup, IVssCreateWriterMetadata::AddDatabaseFiles, or IVssCreateWriterMetadata::AddDatabaseLogFiles. - /// - /// - /// Because AddAlternativeLocationMapping is used to notify a writer that an alternate location was used to restore all - /// the files in a component, it should not be called for any component or files in a component that have not had an alternate - /// location mapping specified. - /// - /// - /// The value of wszPath will have been mapped to wszDestination on restore; however, file names and subdirectories under the - /// original path retain their same names. - /// - /// A typical usage of AddAlternativeLocationMapping during restore might be the following: - /// - /// - /// Retrieve stored Writer Metadata Documents from the backup media and load that information with IVssExamineWriterMetadata::LoadFromXML. - /// - /// - /// - /// Call IVssExamineWriterMetadata::GetAlternateLocationMapping to get an IVssWMFiledesc interface with the mapping information - /// and use IVssWMFiledesc::GetAlternateLocation to get the alternate location. - /// - /// - /// - /// - /// Examine filedesc information to heuristically determine which component this alternate location mapping should be applied to. - /// - /// - /// - /// Call IVssBackupComponents::AddAlternativeLocationMapping to communicate where files were restored. - /// - /// - /// A file should always be restored to its alternate location mapping if either of the following is true: - /// - /// - /// The restore method (set at backup time) is VSS_RME_RESTORE_TO_ALTERNATE_LOCATION. - /// - /// - /// Its restore target was set (at restore time) to VSS_RT_ALTERNATE. - /// - /// - /// In either case, if no valid alternate location mapping is defined this constitutes a writer error. - /// A file may be restored to an alternate location mapping if either of the following is true: - /// - /// - /// The restore method is VSS_RME_RESTORE_IF_NOT_THERE and a version of the file is already present on disk. - /// - /// - /// The restore method is VSS_RME_RESTORE_IF_CAN_REPLACE and a version of the file is present on disk and cannot be replaced. - /// - /// - /// Again, if no valid alternate location mapping is defined this constitutes a writer error. - /// - /// An alternate location mapping is used only during a restore operation and should not be confused with an alternate path, - /// which is used only during a backup operation. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-addalternativelocationmapping - // HRESULT AddAlternativeLocationMapping( [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE componentType, [in] LPCWSTR - // wszLogicalPath, [in] LPCWSTR wszComponentName, [in] LPCWSTR wszPath, [in] LPCWSTR wszFilespec, [in] bool bRecursive, [in] - // LPCWSTR wszDestination ); - void AddAlternativeLocationMapping(Guid writerId, VSS_COMPONENT_TYPE componentType, - [Optional, MarshalAs(UnmanagedType.LPWStr)] string wszLogicalPath, - [MarshalAs(UnmanagedType.LPWStr)] string wszComponentName, [MarshalAs(UnmanagedType.LPWStr)] string wszPath, - [MarshalAs(UnmanagedType.LPWStr)] string wszFilespec, [MarshalAs(UnmanagedType.Bool)] bool bRecursive, - [MarshalAs(UnmanagedType.LPWStr)] string wszDestination); - - /// - /// The AddRestoreSubcomponent method indicates that a subcomponent member of a component set, which had been marked as - /// nonselectable for backup but is marked selectable for restore, is to be restored irrespective of whether any other member of - /// the component set will be restored. - /// - /// Writer class identifier. - /// - /// Identifies the type of the component. Refer to the documentation for VSS_COMPONENT_TYPE for possible return values. - /// - /// - /// - /// Null-terminated wide character string containing the logical path of the component in the backup document that - /// defines the backup component set containing the subcomponent to be added for restore. - /// - /// The value of this parameter can be NULL. - /// There are no restrictions on the characters that can appear in a non- NULL logical path. - /// - /// - /// - /// Null-terminated wide character string containing the logical path of the component in the backup document that - /// defines the backup component set containing the subcomponent to be added for restore. - /// - /// The value of this parameter cannot be NULL. - /// There are no restrictions on the characters that can appear in a non- NULL component name. - /// - /// - /// Null-terminated wide character string containing the logical path of the subcomponent to be added for restore. - /// A logical path is required when adding a subcomponent. Therefore, the value of this parameter cannot be NULL. - /// There are no restrictions on the characters that can appear in a non- NULL logical path. - /// - /// - /// Null-terminated wide character string containing the logical name of the subcomponent to be added for restore. - /// The value of this parameter cannot be NULL. - /// There are no restrictions on the characters that can appear in a non- NULL component name. - /// - /// This parameter is reserved for future use. This parameter should always be set to false - /// - /// - /// Before calling AddRestoreSubcomponent, the root component defined by the wszLogicalPath and wszComponentName - /// parameters must first be selected for restore using IVssBackupComponents::SetSelectedForRestore. - /// - /// If a requester is to support restoring subcomponents, this method must be called before IVssBackupComponents::PreRestore. - /// - /// AddRestoreSubcomponent is intended for the case in which all the files in a writer's component set must be backed up - /// as a unit, but where it is desirable that selected files (subcomponents) be capable of being restored individually. - /// - /// - /// To participate in such a restore, a subcomponent must have the bSelectableForRestore member of VSS_COMPONENTINFO set - /// to TRUE. The component defined by the wszLogicalPath and wszComponentName parameters must also be selected for - /// restore using IVssBackupComponents::SetSelectedForRestore. - /// - /// See Working with Selectability for Restore and Subcomponents for more information. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-addrestoresubcomponent HRESULT - // AddRestoreSubcomponent( [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE componentType, [in] LPCWSTR wszLogicalPath, [in] - // LPCWSTR wszComponentName, [in] LPCWSTR wszSubComponentLogicalPath, [in] LPCWSTR wszSubComponentName, [in] bool bRepair ); - void AddRestoreSubcomponent(Guid writerId, VSS_COMPONENT_TYPE componentType, - [Optional, MarshalAs(UnmanagedType.LPWStr)] string wszLogicalPath, - [MarshalAs(UnmanagedType.LPWStr)] string wszComponentName, - [MarshalAs(UnmanagedType.LPWStr)] string wszSubComponentLogicalPath, - [MarshalAs(UnmanagedType.LPWStr)] string wszSubComponentName, [MarshalAs(UnmanagedType.Bool)] bool bRepair); - - /// The SetFileRestoreStatus method indicates whether some, all, or no files were successfully restored. - /// Writer identifier. - /// Type of the component. See VSS_COMPONENT_TYPE for the possible values. - /// - /// Null-terminated wide character string containing the logical path of the component. - /// 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. - /// - /// - /// Null-terminated wide character string containing the name of the component. - /// - /// The string cannot be NULL and should contain the same component name as was used when the component was added to the - /// backup set using IVssBackupComponents::AddComponent. - /// - /// - /// - /// If all of the files were restored, the value of this parameter is VSS_RS_ALL. If some of the files were restored, the value - /// of this parameter is VSS_RS_FAILED. If none of the files were restored, the value of this parameter is VSS_RS_NONE. - /// - /// This method should be called between calls to IVssBackupComponents::PreRestore and IVssBackupComponents::PostRestore. - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-setfilerestorestatus HRESULT - // SetFileRestoreStatus( [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] LPCWSTR - // wszComponentName, [in] VSS_FILE_RESTORE_STATUS status ); - void SetFileRestoreStatus(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional, MarshalAs(UnmanagedType.LPWStr)] string wszLogicalPath, - [MarshalAs(UnmanagedType.LPWStr)] string wszComponentName, VSS_FILE_RESTORE_STATUS status); - - /// - /// 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. - /// - /// - /// Globally unique identifier (GUID) of the writer class containing the files that are to receive a new target. - /// - /// - /// Identifies the type of the component. Refer to the documentation for VSS_COMPONENT_TYPE for possible return values. - /// - /// - /// - /// 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. - /// - /// - /// - /// 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. - /// - /// - /// - /// 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. - /// - /// - /// - /// - /// 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. - /// - /// - /// - /// - /// 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. - /// - /// - /// 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. - /// - /// - /// - /// 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. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-addnewtarget 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 ); - void AddNewTarget(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional, MarshalAs(UnmanagedType.LPWStr)] string wszLogicalPath, - [MarshalAs(UnmanagedType.LPWStr)] string wszComponentName, [MarshalAs(UnmanagedType.LPWStr)] string wszPath, - [MarshalAs(UnmanagedType.LPWStr)] string wszFileName, [MarshalAs(UnmanagedType.Bool)] bool bRecursive, - [MarshalAs(UnmanagedType.LPWStr)] string wszAlternatePath); - - /// - /// The SetRangesFilePath method is used when a partial file operation requires a ranges file, and that file has been - /// restored to a location other than its original one. - /// - /// - /// Globally unique identifier (GUID) of the writer class containing the files involved in the partial file operation. - /// - /// Identifies the type of the component. Refer to VSS_COMPONENT_TYPE for possible return values. - /// - /// - /// Null-terminated wide character string containing the logical path of the component containing the files that are - /// participating in the partial file operation. - /// - /// 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. - /// - /// - /// - /// Null-terminated wide character string containing the name of the component containing the files that are - /// participating in the partial file operation. - /// - /// - /// The string cannot be NULL and should contain the same component name as was used when the component was added to the - /// backup set using IVssBackupComponents::AddComponent. - /// - /// - /// - /// Index number of the partial file. The value of this parameter is an integer from 0 to n–1 inclusive, where n is the total - /// number of partial files associated with a given component. The value of n is returned by IVssComponent::GetPartialFileCount. - /// - /// - /// Null-terminated wide character string containing the fully qualified path of a ranges file. - /// - /// Calling SetRangesFilePath is not necessary if ranges files are restored in place. - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-setrangesfilepath HRESULT - // SetRangesFilePath( VSS_ID writerId, VSS_COMPONENT_TYPE ct, LPCWSTR wszLogicalPath, LPCWSTR wszComponentName, UINT - // iPartialFile, LPCWSTR wszRangesFile ); - void SetRangesFilePath(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional, MarshalAs(UnmanagedType.LPWStr)] string wszLogicalPath, - [MarshalAs(UnmanagedType.LPWStr)] string wszComponentName, uint iPartialFile, - [MarshalAs(UnmanagedType.LPWStr)] string wszRangesFile); - - /// - /// The PreRestore method will cause VSS to generate a PreRestore event, signaling writers to prepare for an upcoming - /// restore operation. - /// - /// Doubly indirect pointer to an IVssAsync object containing status data for the signaled event. - /// - /// The caller is responsible for releasing the IVssAsync interface pointer. - /// - /// Special consideration should be given to EFI systems when the requester has selected the Automated System Recovery (ASR) - /// writer for restore. If you are restoring to a disk that contains the EFI partition, and one of the following conditions - /// exists, you must first clean the disk by calling the IVdsAdvancedDisk::Clean method: - /// - /// - /// - /// You are restoring to an EFI system disk whose partitioning has changed since the last ASR backup. - /// - /// - /// You are restoring to a different physical drive than the one from which the backup was taken. - /// - /// - /// Failure to perform this disk-cleaning step may result in unexpected results during PreRestore. - /// For more information about the ASR writer, see In-Box VSS Writers. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-prerestore HRESULT PreRestore( - // [out] IVssAsync **ppAsync ); - IVssAsync PreRestore(); - - /// - /// The PostRestore method will cause VSS to generate a PostRestore event, signaling writers that the current - /// restore operation has finished. - /// - /// Doubly indirect pointer to an IVssAsync object that contains status data for the signaled event. - /// The caller is responsible for releasing the IVssAsync interface. - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-postrestore HRESULT PostRestore( - // [out] IVssAsync **ppAsync ); - IVssAsync PostRestore(); - - /// The SetContext method sets the context for subsequent shadow copy-related operations. - /// - /// The context to be set. The context must be one of the supported values of _VSS_SNAPSHOT_CONTEXT or a supported bit mask (or - /// bitwise OR) of _VSS_VOLUME_SNAPSHOT_ATTRIBUTES with a valid _VSS_SNAPSHOT_CONTEXT. - /// - /// - /// The default context for VSS shadow copies is VSS_CTX_BACKUP. - /// - /// Windows XP: The only supported context is the default context, VSS_CTX_BACKUP. Therefore, calling SetContext - /// under Windows XP returns E_NOTIMPL. - /// - /// SetContext can be called only once, and it must be called prior to calling most VSS functions. - /// - /// For details on how the context set by IVssBackupComponents::SetContext affects how a shadow copy is created and - /// managed, see Implementation Details for Creating Shadow Copies. - /// - /// For a complete discussion of the permitted shadow copy contexts, see _VSS_SNAPSHOT_CONTEXT and _VSS_VOLUME_SNAPSHOT_ATTRIBUTES. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-setcontext HRESULT SetContext( - // [in] LONG lContext ); - void SetContext(int lContext); - - /// The StartSnapshotSet method creates a new, empty shadow copy set. - /// The address of a caller-allocated variable that receives the shadow copy set identifier. - /// This method must be called before IVssBackupComponents::PrepareForBackup during backup operations. - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-startsnapshotset HRESULT - // StartSnapshotSet( [out] VSS_ID *pSnapshotSetId ); - Guid StartSnapshotSet(); - - /// - /// The AddToSnapshotSet method adds an original volume or original remote file share to the shadow copy set. - /// - /// - /// - /// Null-terminated wide character string containing the name of the volume or the UNC path of the remote file share to be - /// shadow copied. The name or UNC path must be in one of the following formats and must include a trailing backslash (\): - /// - /// - /// - /// The path of a mounted folder, for example, Y:\MountX\ - /// - /// - /// A drive letter, for example, D:\ - /// - /// - /// A volume GUID path of the form \\?\Volume{GUID}\ (where GUID identifies the volume) - /// - /// - /// A UNC path that specifies a remote file share, for example, \\Clusterx\Share1\ - /// - /// - /// - /// The provider to be used. GUID_NULL can be used, in which case the default provider will be used. - /// Returned identifier of the added shadow copy. - /// - /// - /// 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. - /// - /// - /// If pwszVolumeName is a UNC share path, the server name portion must be in hostname or fully qualified domain name format. - /// UNC share names with IP addresses must be normalized by calling the IVssBackupComponentsEx4::GetRootAndLogicalPrefixPaths - /// method before they are passed to AddToSnapshotSet. - /// - /// The maximum number of shadow copied volumes in a single shadow copy set is 64. - /// If ProviderId is GUID_NULL, the default provider is selected according to the following algorithm: - /// - /// - /// If any hardware provider supports the given volume or remote file share, that provider is selected. - /// - /// - /// If there is no hardware provider available, if any software provider supports the given volume, it is selected. - /// - /// - /// - /// If there is no hardware provider or software provider available, the system provider is selected. (There is only one - /// preinstalled system provider, which must support all nonremovable local volumes.) - /// - /// - /// - /// This method cannot be called for a virtual hard disk (VHD) that is nested inside another VHD. - /// Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: VHDs are not supported. - /// - /// The shadow copy identifier that is returned in the pidSnapshot parameter is stored in the Backup Components Document. - /// However, there is no method for querying this information, and the caller may need to store it so that it can be used during restore. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-addtosnapshotset HRESULT - // AddToSnapshotSet( [in] VSS_PWSZ pwszVolumeName, [in] VSS_ID ProviderId, [out] VSS_ID *pidSnapshot ); - Guid AddToSnapshotSet([MarshalAs(UnmanagedType.LPWStr)] string pwszVolumeName, Guid ProviderId); - - /// Commits all shadow copies in this set simultaneously. - /// - /// A doubly indirect pointer to the required IVssAsync asynchronous interface. This is used to query the method execution state - /// and to retrieve the final error code. - /// - /// - /// The caller is responsible for releasing the IVssAsync interface. - /// This method cannot be called for a virtual hard disk (VHD) that is nested inside another VHD. - /// Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: VHDs are not supported. - /// - /// For information on how to use IVssBackupComponents::DoSnapshotSet to create a standard backup shadow copy, see - /// Overview of Pre-Backup Tasks and Simple Shadow Copy Creation for Backup. For information on how the method is used under - /// different VSS contexts, see Implementation Details for Creating Shadow Copies. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-dosnapshotset HRESULT - // DoSnapshotSet( [out] IVssAsync **ppAsync ); - IVssAsync DoSnapshotSet(); - - /// The DeleteSnapshots method deletes one or more shadow copies or a shadow copy set. - /// Identifier of the shadow copy or a shadow copy set to be deleted. - /// - /// Type of the object on which all shadow copies will be deleted. The value of this parameter is VSS_OBJECT_SNAPSHOT or VSS_OBJECT_SNAPSHOT_SET. - /// - /// - /// If the value of this parameter is TRUE, the provider will do everything possible to delete the shadow copy or shadow - /// copies in a shadow copy set. If it is FALSE, no additional effort will be made. - /// - /// Number of deleted shadow copies. - /// - /// If an error occurs, the value of this parameter is the identifier of the first shadow copy that could not be deleted. - /// Otherwise, it is GUID_NULL. - /// - /// - /// - /// Multiple shadow copies in a shadow copy set are deleted sequentially. If an error occurs during one of these individual - /// deletions, DeleteSnapshots will return immediately; no attempt will be made to delete any remaining shadow copies. - /// The VSS_ID of the undeleted shadow copy is returned in pNondeletedSnapshotID. - /// - /// The requester is responsible for serializing the delete shadow copy operation. - /// - /// During a backup, shadow copies are automatically released as soon as the IVssBackupComponents instance is released. In this - /// case, it is not necessary to explicitly delete shadow copies. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-deletesnapshots HRESULT - // DeleteSnapshots( [in] VSS_ID SourceObjectId, [in] VSS_OBJECT_TYPE eSourceObjectType, [in] BOOL bForceDelete, [out] LONG - // *plDeletedSnapshots, [out] VSS_ID *pNondeletedSnapshotID ); - void DeleteSnapshots(Guid SourceObjectId, VSS_OBJECT_TYPE eSourceObjectType, [MarshalAs(UnmanagedType.Bool)] bool bForceDelete, - out int plDeletedSnapshots, out Guid pNondeletedSnapshotID); - - /// The ImportSnapshots method imports shadow copies transported from a different machine. - /// Doubly indirect pointer to an IVssAsync object containing the imported shadow copy status data. - /// - /// Only one shadow copy can be imported at a time. - /// The requester is responsible for serializing the import shadow copy operation. - /// The caller is responsible for releasing the IVssAsync interface. - /// For more information on importing shadow copies, see Importing Transportable Shadow Copied Volumes. - /// - /// Transportable shadow copies in a cluster: For details about using transportable shadow copies in a cluster, see Fast - /// Recovery Using Transportable Shadow Copied Volumes. The transportable shadow copy must be imported from outside the cluster - /// as long as the original volume is mounted within the cluster. - /// - /// - /// Note If the shadow copy import fails, the Volume Shadow Copy Service won't clean up LUNs on its own. The requester - /// has to initiate the cleanup of LUNs. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-importsnapshots HRESULT - // ImportSnapshots( [out] IVssAsync **ppAsync ); - IVssAsync ImportSnapshots(); - - /// The BreakSnapshotSet method causes the existence of a shadow copy set to be "forgotten" by VSS. - /// Shadow copy set identifier. - /// - /// - /// BreakSnapshotSet can be used only for shadow copies created by a hardware shadow copy provider. This method makes - /// these shadow copies regular volumes. - /// - /// - /// Shadow copies of volumes "broken" with BreakSnapshotSet must be managed independently of VSS as stand-alone volumes. - /// See Breaking Shadow Copies for more information. - /// - /// - /// IVssBackupComponentsEx2::BreakSnapshotSetEx is similar to the BreakSnapshotSet method, except that it has extra - /// parameters to query status and specify how the shadow copy set is broken. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-breaksnapshotset HRESULT - // BreakSnapshotSet( [in] VSS_ID SnapshotSetId ); - void BreakSnapshotSet(Guid SnapshotSetId); - - /// The GetSnapshotProperties method gets the properties of the specified shadow copy. - /// The identifier of the shadow copy of a volume as returned by IVssBackupComponents::AddToSnapshotSet. - /// - /// The address of a caller-allocated VSS_SNAPSHOT_PROP structure that receives the shadow copy properties. The software - /// provider is responsible for setting the members of this structure. The software provider allocates memory for all string - /// members that it sets in the structure. When the structure is no longer needed, the software provider is responsible for - /// freeing these strings by calling the VssFreeSnapshotProperties function. - /// - /// - /// - /// The caller should set the contents of the VSS_SNAPSHOT_PROP structure to zero before calling the - /// GetSnapshotProperties method. - /// - /// The provider is responsible for allocating and freeing the strings in the VSS_SNAPSHOT_PROP structure. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-getsnapshotproperties HRESULT - // GetSnapshotProperties( [in] VSS_ID SnapshotId, [out] VSS_SNAPSHOT_PROP *pProp ); - VSS_SNAPSHOT_PROP GetSnapshotProperties(Guid SnapshotId); - - /// - /// The Query method queries providers on the system and/or the completed shadow copies in the system that reside in the - /// current context. The method can be called only during backup operations. - /// - /// Reserved. The value of this parameter must be GUID_NULL. - /// - /// - /// Indicates restriction of the query to the given object type. A value of VSS_OBJECT_NONE indicates no restriction—that is, - /// all objects will be queried. - /// - /// Currently, the value of this parameter must be VSS_OBJECT_NONE. - /// - /// - /// Object types to be returned. The value of this parameter must be either VSS_OBJECT_SNAPSHOT or VSS_OBJECT_PROVIDER. - /// - /// Doubly indirect pointer to an IVssEnumObject enumerator object. - /// - /// - /// Because Query returns only information on completed shadow copies, the only shadow copy state it can disclose is VSS_SS_COMPLETED. - /// - /// - /// The method may be called only during backup operations and must be preceded by calls to - /// IVssBackupComponents::InitializeForBackup and IVssBackupComponents::SetContext. - /// - /// - /// While Query can return information on all of the providers available on a system, it will return only information - /// about shadow copies with the current context (set by IVssBackupComponents::SetContext). For instance, if the - /// _VSS_SNAPSHOT_CONTEXT context is set to VSS_CTX_BACKUP, Query will not return information on a shadow copy - /// created with a context of VSS_CTX_FILE_SHARE_BACKUP. - /// - /// - /// While this method currently returns a lists of all available providers and/or all completed shadow copies, in the future, - /// specialized queries may be supported: for instance, querying all shadow copies associated with a provider. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-query HRESULT Query( [in] VSS_ID - // QueriedObjectId, [in] VSS_OBJECT_TYPE eQueriedObjectType, [in] VSS_OBJECT_TYPE eReturnedObjectsType, [out] IVssEnumObject - // **ppEnum ); - IVssEnumObject Query(Guid QueriedObjectId, VSS_OBJECT_TYPE eQueriedObjectType, VSS_OBJECT_TYPE eReturnedObjectsType); - - /// - /// The IsVolumeSupported method determines whether the specified provider supports shadow copies on the specified volume - /// or remote file share. - /// - /// - /// Provider identifier. If the value is GUID_NULL, IsVolumeSupported checks whether any provider supports the volume or - /// remote file share. - /// - /// - /// - /// Volume name or UNC path of remote file share. The name or UNC path must be in one of the following formats and must include - /// a trailing backslash (\): - /// - /// - /// - /// The path of a mounted folder, for example, Y:\MountX\ - /// - /// - /// A drive letter, for example, D:\ - /// - /// - /// A volume GUID path of the form \\?\Volume{GUID}\ (where GUID identifies the volume) - /// - /// - /// A UNC path that specifies a remote file share, for example, \\Clusterx\Share1\ - /// - /// - /// - /// - /// Address of a caller-allocated variable that receives TRUE if shadow copies are supported on the specified volume or - /// remote file share, or FALSE otherwise. - /// - /// - /// - /// 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. - /// - /// - /// IsVolumeSupported will return TRUE if it is possible to create shadow copies on the given volume, even if the - /// current configuration does not allow the creation of shadow copies on that volume at the present time. - /// - /// - /// For example, if the maximum number of shadow copies has been reached on a given volume (and therefore no more shadow copies - /// can be created on that volume), the method will still indicate that the volume can be shadow copied. - /// - /// - /// Note For more information about the maximum number of shadow copies that can be created on a volume, see the entry - /// for MaxShadowCopies in Registry Keys and Values for Backup and Restore. - /// - /// This method cannot be called for a virtual hard disk (VHD) that is nested inside another VHD. - /// Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: VHDs are not supported. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-isvolumesupported HRESULT - // IsVolumeSupported( [in] VSS_ID ProviderId, [in] VSS_PWSZ pwszVolumeName, [out] BOOL *pbSupportedByThisProvider ); - [return: MarshalAs(UnmanagedType.Bool)] - bool IsVolumeSupported(Guid ProviderId, [MarshalAs(UnmanagedType.LPWStr)] string pwszVolumeName); - - /// The DisableWriterClasses method prevents a specific class of writers from receiving any events. - /// An array containing one or more writer class identifiers. - /// The number of entries in the rgWriterClassId array. - /// - /// - /// If you have multiple running copies of the same writer, they will all have the same writer class identifier, but they will - /// have different writer instance identifiers. Disabling a writer class causes all of the writer's instances to be disabled. - /// - /// - /// If the DisableWriterClasses method and the IVssBackupComponents::EnableWriterClasses method are never called, all - /// writer classes are enabled. - /// - /// - /// After the first call to DisableWriterClasses returns, the writer classes that were specified in the rgWriterClassId - /// array are disabled, and all other writer classes are enabled. - /// - /// - /// If you call DisableWriterClasses more than once, each call adds the writers in the rgWriterClassId array to the list - /// of disabled writers. - /// - /// - /// If you call DisableWriterClasses one or more times and then call EnableWriterClasses, the first call to - /// EnableWriterClasses cancels the effect of the calls to DisableWriterClasses and enables only the writers in - /// the rgWriterClassId array. - /// - /// - /// If you call DisableWriterClasses, you must do so before calling the IVssBackupComponents::GatherWriterMetadata - /// method. If you call GatherWriterMetadata first and then call DisableWriterClasses, the call to - /// DisableWriterClasses has no effect. If you need to call GatherWriterMetadata first, to determine which writer - /// classes to disable, you must call it from a different instance of the IVssBackupComponents interface. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-disablewriterclasses HRESULT - // DisableWriterClasses( [in] const VSS_ID *rgWriterClassId, [in] UINT cClassId ); - void DisableWriterClasses([In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 1)] Guid[] rgWriterClassId, uint cClassId); - - /// The EnableWriterClasses method enables the specified writers to receive all events. - /// An array containing one or more writer class identifiers. - /// The number of entries in the rgWriterClassId array. - /// - /// - /// If the EnableWriterClasses method and the IVssBackupComponents::DisableWriterClasses method are never called, all - /// writer classes are enabled. - /// - /// - /// After the first call to EnableWriterClasses returns, the writer classes that were specified in the rgWriterClassId - /// array are enabled, and all other writer classes are disabled. - /// - /// - /// If you call EnableWriterClasses more than once, each call adds the writers in the rgWriterClassId array to the list - /// of enabled writers. - /// - /// - /// If you call EnableWriterClasses one or more times and then call DisableWriterClasses, the call to - /// DisableWriterClasses disables any writers in the rgWriterClassId array that were enabled in the calls to EnableWriterClasses. - /// - /// - /// If you call EnableWriterClasses, you must do so before calling the IVssBackupComponents::GatherWriterMetadata method. - /// If you call GatherWriterMetadata first and then call EnableWriterClasses, the call to - /// EnableWriterClasses has no effect. If you need to call GatherWriterMetadata first, to determine which writer - /// classes to enable, you must call it from a different instance of the IVssBackupComponents interface. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-enablewriterclasses HRESULT - // EnableWriterClasses( [in] const VSS_ID *rgWriterClassId, [in] UINT cClassId ); - void EnableWriterClasses([In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 1)] Guid[] rgWriterClassId, uint cClassId); - - /// The DisableWriterInstances method disables a specified writer instance or instances. - /// An array containing one or more writer instance identifiers. - /// The number of entries in the rgWriterInstanceId array. - /// - /// - /// If you have multiple running copies of the same writer, they will all have the same writer class identifier, but they will - /// have different writer instance identifiers. Disabling one instance of a writer does not cause the writer's other instances - /// to be disabled. - /// - /// - /// If you call DisableWriterInstances, you must do so before calling the IVssBackupComponents::GatherWriterMetadata - /// method. If you call GatherWriterMetadata first and then call DisableWriterInstances, the call to - /// DisableWriterInstances has no effect. If you need to call GatherWriterMetadata first, to determine which - /// writer instances to disable, you must call it from a different instance of the IVssBackupComponents interface. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-disablewriterinstances HRESULT - // DisableWriterInstances( [in] const VSS_ID *rgWriterInstanceId, [in] UINT cInstanceId ); - void DisableWriterInstances([In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 1)] Guid[] rgWriterInstanceId, uint cInstanceId); - - /// The ExposeSnapshot method exposes a shadow copy as a drive letter, mounted folder, or file share. - /// Shadow copy identifier. - /// - /// - /// The path to the portion of the volume made available when exposing a shadow copy as a file share. The value of this - /// parameter must be NULL when exposing a shadow copy locally; that is, exposing it as a drive letter or mounted folder. - /// - /// The path cannot contain environment variables (for example, %MyEnv%) or wildcard characters. - /// - /// There is no requirement that the path end with a backslash (""). It is up to applications that retrieve this information to check. - /// - /// - /// - /// Attributes of the exposed shadow copy indicating whether it is exposed locally or remotely. The value must be either the - /// VSS_VOLSNAP_ATTR_EXPOSED_LOCALLY or the VSS_VOLSNAP_ATTR_EXPOSED_REMOTELY value of _VSS_VOLUME_SNAPSHOT_ATTRIBUTES. - /// - /// - /// When a shadow copy is exposed as a file share, the value of this parameter is the share name. If a shadow copy is exposed by - /// mounting it as a device, the parameter value is a drive letter followed by a colon—for example, "X:" or a mounted folder - /// path (for example, "Y:\MountX"). If the value of this parameter is NULL, then VSS determines the share name or drive - /// letter if the lAttributes parameter is VSS_VOLSNAP_ATTR_EXPOSED_REMOTELY. - /// - /// - /// The exposed name of the shadow copy. This is either a share name, a drive letter followed by a colon, or a mounted folder. - /// The value is NULL if ExposeSnapshot failed. VSS allocates the memory for this string. - /// - /// - /// - /// The caller is responsible for freeing the string that the pwszExposed parameter points to by calling the CoTaskMemFree function. - /// - /// When exposing a persistent shadow copy, it remains exposed through subsequent boots. - /// - /// When exposing a shadow copy of a volume, the shadow copy may be treated either as a mountable device or as a file system - /// available for file sharing. - /// - /// - /// When it is exposed as a device—as with other mountable devices—the shadow copy of a volume is exposed at its mount point - /// (drive letter or mounted folder) starting with its root. - /// - /// When exposed as a file share, subsets (indicated by wszPathFromRoot) of the volume can be shared. - /// For more information on how to expose shadow copies, see Exposing and Surfacing Shadow Copied Volumes. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-exposesnapshot HRESULT - // ExposeSnapshot( [in] VSS_ID SnapshotId, [in] VSS_PWSZ wszPathFromRoot, [in] LONG lAttributes, [in] VSS_PWSZ wszExpose, [out] - // VSS_PWSZ *pwszExposed ); - [return: MarshalAs(UnmanagedType.LPWStr)] - string ExposeSnapshot(Guid SnapshotId, [MarshalAs(UnmanagedType.LPWStr)] string wszPathFromRoot, int lAttributes, - [MarshalAs(UnmanagedType.LPWStr)] string wszExpose); - - /// - /// - /// The RevertToSnapshot method reverts a volume to a previous shadow copy. Only shadow copies created with persistent - /// contexts ( VSS_CTX_APP_ROLLBACK, VSS_CTX_CLIENT_ACCESSIBLE, VSS_CTX_CLIENT_ACCESSIBLE_WRITERS, or - /// VSS_CTX_NAS_ROLLBACK) are supported. - /// - /// Note This method is only supported on Windows Server operating systems. - /// - /// VSS_ID of the shadow copy to revert. - /// - /// If this parameter is TRUE, the volume will be dismounted and reverted even if the volume is in use. - /// - /// - /// This operation cannot be canceled, or undone once completed. If the computer is rebooted during the revert operation, the - /// revert process will continue when the system is restarted. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-reverttosnapshot HRESULT - // RevertToSnapshot( [in] VSS_ID SnapshotId, [in] BOOL bForceDismount ); - void RevertToSnapshot(Guid SnapshotId, [MarshalAs(UnmanagedType.Bool)] bool bForceDismount); - - /// - /// The QueryRevertStatus method returns an IVssAsync interface pointer that can be used to determine the status of the - /// revert operation. - /// - /// - /// - /// Null-terminated wide character string containing the name of the volume. The name must be in one of the following formats - /// and must include a trailing backslash (\): - /// - /// - /// - /// The path of a mounted folder, for example, Y:\MountX\ - /// - /// - /// A drive letter, for example, D:\ - /// - /// - /// A volume GUID path of the form \\?\Volume{GUID}\ (where GUID identifies the volume) - /// - /// - /// - /// - /// Pointer to a location that will receive an IVssAsync interface pointer that can be used to retrieve the status of the revert - /// process. When the operation is complete, the caller must release the interface pointer by calling the IUnknown::Release method. - /// - /// - /// The revert operation will continue even if the computer is rebooted, and cannot be canceled or undone, except by restoring a - /// backup created using another method. The QueryStatus method on the returned IVssAsync interface cannot return - /// VSS_S_ASYNC_CANCELLED as the revert operation cannot be canceled after it has started. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-queryrevertstatus HRESULT - // QueryRevertStatus( [in] VSS_PWSZ pwszVolume, [out] IVssAsync **ppAsync ); - IVssAsync QueryRevertStatus([MarshalAs(UnmanagedType.LPWStr)] string pwszVolume); - } - + public string pbstrWriter; + /// The address of a caller-allocated variable that receives a VSS_WRITER_STATE enumeration value. + public VSS_WRITER_STATE pnStatus; /// - /// - /// The IVssBackupComponentsEx interface provides methods for requesters to run backup and restore operations using multiple - /// writer instances. - /// - /// - /// To obtain an instance of the IVssBackupComponentsEx interface, call the QueryInterface method of the IVssBackupComponents - /// interface, passing IID_IVssBackupComponentsEx as the interface identifier (IID) parameter. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nl-vsbackup-ivssbackupcomponentsex - [PInvokeData("vsbackup.h", MSDNShortId = "NL:vsbackup.IVssBackupComponentsEx")] - [ComImport, Guid("963f03ad-9e4c-4a34-ac15-e4b6174e5036"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IVssBackupComponentsEx : IVssBackupComponents - { - /// The GetWriterMetadataEx method returns the metadata for a specific writer instance running on the system. - /// - /// Index of the writer whose metadata is to be retrieved. The value of this parameter is an integer from 0 to n–1 inclusive, - /// where n is the total number of writers on the current system. The value of n is returned by the - /// IVssBackupComponents::GetWriterMetadataCount method. - /// - /// - /// Address of a caller-allocated variable that receives the instance identifier of the writer that collected the metadata. - /// - /// - /// Doubly indirect pointer to the instance of the IVssExamineWriterMetadataEx object that contains the returned metadata. - /// - /// - /// - /// GetWriterMetadataEx is identical to the IVssBackupComponents::GetWriterMetadata method, except that it returns an - /// IVssExamineWriterMetadataEx interface pointer instead of an IVssExamineWriterMetadata interface pointer in the ppMetadata parameter. - /// - /// - /// A requester must call the asynchronous IVssBackupComponents::GatherWriterMetadata method and wait for it to complete prior - /// to calling GetWriterMetadataEx. - /// - /// - /// Although the GatherWriterMetadata method must be called prior to either a restore or backup operation, - /// GetWriterMetadataEx is not typically called for restores. - /// - /// - /// Component information retrieved (during backup operations) using the IVssExamineWriterMetadata::GetComponent method, where - /// the IVssExamineWriterMetadataEx interface has been returned by GetWriterMetadataEx, comes from the Writer Metadata - /// Document of a live writer process. - /// - /// - /// This is in contrast to the information returned by GetWriterComponents (during restore operations), which was stored in the - /// Backup Components Document by calls to the IVssBackupComponents::AddComponent method. - /// - /// When the caller of this method is finished accessing the metadata, it must call IUnknown::Release. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex-getwritermetadataex HRESULT - // GetWriterMetadataEx( [in] UINT iWriter, [out] VSS_ID *pidInstance, [out] IVssExamineWriterMetadataEx **ppMetadata ); - /*IVssExamineWriterMetadataEx*/ IntPtr GetWriterMetadataEx(uint iWriter, out Guid pidInstance); - - /// - /// The SetSelectedForRestoreEx method indicates whether the specified selectable component is selected for restoration - /// to a specified writer instance. - /// - /// Globally unique identifier (GUID) of the writer class. - /// Type of the component. See VSS_COMPONENT_TYPE for the possible values. - /// - /// - /// Null-terminated wide character string containing the logical path of the component. 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. - /// - /// The logical path can be NULL. - /// There are no restrictions on the characters that can appear in a non- NULL logical path. - /// - /// - /// Null-terminated wide character string containing the name of the component. - /// - /// The string cannot be NULL and should contain the same component name as was used when the component was added to the - /// backup set using the IVssBackupComponents::AddComponent method. - /// - /// - /// - /// If the value of this parameter is true, the selected component has been selected for restoration. If the value is - /// false, the selected component has not been selected for restoration. - /// - /// - /// GUID of the writer instance. - /// The default value for this parameter is GUID_NULL. - /// - /// - /// - /// SetSelectedForRestoreEx, which moves a component to a different writer instance, can be called only for a writer that - /// supports running multiple writer instances with the same class ID and supports a requester moving a component to a different - /// writer instance at restore time. To determine whether a writer provides this support, call the - /// IVssExamineWriterMetadata::GetBackupSchema method. - /// - /// SetSelectedForRestoreEx has meaning only for restores taking place in component mode. - /// - /// SetSelectedForRestoreEx can be called only for components that were explicitly added to the backup document at backup - /// time using AddComponent. Restoring a component that was implicitly selected for backup as part of a component set must be - /// done by calling SetSelectedForRestoreEx on the closest ancestor component that was added to the document. If only - /// this component's data is to be restored, that should be accomplished through the - /// IVssBackupComponents::AddRestoreSubcomponent method; this can be done only if the component is selectable for restore (see - /// Working with Selectability and Logical Paths). - /// - /// This method must be called before the IVssBackupComponents::PreRestore method. - /// - /// The distinction between the instanceId and writerID parameters is necessary because it is possible that multiple instances - /// of the same writer are running on the computer. - /// - /// - /// If the value of the instanceId parameter is GUID_NULL, this is equivalent to calling the - /// IVssBackupComponents::SetSelectedForRestore method. - /// - /// - /// The instanceId parameter is used to specify that the component is to be restored to a different writer instance. If the - /// value of the instanceId parameter is not GUID_NULL, it must match the instance ID of a writer instance with the same writer - /// class ID specified in in the writerID parameter. - /// - /// - /// A writer's class identifier, instance identifier, and instance name can be found by calling the - /// IVssExamineWriterMetadataEx::GetIdentityEx method. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex-setselectedforrestoreex - // HRESULT SetSelectedForRestoreEx( VSS_ID writerId, VSS_COMPONENT_TYPE ct, LPCWSTR wszLogicalPath, LPCWSTR wszComponentName, - // bool bSelectedForRestore, VSS_ID instanceId ); - void SetSelectedForRestoreEx(Guid writerId, VSS_COMPONENT_TYPE ct, [MarshalAs(UnmanagedType.LPWStr)] string wszLogicalPath, - [MarshalAs(UnmanagedType.LPWStr)] string wszComponentName, [MarshalAs(UnmanagedType.Bool)] bool bSelectedForRestore, - Guid instanceId = default); - } - - /// - /// Defines additional methods that requesters can use to run backup and restore operations. - /// - /// To obtain an instance of the IVssBackupComponentsEx2 interface, call the QueryInterface method of the - /// IVssBackupComponents interface, and pass the IID_IVssBackupComponentsEx2 constant as the interface identifier (IID) parameter. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nl-vsbackup-ivssbackupcomponentsex2 - [PInvokeData("vsbackup.h", MSDNShortId = "NL:vsbackup.IVssBackupComponentsEx2")] - [ComImport, Guid("acfe2b3a-22c9-4ef8-bd03-2f9ca230084e"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IVssBackupComponentsEx2 : IVssBackupComponentsEx - { - /// Unexposes a shadow copy either by deleting the file share or by removing the drive letter or mounted folder. - /// - /// The shadow copy identifier. The value of this identifier should be the same as the value that was used when the shadow copy - /// was exposed. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex2-unexposesnapshot HRESULT - // UnexposeSnapshot( [in] VSS_ID snapshotId ); - void UnexposeSnapshot(Guid snapshotId); - - /// Marks the restore of a component as authoritative for a replicated data store. - /// The globally unique identifier (GUID) of the writer class. - /// The type of the component. See the VSS_COMPONENT_TYPE enumeration for the possible values. - /// - /// - /// A null-terminated wide character string containing the logical path of the component. For more information, see - /// Logical Pathing of Components. - /// - /// - /// The value of the string containing the logical path used here should be the same as the string that was used when the - /// component was added. - /// - /// The logical path can be NULL. - /// There are no restrictions on the characters that can appear in a non- NULL logical path. - /// - /// - /// A null-terminated wide character string containing the name of the component. - /// - /// The string cannot be NULL and should contain the same component name as the string that was used when the component - /// was added to the backup set using the IVssBackupComponents::AddComponent method. - /// - /// - /// - /// Set this variable to true to indicate that the restore of the component is authoritative, or false otherwise. - /// The default value is false. - /// - /// - /// The SetAuthoritativeRestore method can only be called during a restore operation. - /// - /// A writer indicates that it supports authoritative restore by setting the VSS_BS_AUTHORITATIVE_RESTORE flag in its - /// backup schema mask. - /// - /// For more information, see Setting VSS Restore Options. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex2-setauthoritativerestore - // HRESULT SetAuthoritativeRestore( [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] LPCWSTR - // wszComponentName, [in] bool bAuth ); - void SetAuthoritativeRestore(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional, MarshalAs(UnmanagedType.LPWStr)] string wszLogicalPath, - [MarshalAs(UnmanagedType.LPWStr)] string wszComponentName, [MarshalAs(UnmanagedType.Bool)] bool bAuth); - - /// - /// Sets the roll-forward operation type for a component and specifies the restore point for a partial roll-forward operation. - /// - /// The globally unique identifier (GUID) of the writer class. - /// The type of the component. See the VSS_COMPONENT_TYPE enumeration for the possible values. - /// - /// - /// A null-terminated wide character string containing the logical path of the component. For more information, see - /// Logical Pathing of Components. - /// - /// - /// The value of the string containing the logical path used here should be the same as the string that was used when the - /// component was added. - /// - /// The logical path can be NULL. - /// There are no restrictions on the characters that can appear in a non- NULL logical path. - /// - /// - /// A null-terminated wide character string containing the name of the component. - /// - /// The string cannot be NULL and should contain the same component name as the string that was used when the component - /// was added to the backup set using the IVssBackupComponents::AddComponent method. - /// - /// - /// A VSS_ROLLFORWARD_TYPE enumeration value indicating the type of roll-forward operation to be performed. - /// - /// A null-terminated wide character string specifying the roll-forward restore point. - /// - /// The format of this string is defined by the writer, and can be a timestamp, a log sequence number (LSN), or any marker - /// defined by the writer. - /// - /// - /// - /// The SetRollForward method can only be called during a restore operation. - /// - /// A writer indicates that it supports this method by setting the VSS_BS_ROLLFORWARD_RESTORE flag in its backup schema mask. - /// - /// For more information, see Setting VSS Restore Options. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex2-setrollforward HRESULT - // SetRollForward( [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] LPCWSTR wszComponentName, - // [in] VSS_ROLLFORWARD_TYPE rollType, [in] LPCWSTR wszRollForwardPoint ); - void SetRollForward(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional, MarshalAs(UnmanagedType.LPWStr)] string wszLogicalPath, - [MarshalAs(UnmanagedType.LPWStr)] string wszComponentName, VSS_ROLLFORWARD_TYPE rollType, - [MarshalAs(UnmanagedType.LPWStr)] string wszRollForwardPoint); - - /// Assigns a new logical name to a component that is being restored. - /// The globally unique identifier (GUID) of the writer class. - /// The type of the component. See the VSS_COMPONENT_TYPE enumeration for the possible values. - /// - /// - /// A null-terminated wide character string containing the logical path of the component. For more information, see - /// Logical Pathing of Components. - /// - /// - /// The value of the string containing the logical path used here should be the same as the string that was used when the - /// component was added. - /// - /// The logical path can be NULL. - /// There are no restrictions on the characters that can appear in a non- NULL logical path. - /// - /// - /// A null-terminated wide character string containing the name of the component. - /// - /// The string cannot be NULL and should contain the same component name as was the component name that was used when the - /// component was added to the backup set using the IVssBackupComponents::AddComponent method. - /// - /// - /// - /// A null-terminated wide character string containing the restore name to be set for the component. - /// - /// - /// The SetRestoreName method can only be called during a restore operation. - /// - /// A writer indicates that it supports this method by setting the VSS_BS_RESTORE_RENAME flag in its backup schema mask. - /// - /// For more information, see Setting VSS Restore Options. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex2-setrestorename HRESULT - // SetRestoreName( VSS_ID writerId, VSS_COMPONENT_TYPE ct, LPCWSTR wszLogicalPath, LPCWSTR wszComponentName, LPCWSTR - // wszRestoreName ); - void SetRestoreName(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional, MarshalAs(UnmanagedType.LPWStr)] string wszLogicalPath, - [MarshalAs(UnmanagedType.LPWStr)] string wszComponentName, [MarshalAs(UnmanagedType.LPWStr)] string wszRestoreName); - - /// Breaks a shadow copy set according to requester-specified options. - /// A shadow copy set identifier. - /// A bitmask of _VSS_HARDWARE_OPTIONS flags that specify how the shadow copy set is broken. - /// - /// A pointer to a variable that receives an IVssAsync interface pointer that can be used to retrieve the status of the shadow - /// copy set break operation. When the break operation is complete, the IUnknown::Release method must be called for this - /// interface pointer. - /// - /// - /// - /// BreakSnapshotSetEx is similar to the IVssBackupComponents::BreakSnapshotSet method, except that it has extra - /// parameters to query status and specify how the shadow copy set is broken. - /// - /// - /// Like BreakSnapshotSet, BreakSnapshotSetEx can be used only for shadow copies that were created by a hardware shadow - /// copy provider. - /// - /// - /// After this method returns, the shadow copy volume is still a volume, but it is no longer a shadow copy. For more - /// information, see Breaking Shadow Copies. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex2-breaksnapshotsetex HRESULT - // BreakSnapshotSetEx( VSS_ID SnapshotSetID, DWORD dwBreakFlags, [out] IVssAsync **ppAsync ); - IVssAsync BreakSnapshotSetEx(Guid SnapshotSetID, VSS_HARDWARE_OPTIONS dwBreakFlags); - - /// - /// Not supported. - /// This method is reserved for future use. - /// - /// This parameter is reserved for future use. - /// This parameter is reserved for future use. - /// This parameter is reserved for future use. - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex2-prefastrecovery HRESULT - // PreFastRecovery( VSS_ID SnapshotSetID, DWORD dwPreFastRecoveryFlags, IVssAsync **ppAsync ); - IVssAsync PreFastRecovery(Guid SnapshotSetID, uint dwPreFastRecoveryFlags); - - /// - /// Not supported. - /// This method is reserved for future use. - /// - /// This parameter is reserved for future use. - /// This parameter is reserved for future use. - /// This parameter is reserved for future use. - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex2-fastrecovery HRESULT - // FastRecovery( VSS_ID SnapshotSetID, DWORD dwFastRecoveryFlags, IVssAsync **ppAsync ); - IVssAsync FastRecovery(Guid SnapshotSetID, uint dwFastRecoveryFlags); - } - - /// - /// - /// Defines additional methods that requesters can use to perform LUN resynchronization and return extended writer status information. - /// - /// - /// To obtain an instance of the IVssBackupComponentsEx3 interface, call the QueryInterface method of the - /// IVssBackupComponents interface, and pass the IID_IVssBackupComponentsEx3 constant as the interface identifier (IID) parameter. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nl-vsbackup-ivssbackupcomponentsex3 - [PInvokeData("vsbackup.h", MSDNShortId = "NL:vsbackup.IVssBackupComponentsEx3")] - [ComImport, Guid("c191bfbc-b602-4675-8bd1-67d642f529d5"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IVssBackupComponentsEx3 : IVssBackupComponentsEx2 - { - /// Returns extended status information for the specified writer. - /// - /// The index of the writer whose metadata is to be retrieved. The value of this parameter is an integer from 0 to n–1 - /// inclusive, where n is the total number of writers on the current system. The value of n is returned by the - /// IVssBackupComponents::GetWriterStatusCount method. - /// - /// - /// The address of a caller-allocated variable that receives the instance identifier of the writer. This parameter is required - /// and cannot be NULL. - /// - /// - /// The address of a caller-allocated variable that receives the identifier for the writer class. This parameter is required and - /// cannot be NULL. - /// - /// - /// The address of a caller-allocated variable that receives a string containing the name of the specified writer. This - /// parameter is required and cannot be NULL. - /// - /// - /// The address of a caller-allocated variable that receives a VSS_WRITER_STATE enumeration value. This parameter is required - /// and cannot be NULL. - /// - /// - /// - /// The address of a caller-allocated variable that receives the HRESULT failure code that the writer returned for the hrWriter - /// parameter of the CVssWriterEx2::SetWriterFailureEx method. - /// - /// The following are the supported values. - /// - /// - /// Value - /// Meaning - /// - /// - /// S_OK - /// The writer was successful. - /// - /// - /// VSS_E_WRITERERROR_INCONSISTENTSNAPSHOT - /// The shadow copy contains only a subset of the volumes needed by the writer to correctly back up the application component. - /// - /// - /// VSS_E_WRITERERROR_OUTOFRESOURCES - /// - /// The writer ran out of memory or other system resources. The recommended way to handle this error code is to wait ten minutes - /// and then repeat the operation, up to three times. - /// - /// - /// - /// VSS_E_WRITERERROR_TIMEOUT - /// - /// The writer operation failed because of a time-out between the Freeze and Thaw events. The recommended way to handle this - /// error code is to wait ten minutes and then repeat the operation, up to three times. - /// - /// - /// - /// VSS_E_WRITERERROR_RETRYABLE - /// - /// The writer failed due to an error that would likely not occur if the entire backup, restore, or shadow copy creation process - /// was restarted. The recommended way to handle this error code is to wait ten minutes and then repeat the operation, up to - /// three times. - /// - /// - /// - /// VSS_E_WRITERERROR_NONRETRYABLE - /// - /// The writer operation failed because of an error that might recur if another shadow copy is created. For more information, - /// see Event and Error Handling Under VSS. - /// - /// - /// - /// VSS_E_WRITER_NOT_RESPONDING - /// The writer is not responding. - /// - /// - /// VSS_E_WRITER_STATUS_NOT_AVAILABLE - /// - /// The writer status is not available for one or more writers. A writer may have reached the maximum number of available backup - /// and restore sessions. - /// - /// - /// - /// VSS_E_WRITERERROR_PARTIAL_FAILURE - /// - /// The writer is reporting one or more component-level errors. To retrieve the errors, the requester must use the - /// IVssComponentEx2::GetFailure method. - /// - /// - /// - /// - /// - /// The address of a caller-allocated variable that receives the return code that the writer passed for the hrApplication - /// parameter of the CVssWriterEx2::SetWriterFailureEx method. This parameter is optional and can be NULL. - /// - /// - /// The address of a variable that receives the application failure message that the writer passed for the wszApplicationMessage - /// parameter of the SetWriterFailureEx method. This parameter is optional and can be NULL. - /// - /// - /// - /// A requester must call the asynchronous operation IVssBackupComponents::GatherWriterStatus and wait for it to complete before - /// calling IVssBackupComponentsEx3::GetWriterStatusEx. - /// - /// - /// If this method returns VSS_E_WRITERERROR_PARTIAL_FAILURE, the requester should use the IVssComponentEx2::GetFailure method - /// to retrieve the component-level errors. - /// - /// - /// When the caller has finished accessing the status information returned by this method, it should call SysFreeString to free - /// the memory held by the pbstrWriter and pbstrApplicationMessage parameters. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex3-getwriterstatusex HRESULT - // GetWriterStatusEx( [in] UINT iWriter, [out] VSS_ID *pidInstance, [out] VSS_ID *pidWriter, [out] BSTR *pbstrWriter, [out] - // VSS_WRITER_STATE *pnStatus, [out] HRESULT *phrFailureWriter, [out, optional] HRESULT *phrApplication, [out, optional] BSTR - // *pbstrApplicationMessage ); - void GetWriterStatusEx(uint iWriter, out Guid pidInstance, out Guid pidWriter, [MarshalAs(UnmanagedType.BStr)] out string pbstrWriter, - out VSS_WRITER_STATE pnStatus, out HRESULT phrFailureWriter, out HRESULT phrApplication, - [MarshalAs(UnmanagedType.BStr)] out string pbstrApplicationMessage); - - /// - /// Specifies the volumes to be included in a LUN resynchronization operation. This method is supported only on Windows server - /// operating systems. - /// - /// - /// The identifier of the shadow copy that was returned by the IVssBackupComponents::AddToSnapshotSet method during backup. This - /// parameter is required and cannot be GUID_NULL. - /// - /// This parameter is reserved and must be zero. - /// - /// This parameter is optional and can be NULL. A value of NULL means that the contents of the shadow copy volume - /// are to be copied back to the original volume. VSS identifies the original volume by the VDS_LUN_INFO information in the - /// Backup Components Document. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex3-addsnapshottorecoveryset - // HRESULT AddSnapshotToRecoverySet( [in] VSS_ID snapshotId, [in] DWORD dwFlags, [in, optional] VSS_PWSZ pwszDestinationVolume ); - void AddSnapshotToRecoverySet(Guid snapshotId, [Optional] uint dwFlags, [MarshalAs(UnmanagedType.LPWStr)] string pwszDestinationVolume = default); - - /// Initiates a LUN resynchronization operation. This method is supported only on Windows server operating systems. - /// A bitmask of VSS_RECOVERY_OPTIONS flags that specify how the resynchronization is to be performed. - /// - /// A pointer to a variable that receives an IVssAsync interface pointer that can be used to retrieve the status of the LUN - /// resynchronization operation. When the operation is complete, the caller must release the interface pointer by calling the - /// IUnknown::Release method. - /// - /// - /// - /// At the end of the resynchronization operation, by default the newly resychronized LUN will have the same disk signature that - /// the destination LUN had before the resynchronization. - /// - /// - /// This method cannot be called in WinPE, and it cannot be called in Safe mode. Before calling this method, the caller must - /// call IVssBackupComponents::InitializeForRestore to prepare for the resynchronization. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex3-recoverset HRESULT - // RecoverSet( [in] DWORD dwFlags, [out] IVssAsync **ppAsync ); - IVssAsync RecoverSet(VSS_RECOVERY_OPTIONS dwFlags); - - /// Returns the requester's session identifier. - /// A pointer to a variable that receives the session identifier. - /// - /// - /// The session identifier is an opaque value that uniquely identifies a backup or restore session. It is used to distinguish - /// the current session among multiple parallel backup or restore sessions. - /// - /// - /// As a best practice, writers and requesters should include the session ID in all diagnostics messages used for event logging - /// and tracing. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex3-getsessionid HRESULT - // GetSessionId( [out] VSS_ID *idSession ); - Guid GetSessionId(); - } - - /// - /// Defines additional methods to support the processing of UNC file share paths in a requester. - /// - /// To obtain an instance of the IVssBackupComponentsEx4 interface, call the QueryInterface method of the - /// IVssBackupComponents interface, and pass the IID_IVssBackupComponentsEx4 constant as the interface identifier (IID) parameter. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nl-vsbackup-ivssbackupcomponentsex4 - [PInvokeData("vsbackup.h", MSDNShortId = "NL:vsbackup.IVssBackupComponentsEx4")] - [ComImport, Guid("f434c2fd-b553-4961-a9f9-a8e90b673e53"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IVssBackupComponentsEx4 : IVssBackupComponentsEx3 - { - /// - /// Normalizes a local volume path or UNC share path so that it can be passed to the IVssBackupComponents::AddToSnapshotSet method. - /// - /// The path to be normalized. - /// - /// Receives the root path that should be passed to the IVssBackupComponents::AddToSnapshotSet method. - /// - /// - /// If pwszFilePath is a local path, this parameter receives the volume GUID name. If it's a UNC path, this parameter receives a - /// fully evaluated share path. - /// - /// - /// If pwszFilePath is a UNC share path, the server name portion can be - /// - /// - /// A host name - /// - /// - /// - /// A fully qualified domain name - /// - /// - /// - /// An IP address - /// - /// - /// - /// - /// This parameter specifies whether host name format or fully qualified domain name format should be used in the server name - /// portion of the normalized root path that is returned in the ppwszRootPath parameter. - /// - /// If this parameter is FALSE, simple host name format will be used. - /// The default value for this parameter is FALSE. - /// If this parameter is TRUE, fully qualified domain name will be used. - /// In a deployment where a host name could exist in multiple domain suffixes, this parameter should be TRUE. - /// - /// - /// - /// This method normalizes a local volume path or UNC share path and separates it into a root path and a logical prefix path. - /// The root path can then be passed to the IVssBackupComponents::AddToSnapshotSet method. - /// - /// - /// If pwszFilePath is a local volume path, the root path will be similar to a volume mount point. In this case, the root and - /// the logical prefix paths map to the results of GetVolumePathName and GetVolumeNameForVolumeMountPoint, respectively. - /// - /// - /// If pwszFilePath is a UNC share path, the root and logical prefix paths map to the root path of the file share and the fully - /// evaluated physical share path (which will take into account DFS and cluster deployment), respectively. - /// - /// - /// If you call this method more than once for the same shadow copy set creation operation, you must set the - /// bNormalizeFQDNforRootPath to the same value for every call. Fully qualified domain name format and host name format cannot - /// be mixed in the same shadow copy set. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex4-getrootandlogicalprefixpaths - // HRESULT GetRootAndLogicalPrefixPaths( [in] VSS_PWSZ pwszFilePath, [out] VSS_PWSZ *ppwszRootPath, [out] VSS_PWSZ - // *ppwszLogicalPrefix, [in, optional] BOOL bNormalizeFQDNforRootPath ); - void GetRootAndLogicalPrefixPaths([MarshalAs(UnmanagedType.LPWStr)] string pwszFilePath, [MarshalAs(UnmanagedType.LPWStr)] out string ppwszRootPath, - [MarshalAs(UnmanagedType.LPWStr)] out string ppwszLogicalPrefix, [MarshalAs(UnmanagedType.Bool)] bool bNormalizeFQDNforRootPath = false); - } - - /// - /// - /// The IVssExamineWriterMetadata interface is a C++ (not COM) interface that allows a requester to examine the metadata of a - /// specific writer instance. This metadata may come from a currently executing (live) writer, or it may have been stored as an XML document. - /// - /// An IVssExamineWriterMetadata interface to a live writer's metadata is obtained by a call to IVssBackupComponents::GetWriterMetadata. - /// - /// Metadata obtained from a stored XML document can be examined by an instance of IVssExamineWriterMetadata obtained by a - /// call to CreateVssExamineWriterMetadata. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nl-vsbackup-ivssexaminewritermetadata - [PInvokeData("vsbackup.h", MSDNShortId = "NL:vsbackup.IVssExamineWriterMetadata")] - [ComVisible(true), Guid("902fcf7f-b7fd-42f8-81f1-b2e400b1e5bd"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - private interface IVssExamineWriterMetadata - { - /// The GetAlternateLocationMapping method obtains a specific alternate location mapping of a file set. - /// - /// Index of a particular mapping. The value of this parameter is an integer from 0 to n–1 inclusive, where n is the total - /// number of alternate location mappings associated with a given writer. The value of n is returned by IVssExamineWriterMetadata::GetRestoreMethod. - /// - /// - /// Doubly indirect pointer to an IVssWMFiledesc object containing the alternate location mapping information. - /// - /// - /// The following are the valid return codes for this method. - /// - /// - /// Value - /// Meaning - /// - /// - /// S_OK - /// Successfully returned a pointer to an IVssWMFiledesc interface. - /// - /// - /// E_INVALIDARG - /// One of the parameter values is not valid. - /// - /// - /// E_OUTOFMEMORY - /// The caller is out of memory or other system resources. - /// - /// - /// 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 specified alternate location mapping does not exist. - /// - /// - /// 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. - /// - /// - /// - /// - /// - /// - /// The value returned by IVssExamineWriterMetadata::GetAlternateLocationMapping should not be confused with that - /// returned by IVssComponent::GetAlternateLocationMapping. - /// - /// IVssComponent::GetAlternateLocationMapping is the alternate location to which a file was restored. - /// - /// IVssExamineWriterMetadata::GetAlternateLocationMapping is the alternate location mapping to which a file may be - /// restored if necessary. - /// - /// A file should always be restored to its alternate location mapping if either of the following is true: - /// - /// - /// The restore method (set at backup time) is VSS_RME_RESTORE_TO_ALTERNATE_LOCATION. - /// - /// - /// Its restore target was set (at restore time) to VSS_RT_ALTERNATE. - /// - /// - /// In either case, if no valid alternate location mapping is defined, this constitutes a writer error. - /// A file may be restored to an alternate location mapping if either of the following is true: - /// - /// - /// The restore method is VSS_RME_RESTORE_IF_NOT_THERE and a version of the file is already present on disk. - /// - /// - /// The restore method is VSS_RME_RESTORE_IF_CAN_REPLACE and a version of the file is present on disk and cannot be replaced. - /// - /// - /// Again, if no valid alternate location mapping is defined, this constitutes a writer error. - /// - /// An alternate location mapping is used only during a restore operation and should not be confused with an alternate path, - /// which is used only during a backup operation. - /// - /// The caller is responsible for calling IUnknown::Release to release the resources of the returned IVssWMFiledesc object. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadata-getalternatelocationmapping - // HRESULT GetAlternateLocationMapping( [in] UINT iMapping, [out] IVssWMFiledesc **ppFiledesc ); - [PreserveSig] - HRESULT GetAlternateLocationMapping(uint iMapping, out IVssWMFiledesc ppFiledesc); - - /// - /// The GetBackupSchema method is used by a requester to determine from the Writer Metadata Document the types of backup - /// operations that a given writer can participate in. - /// - /// - /// The types of backup operations that a given writer supports, expressed as a bit mask (or bitwise OR) of VSS_BACKUP_SCHEMA - /// enumeration values. - /// - /// - /// The following are the valid return codes for this method. - /// - /// - /// Value - /// Meaning - /// - /// - /// S_OK - /// Successfully set the failure message. - /// - /// - /// E_INVALIDARG - /// The backup schema argument is not valid. - /// - /// - /// E_OUTOFMEMORY - /// The caller is out of memory or other system resources. - /// - /// - /// 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. - /// - /// - /// - /// - /// - /// - /// The default backup schema is VSS_BS_UNDEFINED: the writer supports only simple full backup and restoration of entire files - /// (as defined by VSS_BT_FULL), there is no support for incremental or differential backups, and partial files are not supported. - /// - /// - /// The writer calls IVssCreateWriterMetadata::SetBackupSchema to indicate its supported schema in its Writer Metadata Document. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadata-getbackupschema HRESULT - // GetBackupSchema( DWORD *pdwSchemaMask ); - [PreserveSig] - HRESULT GetBackupSchema(out VSS_BACKUP_SCHEMA pdwSchemaMask); - - /// The GetComponent method obtains a Writer Metadata Document for a specified backup component. - /// - /// Index for a component. The value of this parameter is an integer from 0 to n–1 inclusive, where n is the total number of - /// components supported by a given writer. The value of n is returned by IVssExamineWriterMetadata::GetFileCounts. - /// - /// Doubly indirect pointer to a IVssWMComponent object containing the component information. - /// - /// The following are the valid return codes for this method. - /// - /// - /// Value - /// Meaning - /// - /// - /// S_OK - /// Successfully returned a pointer to an IVssWMComponent interface. - /// - /// - /// E_INVALIDARG - /// One of the parameter values is not valid. - /// - /// - /// E_OUTOFMEMORY - /// The caller is out of memory or other system resources. - /// - /// - /// 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 specified component does not exist. - /// - /// - /// 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. - /// - /// - /// - /// - /// - /// The caller is responsible for calling IUnknown::Release to release the resources of the returned IVssWMComponent object. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadata-getcomponent HRESULT - // GetComponent( [in] UINT iComponent, [out] IVssWMComponent **ppComponent ); - [PreserveSig] - HRESULT GetComponent(uint iComponent, out IVssWMComponent ppComponent); - - /// - /// Not supported. - /// This method is reserved for system use. - /// - /// This parameter is reserved for system use. - /// This method does not return a value. - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadata-getdocument HRESULT - // GetDocument( IXMLDOMDocument **pDoc ); - [PreserveSig] - HRESULT GetDocument([MarshalAs(UnmanagedType.IDispatch)] out object pDoc); - - /// - /// The GetExcludeFile method obtains information about files that have been explicitly excluded from backup for a given writer. - /// - /// - /// Index for an excluded file set. The value of this parameter is an integer from 0 to n–1 inclusive, where n is the total - /// number of file sets explicitly excluded from the components of a given writer. The value of n is returned by IVssExamineWriterMetadata::GetFileCounts. - /// - /// Doubly indirect pointer to an IVssWMFiledesc object containing the file element information. - /// - /// The following are the valid return codes for this method. - /// - /// - /// Value - /// Meaning - /// - /// - /// S_OK - /// Successfully returned a pointer to an IVssWMFiledesc interface. - /// - /// - /// E_INVALIDARG - /// One of the parameter values is not valid. - /// - /// - /// E_OUTOFMEMORY - /// The caller is out of memory or other system resources. - /// - /// - /// 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 file set specified for exclusion does not exist. - /// - /// - /// 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. - /// - /// - /// - /// - /// - /// For more information on excluding files, see Exclude File List Specification. - /// The caller is responsible for calling IUnknown::Release to release the resources of the returned IVssWMFiledesc object. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadata-getexcludefile HRESULT - // GetExcludeFile( [in] UINT iFile, [out] IVssWMFiledesc **ppFiledesc ); - [PreserveSig] - HRESULT GetExcludeFile(uint iFile, out IVssWMFiledesc ppFiledesc); - - /// The GetFileCounts method obtains excluded files and the number of components that a writer manages. - /// Reserved for system use. - /// - /// The address of a caller-allocated variable that receives the number of file sets that are explicitly excluded from the backup. - /// - /// - /// The address of a caller-allocated variable that receives the total number of components that are managed by the current writer. - /// - /// - /// The following are the valid return codes for this method. - /// - /// - /// Value - /// Meaning - /// - /// - /// S_OK - /// Successfully returned the number of files. - /// - /// - /// E_INVALIDARG - /// One of the parameter values is not valid. - /// - /// - /// E_OUTOFMEMORY - /// The caller is out of memory or other system resources. - /// - /// - /// 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_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. - /// - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadata-getfilecounts HRESULT - // GetFileCounts( [out] UINT *pcIncludeFiles, [out] UINT *pcExcludeFiles, [out] UINT *pcComponents ); - [PreserveSig] - HRESULT GetFileCounts(out uint pcIncludeFiles, out uint pcExcludeFiles, out uint pcComponents); - - /// The GetIdentity method obtains basic information about a specific writer instance. - /// The address of a caller-allocated variable that receives the instance identifier of the writer. - /// The address of a caller-allocated variable that receives the class identifier of the writer. - /// - /// The address of a caller-allocated variable that receives a string that contains the name of the writer. - /// - /// - /// The address of a caller-allocated variable that receives a VSS_USAGE_TYPE enumeration value that specifies how the data - /// managed by the writer is used on the host system. - /// - /// - /// The address of a caller-allocated variable that receives a VSS_SOURCE_TYPE enumeration value that specifies the type of data - /// managed by the writer. - /// - /// - /// The following are the valid return codes for this method. - /// - /// - /// Value - /// Meaning - /// - /// - /// S_OK - /// Successfully returned the identity information. - /// - /// - /// E_INVALIDARG - /// One of the parameter values is not valid. - /// - /// - /// E_OUTOFMEMORY - /// The caller is out of memory or other system resources. - /// - /// - /// 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_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. - /// - /// - /// - /// - /// - /// The caller must free the memory held by the pbstrWriterName parameter by calling SysFreeString. - /// - /// An IVssExamineWriterMetadata interface might be from stored writer state information (created by a call to - /// CreateVssExamineWriterMetadata). If this is the case, then the following are true: - /// - /// - /// - /// pidInstance may not mean anything in terms of live writers. - /// - /// - /// If pidWriter does not match the writer class of any live writer, a requester should not use that writer's components. - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadata-getidentity HRESULT - // GetIdentity( [out] VSS_ID *pidInstance, [out] VSS_ID *pidWriter, [out] BSTR *pbstrWriterName, [out] VSS_USAGE_TYPE *pUsage, - // [out] VSS_SOURCE_TYPE *pSource ); - [PreserveSig] - HRESULT GetIdentity(out Guid pidInstance, out Guid pidWriter, [MarshalAs(UnmanagedType.BStr)] out string pbstrWriterName, - out VSS_USAGE_TYPE pUsage, out VSS_SOURCE_TYPE pSource); - - /// - /// Not supported. - /// This method is reserved for system use. - /// - /// This parameter is reserved for system use. - /// This parameter is reserved for system use. - /// This method does not return a value. - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadata-getincludefile HRESULT - // GetIncludeFile( UINT iFile, IVssWMFiledesc **ppFiledesc ); - [PreserveSig] - HRESULT GetIncludeFile(uint iFile, out IVssWMFiledesc ppFiledesc); - - /// The GetRestoreMethod method returns information about how a writer wants its data to be restored. - /// - /// Pointer to a VSS_RESTOREMETHOD_ENUM value that specifies file overwriting, the use of alternate locations specifying the - /// method that will be used in the restore operation. - /// - /// - /// If the value of pMethod is VSS_RME_STOP_RESTORE_START or VSS_RME_RESTORE_STOP_START, a pointer to a string containing the - /// name of the service that is started and stopped. Otherwise, the value is NULL. - /// - /// - /// Pointer to the URL of an HTML or XML document describing to the user how the restore is to be performed. The value may be NULL. - /// - /// - /// Pointer to a VSS_WRITERRESTORE_ENUM value specifying whether the writer will be involved in restoring its data. - /// - /// - /// Pointer to a Boolean value indicating whether a reboot will be required after the restore operation is complete. The value - /// receives true if a reboot will be required, or false otherwise. - /// - /// Pointer to the number of alternate mappings associated with the writer. - /// - /// The following are the valid return codes for this method. - /// - /// - /// Value - /// Meaning - /// - /// - /// S_OK - /// Successfully returned the restore method information. - /// - /// - /// S_FALSE - /// A restore method does not exist. - /// - /// - /// E_INVALIDARG - /// One of the parameter values is not valid. - /// - /// - /// E_OUTOFMEMORY - /// The caller is out of memory or other system resources. - /// - /// - /// 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_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. - /// - /// - /// - /// - /// - /// The caller must free the memory used by the pbstrUserProcedure and pbstrService parameters by calling SysFreeString. - /// A file should always be restored to its alternate location mapping if either of the following is true: - /// - /// - /// The restore method (set at backup time) is VSS_RME_RESTORE_TO_ALTERNATE_LOCATION. - /// - /// - /// Its restore target was set (at restore time) to VSS_RT_ALTERNATE. - /// - /// - /// In either case, if no valid alternate location mapping is defined, this constitutes a writer error. - /// A file can be restored to an alternate location mapping if : - /// - /// - /// The restore method is VSS_RME_RESTORE_IF_NOT_THERE and a version of the file is already present on disk. - /// - /// - /// The restore method is VSS_RME_RESTORE_IF_CAN_REPLACE and a version of the file is present on disk and cannot be replaced. - /// - /// - /// Again, if no valid alternate location mapping is defined, this constitutes a writer error. - /// - /// An alternate location mapping is used only during a restore operation and should not be confused with an alternate path, - /// which is used only during a backup operation. - /// - /// For more information about restore methods, see Setting VSS Restore Methods. - /// - /// If the restore method is VSS_RME_STOP_RESTORE_START or VSS_RME_RESTORE_STOP_START, a requester uses the name returned by - /// pbstrService to determine which service must be stopped during and then restarted after restore. See Stopping Services For - /// Restore by Requesters for information on writer participation in stopping and restarting services during a restore operation. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadata-getrestoremethod HRESULT - // GetRestoreMethod( [out] VSS_RESTOREMETHOD_ENUM *pMethod, [out] BSTR *pbstrService, [out] BSTR *pbstrUserProcedure, [out] - // VSS_WRITERRESTORE_ENUM *pwriterRestore, [out] bool *pbRebootRequired, [out] UINT *pcMappings ); - [PreserveSig] - HRESULT GetRestoreMethod(out VSS_RESTOREMETHOD_ENUM pMethod, [MarshalAs(UnmanagedType.BStr)] out string pbstrService, - [MarshalAs(UnmanagedType.BStr)] out string pbstrUserProcedure, out VSS_WRITERRESTORE_ENUM pwriterRestore, - [MarshalAs(UnmanagedType.Bool)] out bool pbRebootRequired, out uint pcMappings); - - /// - /// The LoadFromXML method loads an XML document that contains a writer's metadata document into an - /// IVssExamineWriterMetadata interface. - /// - /// String that contains an XML document that represents a writer's metadata document. - /// - /// The following are the valid return codes for this method. - /// - /// - /// Value - /// Meaning - /// - /// - /// S_OK - /// Successfully added the bstrXML parameter value to the XML document. - /// - /// - /// S_FALSE - /// The XML document could not be loaded. - /// - /// - /// E_INVALIDARG - /// One of the parameter values is not valid. - /// - /// - /// E_OUTOFMEMORY - /// The caller is out of memory or other system resources. - /// - /// - /// 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_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. - /// - /// - /// - /// - /// - /// - /// This method is used at restore time to load writer metadata that was saved by IVssExamineWriterMetadata::SaveAsXML at the - /// time of the backup operation. - /// - /// Users should not tamper with this metadata document. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadata-loadfromxml HRESULT - // LoadFromXML( [in] BSTR bstrXML ); - [PreserveSig] - HRESULT LoadFromXML([MarshalAs(UnmanagedType.BStr)] string bstrXML); - - /// - /// The SaveAsXML method saves the Writer Metadata Document that contains a writer's state information to a specified - /// string. This string can be saved as part of a backup operation. - /// - /// - /// Pointer to a string to be used to store the Writer Metadata Document that contains a writer's state information. - /// - /// - /// The following are the valid return codes for this method. - /// - /// - /// Value - /// Meaning - /// - /// - /// S_OK - /// Successfully saved the contents of the XML document in the pbstrXML parameter value. - /// - /// - /// E_INVALIDARG - /// One of the parameter values is not valid. - /// - /// - /// E_OUTOFMEMORY - /// The caller is out of memory or other system resources. - /// - /// - /// 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. - /// - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadata-saveasxml HRESULT - // SaveAsXML( [in] BSTR *pbstrXML ); - [PreserveSig] - HRESULT SaveAsXML([MarshalAs(UnmanagedType.BStr)] out string pbstrXML); - } - - /// - /// - /// The IVssExamineWriterMetadataEx interface is a C++ (not COM) interface that provides a method to retrieve the writer - /// instance name and other basic information for a specific writer instance. - /// - /// - /// To obtain an instance of the IVssExamineWriterMetadataEx interface, call the QueryInterface method of the - /// IVssExamineWriterMetadata interface, passing IID_IVssExamineWriterMetadataEx as the interface identifier (IID) parameter. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nl-vsbackup-ivssexaminewritermetadataex - [PInvokeData("vsbackup.h", MSDNShortId = "NL:vsbackup.IVssExamineWriterMetadataEx")] - [ComVisible(true), Guid("0c0e5ec0-ca44-472b-b702-e652db1c0451"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - private interface IVssExamineWriterMetadataEx : IVssExamineWriterMetadata - { - /// - /// The GetIdentityEx method obtains the writer instance name and other basic information about a specific writer instance. - /// - /// Globally unique identifier (GUID) of the writer instance. - /// GUID of the writer class. - /// Pointer to a string specifying the name of the writer. - /// Pointer to a string specifying the writer instance name. - /// - /// Pointer to a VSS_USAGE_TYPE enumeration value indicating how the data managed by the writer is used on the host system. - /// - /// Pointer to a VSS_SOURCE_TYPE enumeration value indicating the type of data managed by the writer. - /// - /// The following are the valid return codes for this method. - /// - /// - /// Value - /// Meaning - /// - /// - /// S_OK - /// Successfully returned the identity information. - /// - /// - /// E_INVALIDARG - /// One of the parameter values is not valid. - /// - /// - /// E_OUTOFMEMORY - /// The caller is out of memory or other system resources. - /// - /// - /// 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_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. - /// - /// - /// - /// - /// - /// This method is identical to the IVssExamineWriterMetadata::GetIdentity method except for the pbstrInstanceName parameter. - /// The pbstrInstanceName parameter is the writer instance name that was specified during writer initialization by CVssWriter::Initialize. - /// - /// The writer instance name is useful for writers that support running multiple writer instances with the same writer class ID - /// on a single computer. The writer instance name can be used to identify the specific instance. Therefore, the writer must - /// make the instance name unique within the writer class. Also, the writer instance name is expected to persist between backup - /// and restore, and it is used by VSS to correctly restore multiple-instance writers. - /// - /// The caller must free the memory held by the pbstrWriterName and pbstrInstanceName parameters by calling SysFreeString. - /// - /// An IVssExamineWriterMetadataEx interface might be from stored writer state information (created by a call to - /// CreateVssExamineWriterMetadata). If this is the case, then the following are true: - /// - /// - /// - /// pidInstance may not mean anything in terms of live writers. - /// - /// - /// If pidWriter does not match the writer class of any live writer, a requester should not use that writer's components. - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadataex-getidentityex HRESULT - // GetIdentityEx( [out] VSS_ID *pidInstance, [out] VSS_ID *pidWriter, [out] BSTR *pbstrWriterName, [out] BSTR - // *pbstrInstanceName, [out] VSS_USAGE_TYPE *pUsage, [out] VSS_SOURCE_TYPE *pSource ); - [PreserveSig] - HRESULT GetIdentityEx(out Guid pidInstance, out Guid pidWriter, [MarshalAs(UnmanagedType.BStr)] out string pbstrWriterName, - [MarshalAs(UnmanagedType.BStr)] out string pbstrInstanceName, out VSS_USAGE_TYPE pUsage, out VSS_SOURCE_TYPE pSource); - } - - /// - /// Defines methods to retrieve version information and other basic information for a specific writer instance. - /// - /// Your writer application should implement this interface only if you need to use the GetExcludeFromSnapshotCount, - /// GetExcludeFromSnapshotFile, and GetVersion methods. Otherwise, your writer application should implement the - /// IVssExamineWriterMetadataEx interface or the IVssExamineWriterMetadata interface instead. - /// - /// The IVssExamineWriterMetadataEx2 interface is a C++ (not COM) interface. - /// - /// To obtain an instance of the IVssExamineWriterMetadataEx2 interface, call the QueryInterface method of the - /// IVssExamineWriterMetadata interface, and pass the IID_IVssExamineWriterMetadataEx2 constant as the interface identifier - /// (IID) parameter. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nl-vsbackup-ivssexaminewritermetadataex2 - [PInvokeData("vsbackup.h", MSDNShortId = "NL:vsbackup.IVssExamineWriterMetadataEx2")] - [ComVisible(true), Guid("ce115780-a611-431b-b57f-c38303ab6aee"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - private interface IVssExamineWriterMetadataEx2 : IVssExamineWriterMetadataEx - { - /// Obtains the number of file sets that have been explicitly excluded from a given shadow copy. - /// A pointer to the number of file sets explicitly excluded from the shadow copy. - /// - /// The following are the valid return codes for this method. - /// - /// - /// Return code - /// Description - /// - /// - /// S_OK - /// The number of file sets was successfully returned. - /// - /// - /// E_INVALIDARG - /// The pcExcludedFromSnapshot parameter was NULL. - /// - /// - /// E_OUTOFMEMORY - /// The caller is out of memory or other system resources. - /// - /// - /// 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. - /// - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadataex2-getexcludefromsnapshotcount - // HRESULT GetExcludeFromSnapshotCount( [out] UINT *pcExcludedFromSnapshot ); - [PreserveSig] - HRESULT GetExcludeFromSnapshotCount(out uint pcExcludedFromSnapshot); - - /// Obtains information about file sets that have been explicitly excluded from a given shadow copy. - /// - /// An index for an excluded file set. The value of this parameter is an integer from 0 to n–1 inclusive, where n is the total - /// number of file sets explicitly excluded from a given shadow copy. The value of n is returned by the - /// IVssExamineWriterMetadataEx2::GetExcludeFromSnapshotCount method. - /// - /// A doubly indirect pointer to an IVssWMFiledesc object containing the file element information. - /// - /// The following are the valid return codes for this method. - /// - /// - /// Value - /// Meaning - /// - /// - /// S_OK - /// The pointer to an IVssWMFiledesc interface was successfully returned. - /// - /// - /// E_INVALIDARG - /// One of the parameter values is not valid. - /// - /// - /// E_OUTOFMEMORY - /// The caller is out of memory or other system resources. - /// - /// - /// 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. - /// - /// - /// - /// - /// - /// - /// The caller is responsible for calling the IUnknown::Release method to release the resources of the returned IVssWMFiledesc object. - /// - /// - /// The GetExcludeFromSnapshotFile method is intended to report information about file sets excluded from a shadow copy. - /// Requesters should not exclude files from backup based on the information returned by this method. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadataex2-getexcludefromsnapshotfile - // HRESULT GetExcludeFromSnapshotFile( [in] UINT iFile, [out] IVssWMFiledesc **ppFiledesc ); - [PreserveSig] - HRESULT GetExcludeFromSnapshotFile(uint iFile, out IVssWMFiledesc ppFiledesc); - - /// Obtains the version information for a writer application. - /// A pointer to the major version of the writer application. - /// A pointer to the minor version of the writer application. - /// - /// The following are the valid return codes for this method. - /// - /// - /// Value - /// Meaning - /// - /// - /// S_OK - /// The writer version information was successfully returned. - /// - /// - /// E_INVALIDARG - /// One of the parameter values is not valid. - /// - /// - /// E_OUTOFMEMORY - /// The caller is out of memory or other system resources. - /// - /// - /// 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. - /// - /// - /// - /// - /// - /// The GetVersion method returns nonzero results only if the writer was initialized by calling the - /// CVssWriterEx::InitializeEx method and explicit version information was specified. If the writer is initialized by calling - /// the CVssWriter::Initialize method, or if no version information was specified in the call to the - /// CVssWriterEx::InitializeEx method, the GetVersion method returns zero in the pdwMajorVersion and - /// pdwMinorVersion parameters. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadataex2-getversion HRESULT - // GetVersion( [out] DWORD *pdwMajorVersion, [out] DWORD *pdwMinorVersion ); - [PreserveSig] - HRESULT GetVersion(out uint pdwMajorVersion, out uint pdwMinorVersion); - } - - /// - /// - /// The IVssWMComponent is a C++ (not COM) interface that allows access to component information stored in a Writer Metadata Document. - /// - /// Instances of IVssWMComponent are obtained by calling IVssExamineWriterMetadata::GetComponent. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nl-vsbackup-ivsswmcomponent - [PInvokeData("vsbackup.h", MSDNShortId = "NL:vsbackup.IVssWMComponent")] - [ComVisible(true)] - private interface IVssWMComponent - { - /// The FreeComponentInfo method deallocates system resources devoted to the specified component information. - /// Pointer to a VSS_COMPONENTINFO structure that contains the component information. - /// - /// The following are the valid return codes for this method. - /// - /// - /// Value - /// Meaning - /// - /// - /// S_OK - /// Successfully freed the component information data. - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivsswmcomponent-freecomponentinfo HRESULT - // FreeComponentInfo( [out] PVSSCOMPONENTINFO pInfo ); - [PreserveSig] - HRESULT FreeComponentInfo([In] IntPtr pInfo); - - /// The GetComponentInfo method obtains basic information about the specified writer metadata component. - /// - /// Doubly indirect pointer to a structure containing the returned component information. - /// - /// - /// The following are the valid return codes for this method. - /// - /// - /// Value - /// Meaning - /// - /// - /// S_OK - /// Successfully returned the component information. - /// - /// - /// E_INVALIDARG - /// One of the parameter values is not valid. - /// - /// - /// E_OUTOFMEMORY - /// The caller is out of memory or other system resources. - /// - /// - /// 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_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. - /// - /// - /// - /// - /// The caller is responsible for freeing the returned VSS_COMPONENTINFO structure by calling IVssWMComponent::FreeComponentInfo. - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivsswmcomponent-getcomponentinfo HRESULT - // GetComponentInfo( [out] PVSSCOMPONENTINFO *ppInfo ); - [PInvokeData("vsbackup.h", MSDNShortId = "NF:vsbackup.IVssWMComponent.GetComponentInfo")] - [PreserveSig] - HRESULT GetComponentInfo(out IntPtr ppInfo); - - /// - /// The GetDatabaseFile method obtains an IVssWMFiledesc object containing information about the specified database - /// backup component file. - /// - /// - /// Offset between 0 and n-1, where n is the number of database files as specified by the cDatabases member of the - /// VSS_COMPONENTINFO object returned by IVssWMComponent::GetComponentInfo. - /// - /// Doubly indirect pointer to an IVssWMFiledesc object containing the returned file descriptor information. - /// - /// The following are the valid return codes for this method. - /// - /// - /// Value - /// Meaning - /// - /// - /// S_OK - /// Successfully returned a pointer to an instance of the IVssWMFiledesc interface. - /// - /// - /// E_INVALIDARG - /// One of the parameter values is not valid. - /// - /// - /// E_OUTOFMEMORY - /// The caller is out of memory or other system resources. - /// - /// - /// 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 specified database file does not exist. - /// - /// - /// 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. - /// - /// - /// - /// - /// - /// The caller is responsible for calling IUnknown::Release to release system resources held by the returned IVssWMFiledesc object. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivsswmcomponent-getdatabasefile HRESULT - // GetDatabaseFile( [in] UINT iDBFile, [out] IVssWMFiledesc **ppFiledesc ); - [PreserveSig] - HRESULT GetDatabaseFile(uint iDBFile, out IVssWMFiledesc ppFiledesc); - - /// - /// The GetDatabaseLogFile method obtains a file descriptor for the log file associated with the specified database - /// backup component. - /// - /// - /// Offset between 0 and n-1, where n is the number of database log files as specified by the cLogFiles member of the - /// VSS_COMPONENTINFO object returned by IVssWMComponent::GetComponentInfo. - /// - /// Doubly indirect pointer to an IVssWMFiledesc object containing the returned file descriptor information. - /// - /// The following are the valid return codes for this method. - /// - /// - /// Value - /// Meaning - /// - /// - /// S_OK - /// Successfully returned a pointer to an instance of the IVssWMFiledesc interface. - /// - /// - /// E_INVALIDARG - /// One of the parameter values is not valid. - /// - /// - /// E_OUTOFMEMORY - /// The caller is out of memory or other system resources. - /// - /// - /// 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 specified database log file does not exist. - /// - /// - /// 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. - /// - /// - /// - /// - /// - /// The caller is responsible for calling IUnknown::Release to release system resources held by the returned IVssWMFiledesc object. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivsswmcomponent-getdatabaselogfile HRESULT - // GetDatabaseLogFile( [in] UINT iDbLogFile, [out] IVssWMFiledesc **ppFiledesc ); - [PreserveSig] - HRESULT GetDatabaseLogFile(uint iDbLogFile, out IVssWMFiledesc ppFiledesc); - - /// - /// The GetDependency method returns an instance of the IVssWMDependency interface containing accessors for obtaining - /// information about explicit writer-component dependencies of one of the current components. - /// - /// - /// Offset between 0 and n-1, where n is the number of dependencies associated with this component as specified by the - /// cDependencies member of the VSS_COMPONENTINFO object returned by IVssWMComponent::GetComponentInfo. - /// - /// Doubly indirect pointer to an instance of the IVssWMDependency interface. - /// - /// This method can return one of these values. - /// - /// - /// Value - /// Meaning - /// - /// - /// S_OK - /// The operation was successful. - /// - /// - /// E_INVALIDARG - /// One of the parameter values is not valid. - /// - /// - /// E_OUTOFMEMORY - /// The caller is out of memory or other system resources. - /// - /// - /// 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 specified by the index iDependency does not exist. - /// - /// - /// 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. - /// - /// - /// - /// - /// - /// The caller is responsible for calling IUnknown::Release to release system resources held by the returned IVssWMFiledesc object. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivsswmcomponent-getdependency HRESULT GetDependency( - // [in] UINT iDependency, [out] IVssWMDependency **ppDependency ); - [PreserveSig] - HRESULT GetDependency(uint iDependency, out IVssWMDependency ppDependency); - - /// The GetFile method obtains a file descriptor associated with a file group. - /// - /// Offset between 0 and n-1, where n is the number of files in the file group as specified by the cFileCount member of - /// the VSS_COMPONENTINFO object returned by IVssWMComponent::GetComponentInfo. - /// - /// Doubly indirect pointer to a IVssWMFiledesc object containing the returned file descriptor information. - /// - /// The following are the valid return codes for this method. - /// - /// - /// Value - /// Meaning - /// - /// - /// S_OK - /// Successfully returned a pointer to an instance of the IVssWMFiledesc interface. - /// - /// - /// E_INVALIDARG - /// One of the parameter values is not valid. - /// - /// - /// E_OUTOFMEMORY - /// The caller is out of memory or other system resources. - /// - /// - /// 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 specified file does not exist. - /// - /// - /// 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. - /// - /// - /// - /// - /// - /// The caller is responsible for calling IUnknown::Release to release system resources held by the returned IVssWMFiledesc object. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivsswmcomponent-getfile HRESULT GetFile( [in] UINT - // iFile, [out] IVssWMFiledesc **ppFiledesc ); - [PreserveSig] - HRESULT GetFile(uint iFile, out IVssWMFiledesc ppFiledesc); - } - - /// - /// - /// The CreateVssBackupComponents function creates an IVssBackupComponents interface object and returns a pointer to it. - /// - /// - /// Doubly indirect pointer to the created IVssBackupComponents interface object. - /// - /// - /// The return values listed here are in addition to the normal COM HRESULT s that may be returned at any time from the function. - /// + /// The address of a caller-allocated variable that receives the HRESULT failure code that was returned by the writer. + /// The following are the supported values for pHrResultFailure. /// /// /// Value @@ -3498,47 +27,392 @@ namespace Vanara.PInvoke /// /// /// S_OK - /// Successfully returned a pointer to an IVssBackupComponents interface. + /// The writer was successful. /// /// - /// E_ACCESSDENIED - /// The caller does not have sufficient backup privileges or is not an administrator. + /// VSS_E_WRITERERROR_INCONSISTENTSNAPSHOT + /// The shadow copy contains only a subset of the volumes needed by the writer to correctly back up the application component. /// /// - /// E_INVALIDARG - /// One of the parameters is not valid. - /// - /// - /// E_OUTOFMEMORY - /// Out of memory or other system resources. - /// - /// - /// VSS_E_UNEXPECTED + /// VSS_E_WRITERERROR_OUTOFRESOURCES /// - /// 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. + /// The writer ran out of memory or other system resources. The recommended way to handle this error code is to wait ten minutes and + /// then repeat the operation, up to three times. + /// + /// + /// + /// VSS_E_WRITERERROR_TIMEOUT + /// + /// The writer operation failed because of a time-out between the Freeze and Thaw events. The recommended way to handle this error + /// code is to wait ten minutes and then repeat the operation, up to three times. + /// + /// + /// + /// VSS_E_WRITERERROR_RETRYABLE + /// + /// The writer failed due to an error that would likely not occur if the entire backup, restore, or shadow copy creation process was + /// restarted. The recommended way to handle this error code is to wait ten minutes and then repeat the operation, up to three times. + /// + /// + /// + /// VSS_E_WRITERERROR_NONRETRYABLE + /// + /// The writer operation failed because of an error that might recur if another shadow copy is created. For more information, see + /// Event and Error Handling Under VSS. + /// + /// + /// + /// VSS_E_WRITER_NOT_RESPONDING + /// The writer is not responding. + /// + /// + /// VSS_E_WRITER_STATUS_NOT_AVAILABLE + /// + /// The writer status is not available for one or more writers. A writer may have reached the maximum number of available backup and + /// restore sessions. Windows Vista, Windows Server 2003 and Windows XP: This value is not supported. /// /// /// + /// + public HRESULT phResultFailure; + + /// + /// The address of a caller-allocated variable that receives the return code that the writer passed for the hrApplication parameter + /// of the CVssWriterEx2::SetWriterFailureEx method. This parameter is optional and can be NULL. + /// + public HRESULT phrApplication; + + /// + /// The address of a variable that receives the application failure message that the writer passed for the wszApplicationMessage + /// parameter of the SetWriterFailureEx method. This parameter is optional and can be NULL. + /// + public string pbstrApplicationMessage; + } + + /// + /// + /// The IVssBackupComponents interface is used by a requester to poll writers about file status and to run backup/restore operations. + /// + /// Applications obtain an instance of the IVssBackupComponents interface by calling CreateVssBackupComponents. + /// An IVssBackupComponents object can be used for only a single backup, restore, or Query operation. + /// + /// After the backup, restore, or Query operation has either successfully finished or been explicitly terminated, a requester must + /// release the IVssBackupComponents object by calling IVssBackupComponents::Release. An IVssBackupComponents + /// object must not be reused. For example, you cannot perform a backup or restore operation with the same IVssBackupComponents + /// object that you have already used for a Query operation. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nl-vsbackup-ivssbackupcomponents + [PInvokeData("vsbackup.h", MSDNShortId = "NL:vsbackup.IVssBackupComponents")] + //[ComImport, Guid("665c1d5f-c218-414d-a05d-7fef5f9d5c86"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IVssBackupComponents + { + /// + /// The GetWriterComponents method is used to return information about those components of a given writer that have been + /// stored in a requester's Backup Components Document. + /// + /// + /// The index of the writer being queried. It is a number between 0 and n-1, where n is the value returned by IVssBackupComponents::GetWriterComponentsCount. + /// + /// An IVssWriterComponentsExt interface object that will receive the returned component information. + /// + /// The caller of this method must call IUnknown::Release when it finishes accessing the component information. + /// + /// GetWriterComponents retrieves component information for a component stored in the Backup Components Document by earlier + /// calls to IVssBackupComponents::AddComponent. + /// + /// + /// The information in the components stored in the Backup Components Document is not static. If a writer updates a component during + /// a restore, that change will be reflected in the component retrieved by GetWriterComponents. This is in contrast with + /// component information found in the IVssWMComponent object returned by IVssExamineWriterMetadata::GetComponent. That information + /// is read-only and comes from the Writer Metadata Document of a writer process. + /// + /// + /// The IVssWriterComponentsExt interface pointer that is returned in the pWriterComponents parameter should not be cached, because + /// the following IVssBackupComponents methods cause the interface pointer that is returned by GetWriterComponents to be no + /// longer valid: + /// + /// + /// IVssBackupComponents::PrepareForBackup IVssBackupComponents::DoSnapshotSet IVssBackupComponents::BackupComplete + /// IVssBackupComponents::PreRestore IVssBackupComponents::PostRestore If you call one of these methods after you have retrieved an + /// IVssWriterComponentsExt interface pointer by calling GetWriterComponents, you cannot reuse that pointer, because it is no + /// longer valid. Instead, you must call GetWriterComponents again to retrieve a new IVssWriterComponentsExt interface pointer. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-getwritercomponents HRESULT + // GetWriterComponents( [in] UINT iWriter, [out] IVssWriterComponentsExt **ppWriter ); + IReadOnlyList WriterComponents { get; } + + /// The InitializeForBackup method initializes the backup components metadata in preparation for backup. + /// + /// Optional. During imports of transported shadow copies, this parameter must be the original document generated when creating the + /// saved shadow copy and saved using IVssBackupComponents::SaveAsXML. + /// + /// + /// + /// The XML document supplied to this method initializes the IVssBackupComponents object with metadata previously stored by a call + /// to IVssBackupComponents::SaveAsXML. Users should not tamper with this metadata document. + /// + /// + /// For more information on how to use InitializeForBackup with transportable shadow copies, see Importing Transportable + /// Shadow Copied Volumes. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-initializeforbackup HRESULT + // InitializeForBackup( [in] BSTR bstrXML ); + void InitializeForBackup([Optional] string bstrXML); + + /// The SetBackupState method defines an overall configuration for a backup operation. + /// + /// Indicates whether a backup or restore operation will be in component mode. + /// + /// Operation in component mode supports selectively backing up designated individual components (which can allow their exclusion), + /// or only supports backing up all files and components on a volume. + /// + /// The Boolean is true if the operation will be conducted in component mode and false if not. + /// + /// Indicates whether a bootable system state backup is being performed. + /// A VSS_BACKUP_TYPE enumeration value indicating the type of backup to be performed. + /// + /// Optional. If the value of this parameter is true, partial file support is enabled. The default value for this argument is false. + /// + /// Applications must call SetBackupState prior to calling IVssBackupComponents::PrepareForBackup. + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-setbackupstate HRESULT + // SetBackupState( [in] bool bSelectComponents, [in] bool bBackupBootableSystemState, [in] VSS_BACKUP_TYPE backupType, [in] bool + // bPartialFileSupport ); + void SetBackupState(bool bSelectComponents, bool bBackupBootableSystemState, VSS_BACKUP_TYPE backupType, bool bPartialFileSupport = false); + + /// + /// The InitializeForRestore method initializes the IVssBackupComponents interface in preparation for a restore operation. + /// + /// XML string containing the Backup Components Document generated by a backup operation and saved by IVssBackupComponents::SaveAsXML. + /// + /// The XML document supplied to this method initializes the IVssBackupComponents object with metadata previously stored by a call + /// to IVssBackupComponents::SaveAsXML. Users should not tamper with this metadata document. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-initializeforrestore HRESULT + // InitializeForRestore( [in] BSTR bstrXML ); + void InitializeForRestore([Optional]string bstrXML); + + /// The SetRestoreState method defines an overall configuration for a restore operation. + /// A VSS_RESTORE_TYPE enumeration value indicating the type of restore to be performed. + /// + /// + /// Typically, most restore operations will not need to override the default restore type (VSS_RTYPE_UNDEFINED). Writers should + /// treat this restore type as if it were VSS_RTYPE_BY_COPY. + /// + /// If applications need to call SetRestoreState, it should be called prior to calling IVssBackupComponents::PreRestore. + /// If SetRestoreState is not called prior to IVssBackupComponents::PreRestore, the default restore state () is used. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-setrestorestate HRESULT + // SetRestoreState( [in] VSS_RESTORE_TYPE restoreType ); + void SetRestoreState(VSS_RESTORE_TYPE restoreType); + + /// + /// The GatherWriterMetadata method prompts each writer to send the metadata they have collected. The method will generate an + /// Identify event to communicate with writers. + /// + /// An IVssAsync object containing the writer metadata. + /// + /// The caller is responsible for releasing the IVssAsync interface. + /// GatherWriterMetadata should be called only once during the lifetime of a given IVssBackupComponents object. + /// + /// GatherWriterMetadata generates an Identify event, which is handled by each instance of each writer through the + /// CVssWriter::OnIdentify method, which is used to fill the Writer Metadata Document. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-gatherwritermetadata HRESULT + // GatherWriterMetadata( [out] IVssAsync **pAsync ); + IVssAsync GatherWriterMetadata(); + + /// The GetWriterMetadata method returns the metadata for a specific writer running on the system. + /// + /// Index of the writer whose metadata is to be retrieved. The value of this parameter is an integer from 0 to n–1 inclusive, where + /// n is the total number of writers on the current system. The value of n is returned by IVssBackupComponents::GetWriterMetadataCount. + /// + /// Pointer to the instance identifier of the writer that collected the metadata. + /// Doubly indirect pointer to the instance of the IVssExamineWriterMetadata object that contains the returned metadata. + /// + /// + /// A requester must call the asynchronous operation IVssBackupComponents::GatherWriterMetadata and wait for it to complete prior to + /// calling GetWriterMetadata. + /// + /// + /// Although IVssBackupComponents::GatherWriterMetadata must be called prior to either a restore or backup operation, + /// GetWriterMetadata is not typically called for restores. + /// + /// + /// Component information retrieved (during backup operations) using IVssExamineWriterMetadata::GetComponent, where the + /// IVssExamineWriterMetadata interface has been returned by GetWriterMetadata, comes from the Writer Metadata Document of a + /// live writer process. + /// + /// + /// This is in contrast to the information returned by GetWriterComponents (during restore operations), which was stored in the + /// Backup Components Document by calls to AddComponent. + /// + /// When the caller of this method is finished accessing the metadata, it must call IUnknown::Release. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-getwritermetadata HRESULT + // GetWriterMetadata( [in] UINT iWriter, [out] VSS_ID *pidInstance, [out] IVssExamineWriterMetadata **ppMetadata ); + IReadOnlyList WriterMetadata { get; } + + /// + /// The FreeWriterMetadata method frees system resources allocated when IVssBackupComponents::GatherWriterMetadata was called. + /// + /// + /// + /// This method should never be called prior to the completion of IVssBackupComponents::GatherWriterMetadata. The result of calling + /// the method prior to completion of the metadata gather is undefined. + /// + /// + /// Once writer metadata has been freed, it cannot be recovered by the current instance of the IVssBackupComponents interface. It + /// will be necessary to create a new instance of IVssBackupComponents, and call the + /// IVssBackupComponents::GatherWriterMetadata method again. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-freewritermetadata HRESULT FreeWriterMetadata(); + void FreeWriterMetadata(); + + /// + /// The AddComponent method is used to explicitly add to the backup set in the Backup Components Document all required + /// components (nonselectable for backup components without a selectable for backup ancestor), and such optional (selectable for + /// backup) components as the requester considers necessary. Members of component sets (components with a selectable for backup + /// ancestor) are implicitly included in the backup set, but are not explicitly added to the Backup Components Document. + /// + /// Identifies a specific instance of a writer. + /// Writer class identifier. + /// + /// Identifies the type of the component. Refer to the documentation for VSS_COMPONENT_TYPE for permitted input values. + /// + /// + /// + /// String containing the logical path of the selectable for backup component. For more information, see Logical Pathing of Components. + /// + /// A logical path is not required when adding a component. Therefore, the value of this parameter can be . + /// There are no restrictions on the characters that can appear in a non- logical path. + /// + /// + /// String containing the name of the selectable for backup component. + /// The value of this parameter cannot be . + /// There are no restrictions on the characters that can appear in a non- logical path. + /// + /// + /// The AddComponent method has meaning only if the backup operation takes place in component mode. + /// Only these kinds of components should be added to the Backup Components Document using AddComponent. + /// + /// + /// Components that are selectable for backup (see selectability for backup). + /// + /// + /// Nonselectable-for-backup components with no selectable-for-backup ancestors. + /// + /// + /// + /// Nonselectable for backup components that have a selectable for backup ancestor in the hierarchy of their logical paths are part + /// of a component set defined by the selectable for backup ancestor. These components are implicitly added to the Backup Components + /// Document when the ancestor is added and should never be explicitly added to a requester's Backup Components Document by using + /// AddComponent.The result of doing so is undefined (see Working with Selectability and Logical Paths). + /// + /// + /// Selectable for backup components with selectable for backup ancestors are also subcomponents in a component set. They can be + /// implicitly selected if their ancestor is selected (in which case they are not added to the Backup Components Document using + /// AddComponent), or they can be explicitly selected using AddComponent. + /// + /// + /// The combination of logical path and name for each component of a given instance of a given class of writer must be unique. + /// Attempting to call AddComponent twice with the same values of wszLogicalPath and wszComponentName results in a + /// VSS_E_OBJECT_ALREADY_EXISTS error. + /// + /// + /// The distinction between the instanceId and the writerID is necessary because it is possible to run multiple copies for the same writer. + /// + /// A writer's class identifier and instance can be found by calling IVssExamineWriterMetadata::GetIdentity. + /// + /// Before it calls AddComponent, a requester must have been initialized for backup by calling + /// IVssBackupComponents::InitializeForBackup and IVssBackupComponents::GatherWriterMetadata. See Overview of Backup Initialization. + /// + /// + /// The requester must call AddComponent to add the required components to the shadow copy before calling + /// IVssBackupComponents::DoSnapshotSet to create the shadow copy. See Overview of the Backup Discovery Phase and Overview of + /// Pre-Backup Tasks. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-addcomponent HRESULT AddComponent( + // [in] VSS_ID instanceId, [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] LPCWSTR + // wszComponentName ); + void AddComponent(Guid instanceId, Guid writerId, VSS_COMPONENT_TYPE ct, [Optional] string wszLogicalPath, string wszComponentName); + + /// + /// The PrepareForBackup method will cause VSS to generate a PrepareForBackup event, signaling writers to prepare for an + /// upcoming backup operation. This makes a requester's Backup Components Document available to writers. + /// + /// + /// Doubly indirect pointer to an instance of the IVssAsync interface that is used to determine when the asynchronous operation is complete. /// /// - /// The calling application is responsible for calling IUnknown::Release to release the resources held by the returned - /// IVssBackupComponents when it is no longer needed. + /// + /// PrepareForBackup generates a PrepareForBackup event, which is handled by each instance of each writer through the + /// CVssWriter::OnPrepareBackup method. + /// + /// Before PrepareForBackup can be called, IVssBackupComponents::SetBackupState must be called. + /// + /// The Backup Components Document can still be modified by writers in their PrepareForBackup event handler + /// (CVssWriter::OnPrepareBackup), and afterward until the generation of a BackupComplete event. + /// + /// The caller is responsible for releasing the IVssAsync interface. /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-createvssbackupcomponents HRESULT - // CreateVssBackupComponents( [out] IVssBackupComponents **ppBackup); - [DllImport(Lib_VssApi, SetLastError = false, CharSet = CharSet.Unicode, EntryPoint = "CreateVssBackupComponentsInternal")] - [PInvokeData("vsbackup.h", MSDNShortId = "NF:vsbackup.CreateVssBackupComponents")] - public static extern HRESULT CreateVssBackupComponents(out IVssBackupComponents ppBackup); + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-prepareforbackup HRESULT + // PrepareForBackup( [out] IVssAsync **ppAsync ); + IVssAsync PrepareForBackup(); - /// The CreateVssExamineWriterMetadata function creates an IVssExamineWriterMetadata object. - /// - /// An XML string containing a Writer Metadata Document with which to initialize the returned IVssExamineWriterMetadata object. + /// + /// The AbortBackup method notifies VSS that a backup operation was terminated. + /// + /// This method must be called if a backup operation terminates after the creation of a shadow copy set with + /// IVssBackupComponents::StartSnapshotSet and before IVssBackupComponents::DoSnapshotSet returns. + /// + /// If AbortBackup is called and no shadow copy or backup operations are underway, it is ignored. + /// + /// + /// AbortBackup generates an Abort event, which is handled by each instance of each writer through the CVssWriter::OnAbort method. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-abortbackup HRESULT AbortBackup(); + void AbortBackup(); + + /// The GatherWriterStatus method prompts each writer to send a status message. + /// Doubly indirect pointer to an IVssAsync object containing the writer status data. + /// + /// The caller of this method should also call IVssBackupComponents::FreeWriterStatus after receiving the status of each writer. + /// + /// After calling BackupComplete, requesters must call GatherWriterStatus to cause the writer session to be set to a + /// completed state. + /// + /// Note This is only necessary on Windows Server 2008 with Service Pack 2 (SP2) and earlier. + /// The CVssWriter class handles the status message sent by each writer. + /// The caller is responsible for releasing the IVssAsync interface. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-gatherwriterstatus HRESULT + // GatherWriterStatus( [out] IVssAsync **pAsync ); + IVssAsync GatherWriterStatus(); + + /// The FreeWriterStatus method frees system resources allocated during the call to IVssBackupComponents::GatherWriterStatus. + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-freewriterstatus HRESULT FreeWriterStatus(); + void FreeWriterStatus(); + + /// The GetWriterStatus method returns the status of the specified writer. + /// + /// Index of the writer whose metadata is to be retrieved. The value of this parameter is an integer from 0 to n–1 inclusive, where + /// n is the total number of writers on the current system. The value of n is returned by IVssBackupComponents::GetWriterStatusCount. /// - /// A variable that receives an IVssExamineWriterMetadata interface pointer to the object. - /// - /// The return values listed here are in addition to the normal COM HRESULTs that may be returned at any time from the function. + /// The address of a caller-allocated variable that receives the instance identifier of the writer. + /// The address of a caller-allocated variable that receives the identifier for the writer class. + /// + /// The address of a caller-allocated variable that receives a string containing the name of the specified writer. + /// + /// The address of a caller-allocated variable that receives a VSS_WRITER_STATE enumeration value. + /// + /// The address of a caller-allocated variable that receives the HRESULT failure code that was returned by the writer. + /// The following are the supported values for pHrResultFailure. /// /// /// Value @@ -3546,25 +420,170 @@ namespace Vanara.PInvoke /// /// /// S_OK - /// Successfully returned a pointer to an IVssExamineWriterMetadata interface. + /// The writer was successful. /// /// - /// E_ACCESSDENIED - /// The caller does not have sufficient backup privileges or is not an administrator. + /// VSS_E_WRITERERROR_INCONSISTENTSNAPSHOT + /// The shadow copy contains only a subset of the volumes needed by the writer to correctly back up the application component. + /// + /// + /// VSS_E_WRITERERROR_OUTOFRESOURCES + /// + /// The writer ran out of memory or other system resources. The recommended way to handle this error code is to wait ten minutes and + /// then repeat the operation, up to three times. + /// + /// + /// + /// VSS_E_WRITERERROR_TIMEOUT + /// + /// The writer operation failed because of a time-out between the Freeze and Thaw events. The recommended way to handle this error + /// code is to wait ten minutes and then repeat the operation, up to three times. + /// + /// + /// + /// VSS_E_WRITERERROR_RETRYABLE + /// + /// The writer failed due to an error that would likely not occur if the entire backup, restore, or shadow copy creation process was + /// restarted. The recommended way to handle this error code is to wait ten minutes and then repeat the operation, up to three times. + /// + /// + /// + /// VSS_E_WRITERERROR_NONRETRYABLE + /// + /// The writer operation failed because of an error that might recur if another shadow copy is created. For more information, see + /// Event and Error Handling Under VSS. + /// + /// + /// + /// VSS_E_WRITER_NOT_RESPONDING + /// The writer is not responding. + /// + /// + /// VSS_E_WRITER_STATUS_NOT_AVAILABLE + /// + /// The writer status is not available for one or more writers. A writer may have reached the maximum number of available backup and + /// restore sessions. Windows Vista, Windows Server 2003 and Windows XP: This value is not supported. + /// + /// + /// + /// + /// + /// + /// A requester must call the asynchronous operation IVssBackupComponents::GatherWriterStatus and wait for it to complete prior to + /// calling GetWriterStatus. + /// + /// + /// When the caller has finished accessing the status information returned by this method, it should call SysFreeString to free the + /// memory held by the pbstrWriter parameter. + /// + /// + /// The VSS_E_WRITERERROR_XXX values returned in the pHrResultFailure parameter are generated by writers. + /// VSS_E_WRITER_NOT_RESPONDING and VSS_E_WRITER_STATUS_NOT_AVAILABLE are generated by VSS. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-getwriterstatus HRESULT + // GetWriterStatus( [in] UINT iWriter, [out] VSS_ID *pidInstance, [out] VSS_ID *pidWriter, [out] BSTR *pbstrWriter, [out] + // VSS_WRITER_STATE *pnStatus, [out] HRESULT *phResultFailure ); + IReadOnlyList WriterStatus { get; } + + /// + /// The SetBackupSucceeded method indicates whether the backup of the specified component of a specific writer was successful. + /// + /// Globally unique identifier (GUID) of the writer instance. + /// Globally unique identifier (GUID) of the writer class. + /// Type of the component. See VSS_COMPONENT_TYPE for the possible values. + /// + /// String containing the logical path of the component. + /// 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 . + /// There are no restrictions on the characters that can appear in a non- logical path. + /// + /// + /// String containing the name of the component. + /// + /// The string cannot be and should contain the same component name as was used when the component was added + /// to the backup set using IVssBackupComponents::AddComponent. + /// + /// + /// Set this parameter to true if the component was successfully backed up, or false otherwise. + /// + /// + /// When working in component mode (when IVssBackupComponents::SetBackupState is called with its select components argument set to + /// true), writers check the state of each components backup using IVssComponent::GetBackupSucceeded. Therefore, a + /// well-behaved backup application (requester) must call SetBackupSucceeded after each component has been processed and + /// prior to calling IVssBackupComponents::BackupComplete. + /// + /// + /// Do not call this method if the call to IVssBackupComponents::DoSnapshotSet failed. For more information about how requesters use + /// DoSnapshotSet, SetBackupSucceeded, and BackupComplete in a backup operation, see Overview of Pre-Backup Tasks and + /// Overview of Actual Backup Of Files. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-setbackupsucceeded HRESULT + // SetBackupSucceeded( [in] VSS_ID instanceId, [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] + // LPCWSTR wszComponentName, [in] bool bSucceded ); + void SetBackupSucceeded(Guid instanceId, Guid writerId, VSS_COMPONENT_TYPE ct, [Optional] string wszLogicalPath, + string wszComponentName, bool bSucceded); + + /// The SetBackupOptions method sets a string of private, or writer-dependent, backup parameters for a component. + /// Writer identifier. + /// Type of the component. See VSS_COMPONENT_TYPE for the possible values. + /// + /// String containing the logical path of the component. + /// 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 . + /// There are no restrictions on the characters that can appear in a non- logical path. + /// + /// + /// String containing the name of the component. + /// + /// The string containing the name cannot be and should contain the same component name as was used when the + /// component was added to the backup set using IVssBackupComponents::AddComponent. + /// + /// + /// String containing the backup parameters to be set. + /// + /// The following are the valid return codes for this method. + /// + /// + /// Value + /// Meaning + /// + /// + /// S_OK + /// Successfully set the backup options. /// /// /// E_INVALIDARG - /// One of the parameters is not valid. + /// One of the parameter values is not valid. /// /// /// E_OUTOFMEMORY - /// Out of memory or other system resources. + /// The caller is out of memory or other system resources. + /// + /// + /// VSS_E_BAD_STATE + /// + /// 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. + /// + /// + /// + /// VSS_E_OBJECT_NOT_FOUND + /// The backup component does not exist. /// /// /// VSS_E_INVALID_XML_DOCUMENT /// - /// The XML document passed in the bstrXML parameter is not valid—that is, either it is not a correctly formed XML string or it does - /// not match the schema. + /// The XML document is not valid. Check the event log for details. For more information, see Event and Error Handling Under VSS. /// /// /// @@ -3579,37 +598,1958 @@ namespace Vanara.PInvoke /// /// /// - /// To save a copy of a writer’s Writer Metadata Document into an XML string to pass in the bstrXML parameter, use the - /// IVssExamineWriterMetadata::SaveAsXML method. + /// The exact syntax and content of the backup options set by the wszBackupOptions parameter of the SetBackupOptions method + /// will depend on the specific writer being contacted. /// + /// This method must be called before IVssBackupComponents::PrepareForBackup. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-setbackupoptions HRESULT + // SetBackupOptions( [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] LPCWSTR wszComponentName, + // [in] LPCWSTR wszBackupOptions ); + void SetBackupOptions(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional] string wszLogicalPath, + string wszComponentName, string wszBackupOptions); + + /// The SetSelectedForRestore method indicates whether the specified selectable component is selected for restoration. + /// Writer identifier. + /// Type of the component. See VSS_COMPONENT_TYPE for the possible values. + /// + /// String containing the logical path of the component. 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. + /// The logical path can be . + /// There are no restrictions on the characters that can appear in a non- logical path. + /// + /// + /// String containing the name of the component. /// - /// To retrieve the latest version of a writer’s Writer Metadata Document, use the IVssBackupComponents::GetWriterMetadata method. + /// The string cannot be and should contain the same component name as was used when the component was added + /// to the backup set using IVssBackupComponents::AddComponent. /// + /// + /// + /// If the value of this parameter is true, the selected component has been selected for restoration. If the value is + /// false, the selected component has not been selected for restoration. + /// + /// + /// SetSelectedForRestore has meaning only for restores taking place in component mode. /// - /// To load a writer metadata document into an existing IVssExamineWriterMetadata object, use the - /// IVssExamineWriterMetadata::LoadFromXML method. + /// SetSelectedForRestore can only be called for components that were explicitly added to the backup document at backup time + /// using IVssBackupComponents::AddComponent. Restoring a component that was implicitly selected for backup as part of a component + /// set must be done by calling SetSelectedForRestore on the closest ancestor component that was added to the document. If + /// only this component's data is to be restored, that should be accomplished through IVssBackupComponents::AddRestoreSubcomponent; + /// this can only be done if the component is selectable for restore (see Working with Selectability and Logical Paths). /// - /// Users should not attempt to modify the contents of the Writer Metadata Document. + /// This method must be called before IVssBackupComponents::PreRestore. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-setselectedforrestore HRESULT + // SetSelectedForRestore( [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] LPCWSTR + // wszComponentName, [in] bool bSelectedForRestore ); + void SetSelectedForRestore(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional] string wszLogicalPath, + string wszComponentName, bool bSelectedForRestore); + + /// + /// The SetRestoreOptions method sets a string of private, or writer-dependent, restore parameters for a writer component. + /// + /// Writer identifier. + /// Type of the component. See VSS_COMPONENT_TYPE for the possible values. + /// + /// String containing the logical path of the component. For more information, see Logical Pathing of Components. /// - /// The calling application is responsible for calling IUnknown::Release to release the resources held by the - /// IVssExamineWriterMetadata object when the object is no longer needed. + /// 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 . + /// There are no restrictions on the characters that can appear in a non-NULL logical path. + /// + /// + /// String containing the name of the component. + /// + /// The string cannot be and should contain the same component name as was used when the component was added + /// to the backup set using IVssBackupComponents::AddComponent. + /// + /// + /// + /// String containing the private string of restore parameters. For more information see Setting VSS Restore Options. + /// + /// + /// This method must be called before IVssBackupComponents::PreRestore. + /// + /// The exact syntax and content of the restore options set by the wszRestoreOptions parameter of the SetRestoreOptions + /// method will depend on the specific writer being contacted. /// /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-createvssexaminewritermetadata HRESULT - // CreateVssExamineWriterMetadata( [in] BSTR bstrXML, [out] IVssExamineWriterMetadata **ppMetadata); - [DllImport(Lib_VssApi, SetLastError = false, CharSet = CharSet.Unicode, EntryPoint = "CreateVssExamineWriterMetadataInternal")] - [PInvokeData("vsbackup.h", MSDNShortId = "NF:vsbackup.CreateVssExamineWriterMetadata")] - public static extern HRESULT CreateVssExamineWriterMetadata([MarshalAs(UnmanagedType.BStr)] string bstrXML, out /*IVssExamineWriterMetadata*/ IntPtr ppMetadata); + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-setrestoreoptions HRESULT + // SetRestoreOptions( [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] LPCWSTR wszComponentName, + // [in] LPCWSTR wszRestoreOptions ); + void SetRestoreOptions(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional] string wszLogicalPath, + string wszComponentName, string wszRestoreOptions); - ///// The GetComponentInfo method obtains basic information about the specified writer metadata component. - ///// Doubly indirect pointer to a structure containing the returned component information. - ///// The caller is responsible for freeing the returned VSS_COMPONENTINFO structure by calling IVssWMComponent::FreeComponentInfo. - //public static VSS_COMPONENTINFO GetComponentInfo(this IVssWMComponent comp) - //{ - // comp.GetComponentInfo(out var ptr).ThrowIfFailed(); - // try { return ptr.ToStructure(); } - // finally { comp.FreeComponentInfo(ptr); } - //} + /// + /// The SetAdditionalRestores method is used by a requester during incremental or differential restore operations to indicate + /// to writers that a given component will require additional restore operations to completely retrieve it. + /// + /// Writer identifier. + /// Type of the component. See VSS_COMPONENT_TYPE for the possible values. + /// + /// String containing the logical path of the component to be added. + /// 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 . + /// There are no restrictions on the characters that can appear in a non- logical path. + /// + /// + /// String containing the name of the component. + /// + /// The value of the string should not be , and should contain the same component as was used when the + /// component was added to the backup set using IVssBackupComponents::AddComponent. + /// + /// + /// + /// If the value of this parameter is true, additional restores of the component will follow this restore. If the value is + /// false, additional restores of the component will not follow this restore. + /// + /// + /// + /// The information provided by the SetAdditionalRestores method is typically used by writers that support an explicit + /// recovery mechanism as part of their PostRestore event handler (CVssWriter::OnPostRestore)—for instance, the Exchange Server, and + /// database applications such as SQL Server. For these applications, it is often not possible to perform additional differential, + /// incremental, or log restores after such a recovery is performed. + /// + /// + /// Therefore, if SetAdditionalRestores for a component is set to true, this means that such a writer should not + /// execute its explicit recovery mechanism and should expect that additional differential, incremental, or log restores will be done. + /// + /// + /// When SetAdditionalRestores on a component is set to false, then after the component is restored, the application + /// can complete its recovery operation and be brought back online. + /// + /// This method must be called before IVssBackupComponents::PreRestore. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-setadditionalrestores HRESULT + // SetAdditionalRestores( [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] LPCWSTR + // wszComponentName, [in] bool bAdditionalRestores ); + void SetAdditionalRestores(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional] string wszLogicalPath, + string wszComponentName, bool bAdditionalRestores); + + /// + /// + /// The SetPreviousBackupStamp method sets the backup stamp of an earlier backup operation, upon which a differential or + /// incremental backup operation will be based. + /// + /// The method can be called only during a backup operation. + /// + /// Writer identifier. + /// Type of the component. See VSS_COMPONENT_TYPE for the possible values. + /// + /// String containing the logical path of the component. + /// 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 . + /// + /// + /// String containing the name of the component. + /// + /// The string cannot be and should contain the same component name as was used when the component was added + /// to the backup set using IVssBackupComponents::AddComponent. + /// + /// + /// The backup stamp to be set. + /// + /// This method should be called before IVssBackupComponents::PrepareForBackup. + /// Only requesters can call this method. + /// + /// The backup stamp set by SetPreviousBackupStamp applies to all files in the component and any nonselectable subcomponents + /// it has. + /// + /// + /// Requesters merely store the backup stamps in the Backup Components Document. They cannot make direct use of the backup stamps, + /// do not know their format, and do not know how to generate them. + /// + /// + /// Therefore, the value set with SetPreviousBackupStamp should either be retrieved from the stored Backup Components + /// Document of an earlier backup operation (using IVssComponent::GetBackupStamp for the correct component), or from information + /// stored by the requester into its own internal records. + /// + /// + /// A writer will then obtain this value (using IVssComponent::GetPreviousBackupStamp) and using it will be able to mark the + /// appropriate files for participation in an incremental or differential backup. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-setpreviousbackupstamp HRESULT + // SetPreviousBackupStamp( [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] LPCWSTR + // wszComponentName, [in] LPCWSTR wszPreviousBackupStamp ); + void SetPreviousBackupStamp(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional] string wszLogicalPath, + string wszComponentName, string wszPreviousBackupStamp); + + /// + /// The SaveAsXML method saves the Backup Components Document containing a requester's state information to a specified + /// string. This XML document, which contains the Backup Components Document, should always be securely saved as part of a backup operation. + /// + /// The Backup Components Document containing a requester's state information. + /// + /// + /// For a typical backup operation, SaveAsXML should not be called until after both writers and the requester are finished + /// modifying the Backup Components Document. + /// + /// + /// Writers can continue to modify the Backup Components Document until their successful return from handling the PostSnapshot event + /// (CVssWriter::OnPostSnapshot), or equivalently upon the completion of IVssBackupComponents::DoSnapshotSet. + /// + /// + /// Requesters will need to continue to modify the Backup Components Document as the backup progresses. In particular, a requester + /// will store a component-by-component record of the success or failure of the backup through calls to the + /// IVssBackupComponents::SetBackupSucceeded method. + /// + /// + /// Once the requester has finished modifying the Backup Components Document, the requester should use SaveAsXML to save a + /// copy of the document to the backup media. + /// + /// + /// A Backup Components Document can be saved at earlier points in the life cycle of a backup operation—for instance, to support the + /// generation of transportable shadow copies to be handled on remote machines. (See Importing Transportable Shadow Copied Volumes + /// for more information.) + /// + /// + /// However, SaveAsXML should never be called prior to IVssBackupComponents::PrepareForBackup, because the Backup Components + /// Document will not have been filled by the requester and the writers. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-saveasxml HRESULT SaveAsXML( [in] + // BSTR *pbstrXML ); + string SaveAsXML(); + + /// + /// The BackupComplete method causes VSS to generate a BackupComplete event, which signals writers that the backup + /// process has completed. + /// + /// Doubly indirect pointer to an IVssAsync instance. + /// + /// + /// When working in component mode (IVssBackupComponents::SetBackupState was called with a select components argument of + /// TRUE), writers can determine the success or failure of the backup of any component explicitly included in the Backup + /// Components Document components by using IVssComponent::GetBackupSucceeded. Therefore, a well-behaved backup application + /// (requester) must call IVssBackupComponents::SetBackupSucceeded after each component has been processed and prior to calling BackupComplete. + /// + /// + /// Do not call this method if the call to IVssBackupComponents::DoSnapshotSet failed. For more information about how requesters use + /// DoSnapshotSet, SetBackupSucceeded, and BackupComplete in a backup operation, see Overview of Pre-Backup Tasks and + /// Overview of Actual Backup Of Files. + /// + /// + /// This operation is asynchronous. The caller can use the QueryStatus interface method in the returned IVssAsync interface to + /// determine the status of the notification. + /// + /// + /// After calling BackupComplete, requesters must call GatherWriterStatus to cause the writer session to be set to a + /// completed state. + /// + /// Note This is only necessary on Windows Server 2008 with Service Pack 2 (SP2) and earlier. + /// The backup application can choose to abort the backup at any time after the shadow copy is created by calling IVssAsync::Cancel. + /// + /// The calling application is responsible for calling IUnknown::Release to release the resources held by the returned IVssAsync + /// when it is no longer needed. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-backupcomplete HRESULT + // BackupComplete( [out] IVssAsync **ppAsync ); + IVssAsync BackupComplete(); + + /// + /// The AddAlternativeLocationMapping method is used by a requester to indicate that an alternate location mapping was used + /// to restore all the members of a file set in a given component. + /// + /// Globally unique identifier (GUID) of the writer class that exported the component. + /// + /// Type of the component. The possible values of this parameter are defined by the VSS_COMPONENT_TYPE enumeration. + /// + /// + /// String containing the logical path to the component. + /// For more information, see Logical Pathing of Components. + /// The logical path can be . + /// There are no restrictions on the characters that can appear in a non- logical path. + /// + /// + /// String containing the component name. + /// There are no restrictions on the characters that can appear in a non- logical path. + /// + /// + /// + /// String containing the path to the directory that originally contained the file to be relocated. This path can be local to 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. + /// + /// + /// + /// String containing the original file specification. + /// + /// A file specification cannot contain directory specifications (for example, no backslashes) but can contain the ? and * wildcard characters. + /// + /// + /// + /// + /// A Boolean value that indicates whether the path specified by the wszPath parameter identifies only a single directory or if it + /// indicates a hierarchy of directories to be traversed recursively. This parameter should be set to true if the path is + /// treated as a hierarchy of directories to be traversed recursively, or false if not. + /// + /// For information on traversing mounted folders, see Working with Mounted Folders and Reparse Points. + /// + /// + /// String containing the name of the directory where the file will be relocated. This path can be local to the VSS machine, or it + /// can be a file share directory on a remote file server. UNC paths are supported. + /// + /// + /// + /// 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 writerId, componentType, wszLogicalPath, and wszComponentName parameters identify a particular component, and the wszPath, + /// wszFilespec, and bRecursive parameters identify the file set belonging to that component. + /// + /// + /// The combination of path, file specification, and recursion flag (wszPath, wszFilespec, and bRecursive, respectively) provided to + /// AddAlternativeLocationMapping to be mapped must match that of one of the file sets added to a component using either + /// IVssCreateWriterMetadata::AddFilesToFileGroup, IVssCreateWriterMetadata::AddDatabaseFiles, or IVssCreateWriterMetadata::AddDatabaseLogFiles. + /// + /// + /// Because AddAlternativeLocationMapping is used to notify a writer that an alternate location was used to restore all the + /// files in a component, it should not be called for any component or files in a component that have not had an alternate location + /// mapping specified. + /// + /// + /// The value of wszPath will have been mapped to wszDestination on restore; however, file names and subdirectories under the + /// original path retain their same names. + /// + /// A typical usage of AddAlternativeLocationMapping during restore might be the following: + /// + /// + /// Retrieve stored Writer Metadata Documents from the backup media and load that information with IVssExamineWriterMetadata::LoadFromXML. + /// + /// + /// + /// Call IVssExamineWriterMetadata::GetAlternateLocationMapping to get an IVssWMFiledesc interface with the mapping information and + /// use IVssWMFiledesc::GetAlternateLocation to get the alternate location. + /// + /// + /// + /// + /// Examine filedesc information to heuristically determine which component this alternate location mapping should be applied to. + /// + /// + /// + /// Call IVssBackupComponents::AddAlternativeLocationMapping to communicate where files were restored. + /// + /// + /// A file should always be restored to its alternate location mapping if either of the following is true: + /// + /// + /// The restore method (set at backup time) is VSS_RME_RESTORE_TO_ALTERNATE_LOCATION. + /// + /// + /// Its restore target was set (at restore time) to VSS_RT_ALTERNATE. + /// + /// + /// In either case, if no valid alternate location mapping is defined this constitutes a writer error. + /// A file may be restored to an alternate location mapping if either of the following is true: + /// + /// + /// The restore method is VSS_RME_RESTORE_IF_NOT_THERE and a version of the file is already present on disk. + /// + /// + /// The restore method is VSS_RME_RESTORE_IF_CAN_REPLACE and a version of the file is present on disk and cannot be replaced. + /// + /// + /// Again, if no valid alternate location mapping is defined this constitutes a writer error. + /// + /// An alternate location mapping is used only during a restore operation and should not be confused with an alternate path, which + /// is used only during a backup operation. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-addalternativelocationmapping + // HRESULT AddAlternativeLocationMapping( [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE componentType, [in] LPCWSTR wszLogicalPath, + // [in] LPCWSTR wszComponentName, [in] LPCWSTR wszPath, [in] LPCWSTR wszFilespec, [in] bool bRecursive, [in] LPCWSTR wszDestination ); + void AddAlternativeLocationMapping(Guid writerId, VSS_COMPONENT_TYPE componentType, [Optional] string wszLogicalPath, + string wszComponentName, string wszPath, string wszFilespec, bool bRecursive, string wszDestination); + + /// + /// The AddRestoreSubcomponent method indicates that a subcomponent member of a component set, which had been marked as + /// nonselectable for backup but is marked selectable for restore, is to be restored irrespective of whether any other member of the + /// component set will be restored. + /// + /// Writer class identifier. + /// + /// Identifies the type of the component. Refer to the documentation for VSS_COMPONENT_TYPE for possible return values. + /// + /// + /// + /// String containing the logical path of the component in the backup document that defines the backup component set containing the + /// subcomponent to be added for restore. + /// + /// The value of this parameter can be . + /// There are no restrictions on the characters that can appear in a non- logical path. + /// + /// + /// + /// String containing the logical path of the component in the backup document that defines the backup component set containing the + /// subcomponent to be added for restore. + /// + /// The value of this parameter cannot be . + /// There are no restrictions on the characters that can appear in a non- component name. + /// + /// + /// String containing the logical path of the subcomponent to be added for restore. + /// A logical path is required when adding a subcomponent. Therefore, the value of this parameter cannot be . + /// There are no restrictions on the characters that can appear in a non- logical path. + /// + /// + /// String containing the logical name of the subcomponent to be added for restore. + /// The value of this parameter cannot be . + /// There are no restrictions on the characters that can appear in a non- component name. + /// + /// This parameter is reserved for future use. This parameter should always be set to false + /// + /// + /// Before calling AddRestoreSubcomponent, the root component defined by the wszLogicalPath and wszComponentName parameters + /// must first be selected for restore using IVssBackupComponents::SetSelectedForRestore. + /// + /// If a requester is to support restoring subcomponents, this method must be called before IVssBackupComponents::PreRestore. + /// + /// AddRestoreSubcomponent is intended for the case in which all the files in a writer's component set must be backed up as a + /// unit, but where it is desirable that selected files (subcomponents) be capable of being restored individually. + /// + /// + /// To participate in such a restore, a subcomponent must have the bSelectableForRestore member of VSS_COMPONENTINFO set to + /// TRUE. The component defined by the wszLogicalPath and wszComponentName parameters must also be selected for restore using IVssBackupComponents::SetSelectedForRestore. + /// + /// See Working with Selectability for Restore and Subcomponents for more information. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-addrestoresubcomponent HRESULT + // AddRestoreSubcomponent( [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE componentType, [in] LPCWSTR wszLogicalPath, [in] LPCWSTR + // wszComponentName, [in] LPCWSTR wszSubComponentLogicalPath, [in] LPCWSTR wszSubComponentName, [in] bool bRepair ); + void AddRestoreSubcomponent(Guid writerId, VSS_COMPONENT_TYPE componentType, [Optional] string wszLogicalPath, + string wszComponentName, string wszSubComponentLogicalPath, string wszSubComponentName, bool bRepair); + + /// The SetFileRestoreStatus method indicates whether some, all, or no files were successfully restored. + /// Writer identifier. + /// Type of the component. See VSS_COMPONENT_TYPE for the possible values. + /// + /// String containing the logical path of the component. + /// 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 . + /// There are no restrictions on the characters that can appear in a non- logical path. + /// + /// + /// String containing the name of the component. + /// + /// The string cannot be and should contain the same component name as was used when the component was added + /// to the backup set using IVssBackupComponents::AddComponent. + /// + /// + /// + /// If all of the files were restored, the value of this parameter is VSS_RS_ALL. If some of the files were restored, the value of + /// this parameter is VSS_RS_FAILED. If none of the files were restored, the value of this parameter is VSS_RS_NONE. + /// + /// This method should be called between calls to IVssBackupComponents::PreRestore and IVssBackupComponents::PostRestore. + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-setfilerestorestatus HRESULT + // SetFileRestoreStatus( [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] LPCWSTR + // wszComponentName, [in] VSS_FILE_RESTORE_STATUS status ); + void SetFileRestoreStatus(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional] string wszLogicalPath, + string wszComponentName, VSS_FILE_RESTORE_STATUS status); + + /// + /// 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. + /// + /// + /// Globally unique identifier (GUID) of the writer class containing the files that are to receive a new target. + /// + /// + /// Identifies the type of the component. Refer to the documentation for VSS_COMPONENT_TYPE for possible return values. + /// + /// + /// + /// 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 . + /// There are no restrictions on the characters that can appear in a non- logical path. + /// + /// + /// String containing the name of the component containing the files that are to receive a new restore target. + /// + /// The string should not be 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- logical path. + /// + /// + /// 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. + /// + /// + /// + /// 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. + /// + /// + /// + /// + /// 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. + /// + /// + /// 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. + /// + /// + /// + /// 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. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-addnewtarget 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 ); + void AddNewTarget(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional] string wszLogicalPath, string wszComponentName, + string wszPath, string wszFileName, bool bRecursive, string wszAlternatePath); + + /// + /// The SetRangesFilePath method is used when a partial file operation requires a ranges file, and that file has been + /// restored to a location other than its original one. + /// + /// + /// Globally unique identifier (GUID) of the writer class containing the files involved in the partial file operation. + /// + /// Identifies the type of the component. Refer to VSS_COMPONENT_TYPE for possible return values. + /// + /// String containing the logical path of the component containing the files that are participating in the partial file operation. + /// 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 . + /// There are no restrictions on the characters that can appear in a non- logical path. + /// + /// + /// String containing the name of the component containing the files that are participating in the partial file operation. + /// + /// The string cannot be and should contain the same component name as was used when the component was added + /// to the backup set using IVssBackupComponents::AddComponent. + /// + /// + /// + /// Index number of the partial file. The value of this parameter is an integer from 0 to n–1 inclusive, where n is the total number + /// of partial files associated with a given component. The value of n is returned by IVssComponent::GetPartialFileCount. + /// + /// String containing the fully qualified path of a ranges file. + /// Calling SetRangesFilePath is not necessary if ranges files are restored in place. + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-setrangesfilepath HRESULT + // SetRangesFilePath( VSS_ID writerId, VSS_COMPONENT_TYPE ct, LPCWSTR wszLogicalPath, LPCWSTR wszComponentName, UINT iPartialFile, + // LPCWSTR wszRangesFile ); + void SetRangesFilePath(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional] string wszLogicalPath, + string wszComponentName, uint iPartialFile, string wszRangesFile); + + /// + /// The PreRestore method will cause VSS to generate a PreRestore event, signaling writers to prepare for an upcoming restore operation. + /// + /// Doubly indirect pointer to an IVssAsync object containing status data for the signaled event. + /// + /// The caller is responsible for releasing the IVssAsync interface pointer. + /// + /// Special consideration should be given to EFI systems when the requester has selected the Automated System Recovery (ASR) writer + /// for restore. If you are restoring to a disk that contains the EFI partition, and one of the following conditions exists, you + /// must first clean the disk by calling the IVdsAdvancedDisk::Clean method: + /// + /// + /// + /// You are restoring to an EFI system disk whose partitioning has changed since the last ASR backup. + /// + /// + /// You are restoring to a different physical drive than the one from which the backup was taken. + /// + /// + /// Failure to perform this disk-cleaning step may result in unexpected results during PreRestore. + /// For more information about the ASR writer, see In-Box VSS Writers. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-prerestore HRESULT PreRestore( [out] + // IVssAsync **ppAsync ); + IVssAsync PreRestore(); + + /// + /// The PostRestore method will cause VSS to generate a PostRestore event, signaling writers that the current restore + /// operation has finished. + /// + /// Doubly indirect pointer to an IVssAsync object that contains status data for the signaled event. + /// The caller is responsible for releasing the IVssAsync interface. + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-postrestore HRESULT PostRestore( + // [out] IVssAsync **ppAsync ); + IVssAsync PostRestore(); + + /// The SetContext method sets the context for subsequent shadow copy-related operations. + /// + /// The context to be set. The context must be one of the supported values of _VSS_SNAPSHOT_CONTEXT or a supported bit mask (or + /// bitwise OR) of _VSS_VOLUME_SNAPSHOT_ATTRIBUTES with a valid _VSS_SNAPSHOT_CONTEXT. + /// + /// + /// The default context for VSS shadow copies is VSS_CTX_BACKUP. + /// + /// Windows XP: The only supported context is the default context, VSS_CTX_BACKUP. Therefore, calling SetContext under + /// Windows XP returns E_NOTIMPL. + /// + /// SetContext can be called only once, and it must be called prior to calling most VSS functions. + /// + /// For details on how the context set by IVssBackupComponents::SetContext affects how a shadow copy is created and managed, + /// see Implementation Details for Creating Shadow Copies. + /// + /// For a complete discussion of the permitted shadow copy contexts, see _VSS_SNAPSHOT_CONTEXT and _VSS_VOLUME_SNAPSHOT_ATTRIBUTES. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-setcontext HRESULT SetContext( [in] + // LONG lContext ); + void SetContext(VSS_SNAPSHOT_CONTEXT lContext); + + /// The StartSnapshotSet method creates a new, empty shadow copy set. + /// The address of a caller-allocated variable that receives the shadow copy set identifier. + /// This method must be called before IVssBackupComponents::PrepareForBackup during backup operations. + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-startsnapshotset HRESULT + // StartSnapshotSet( [out] VSS_ID *pSnapshotSetId ); + Guid StartSnapshotSet(); + + /// The AddToSnapshotSet method adds an original volume or original remote file share to the shadow copy set. + /// + /// + /// String containing the name of the volume or the UNC path of the remote file share to be shadow copied. The name or UNC path must + /// be in one of the following formats and must include a trailing backslash (\): + /// + /// + /// + /// The path of a mounted folder, for example, Y:\MountX\ + /// + /// + /// A drive letter, for example, D:\ + /// + /// + /// A volume GUID path of the form \\?\Volume{GUID}\ (where GUID identifies the volume) + /// + /// + /// A UNC path that specifies a remote file share, for example, \\Clusterx\Share1\ + /// + /// + /// + /// The provider to be used. Guid.Null can be used, in which case the default provider will be used. + /// Returned identifier of the added shadow copy. + /// + /// + /// 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. + /// + /// + /// If pwszVolumeName is a UNC share path, the server name portion must be in hostname or fully qualified domain name format. UNC + /// share names with IP addresses must be normalized by calling the IVssBackupComponentsEx4::GetRootAndLogicalPrefixPaths method + /// before they are passed to AddToSnapshotSet. + /// + /// The maximum number of shadow copied volumes in a single shadow copy set is 64. + /// If ProviderId is Guid.Null, the default provider is selected according to the following algorithm: + /// + /// + /// If any hardware provider supports the given volume or remote file share, that provider is selected. + /// + /// + /// If there is no hardware provider available, if any software provider supports the given volume, it is selected. + /// + /// + /// + /// If there is no hardware provider or software provider available, the system provider is selected. (There is only one + /// preinstalled system provider, which must support all nonremovable local volumes.) + /// + /// + /// + /// This method cannot be called for a virtual hard disk (VHD) that is nested inside another VHD. + /// Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: VHDs are not supported. + /// + /// The shadow copy identifier that is returned in the pidSnapshot parameter is stored in the Backup Components Document. However, + /// there is no method for querying this information, and the caller may need to store it so that it can be used during restore. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-addtosnapshotset HRESULT + // AddToSnapshotSet( [in] VSS_PWSZ pwszVolumeName, [in] VSS_ID ProviderId, [out] VSS_ID *pidSnapshot ); + Guid AddToSnapshotSet(string pwszVolumeName, Guid ProviderId); + + /// Commits all shadow copies in this set simultaneously. + /// + /// A doubly indirect pointer to the required IVssAsync asynchronous interface. This is used to query the method execution state and + /// to retrieve the final error code. + /// + /// + /// The caller is responsible for releasing the IVssAsync interface. + /// This method cannot be called for a virtual hard disk (VHD) that is nested inside another VHD. + /// Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: VHDs are not supported. + /// + /// For information on how to use IVssBackupComponents::DoSnapshotSet to create a standard backup shadow copy, see Overview + /// of Pre-Backup Tasks and Simple Shadow Copy Creation for Backup. For information on how the method is used under different VSS + /// contexts, see Implementation Details for Creating Shadow Copies. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-dosnapshotset HRESULT DoSnapshotSet( + // [out] IVssAsync **ppAsync ); + IVssAsync DoSnapshotSet(); + + /// The DeleteSnapshots method deletes one or more shadow copies or a shadow copy set. + /// Identifier of the shadow copy or a shadow copy set to be deleted. + /// + /// Type of the object on which all shadow copies will be deleted. The value of this parameter is VSS_OBJECT_SNAPSHOT or VSS_OBJECT_SNAPSHOT_SET. + /// + /// + /// If the value of this parameter is TRUE, the provider will do everything possible to delete the shadow copy or shadow + /// copies in a shadow copy set. If it is FALSE, no additional effort will be made. + /// + /// Number of deleted shadow copies. + /// + /// If an error occurs, the value of this parameter is the identifier of the first shadow copy that could not be deleted. Otherwise, + /// it is Guid.Null. + /// + /// + /// + /// Multiple shadow copies in a shadow copy set are deleted sequentially. If an error occurs during one of these individual + /// deletions, DeleteSnapshots will return immediately; no attempt will be made to delete any remaining shadow copies. The + /// VSS_ID of the undeleted shadow copy is returned in pNondeletedSnapshotID. + /// + /// The requester is responsible for serializing the delete shadow copy operation. + /// + /// During a backup, shadow copies are automatically released as soon as the IVssBackupComponents instance is released. In this + /// case, it is not necessary to explicitly delete shadow copies. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-deletesnapshots HRESULT + // DeleteSnapshots( [in] VSS_ID SourceObjectId, [in] VSS_OBJECT_TYPE eSourceObjectType, [in] BOOL bForceDelete, [out] LONG + // *plDeletedSnapshots, [out] VSS_ID *pNondeletedSnapshotID ); + void DeleteSnapshots(Guid SourceObjectId, VSS_OBJECT_TYPE eSourceObjectType, bool bForceDelete, + out int plDeletedSnapshots, out Guid pNondeletedSnapshotID); + + /// The ImportSnapshots method imports shadow copies transported from a different machine. + /// Doubly indirect pointer to an IVssAsync object containing the imported shadow copy status data. + /// + /// Only one shadow copy can be imported at a time. + /// The requester is responsible for serializing the import shadow copy operation. + /// The caller is responsible for releasing the IVssAsync interface. + /// For more information on importing shadow copies, see Importing Transportable Shadow Copied Volumes. + /// + /// Transportable shadow copies in a cluster: For details about using transportable shadow copies in a cluster, see Fast + /// Recovery Using Transportable Shadow Copied Volumes. The transportable shadow copy must be imported from outside the cluster as + /// long as the original volume is mounted within the cluster. + /// + /// + /// Note If the shadow copy import fails, the Volume Shadow Copy Service won't clean up LUNs on its own. The requester has to + /// initiate the cleanup of LUNs. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-importsnapshots HRESULT + // ImportSnapshots( [out] IVssAsync **ppAsync ); + IVssAsync ImportSnapshots(); + + /// The BreakSnapshotSet method causes the existence of a shadow copy set to be "forgotten" by VSS. + /// Shadow copy set identifier. + /// + /// + /// BreakSnapshotSet can be used only for shadow copies created by a hardware shadow copy provider. This method makes these + /// shadow copies regular volumes. + /// + /// + /// Shadow copies of volumes "broken" with BreakSnapshotSet must be managed independently of VSS as stand-alone volumes. See + /// Breaking Shadow Copies for more information. + /// + /// + /// IVssBackupComponentsEx2::BreakSnapshotSetEx is similar to the BreakSnapshotSet method, except that it has extra + /// parameters to query status and specify how the shadow copy set is broken. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-breaksnapshotset HRESULT + // BreakSnapshotSet( [in] VSS_ID SnapshotSetId ); + void BreakSnapshotSet(Guid SnapshotSetId); + + /// The GetSnapshotProperties method gets the properties of the specified shadow copy. + /// The identifier of the shadow copy of a volume as returned by IVssBackupComponents::AddToSnapshotSet. + /// + /// The address of a caller-allocated VSS_SNAPSHOT_PROP structure that receives the shadow copy properties. The software provider is + /// responsible for setting the members of this structure. The software provider allocates memory for all string members that it + /// sets in the structure. When the structure is no longer needed, the software provider is responsible for freeing these strings by + /// calling the VssFreeSnapshotProperties function. + /// + /// + /// + /// The caller should set the contents of the VSS_SNAPSHOT_PROP structure to zero before calling the GetSnapshotProperties method. + /// + /// The provider is responsible for allocating and freeing the strings in the VSS_SNAPSHOT_PROP structure. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-getsnapshotproperties HRESULT + // GetSnapshotProperties( [in] VSS_ID SnapshotId, [out] VSS_SNAPSHOT_PROP *pProp ); + VSS_SNAPSHOT_PROP GetSnapshotProperties(Guid SnapshotId); + + /// + /// The Query method queries providers on the system and/or the completed shadow copies in the system that reside in the + /// current context. The method can be called only during backup operations. + /// + /// Reserved. The value of this parameter must be Guid.Null. + /// + /// + /// Indicates restriction of the query to the given object type. A value of VSS_OBJECT_NONE indicates no restriction—that is, all + /// objects will be queried. + /// + /// Currently, the value of this parameter must be VSS_OBJECT_NONE. + /// + /// + /// Object types to be returned. The value of this parameter must be either VSS_OBJECT_SNAPSHOT or VSS_OBJECT_PROVIDER. + /// + /// Doubly indirect pointer to an IVssEnumObject enumerator object. + /// + /// + /// Because Query returns only information on completed shadow copies, the only shadow copy state it can disclose is VSS_SS_COMPLETED. + /// + /// + /// The method may be called only during backup operations and must be preceded by calls to + /// IVssBackupComponents::InitializeForBackup and IVssBackupComponents::SetContext. + /// + /// + /// While Query can return information on all of the providers available on a system, it will return only information about + /// shadow copies with the current context (set by IVssBackupComponents::SetContext). For instance, if the _VSS_SNAPSHOT_CONTEXT + /// context is set to VSS_CTX_BACKUP, Query will not return information on a shadow copy created with a context of VSS_CTX_FILE_SHARE_BACKUP. + /// + /// + /// While this method currently returns a lists of all available providers and/or all completed shadow copies, in the future, + /// specialized queries may be supported: for instance, querying all shadow copies associated with a provider. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-query HRESULT Query( [in] VSS_ID + // QueriedObjectId, [in] VSS_OBJECT_TYPE eQueriedObjectType, [in] VSS_OBJECT_TYPE eReturnedObjectsType, [out] IVssEnumObject + // **ppEnum ); + IVssEnumObject Query(Guid QueriedObjectId, VSS_OBJECT_TYPE eQueriedObjectType, VSS_OBJECT_TYPE eReturnedObjectsType); + + /// + /// The IsVolumeSupported method determines whether the specified provider supports shadow copies on the specified volume or + /// remote file share. + /// + /// + /// Provider identifier. If the value is Guid.Null, IsVolumeSupported checks whether any provider supports the volume or + /// remote file share. + /// + /// + /// + /// Volume name or UNC path of remote file share. The name or UNC path must be in one of the following formats and must include a + /// trailing backslash (\): + /// + /// + /// + /// The path of a mounted folder, for example, Y:\MountX\ + /// + /// + /// A drive letter, for example, D:\ + /// + /// + /// A volume GUID path of the form \\?\Volume{GUID}\ (where GUID identifies the volume) + /// + /// + /// A UNC path that specifies a remote file share, for example, \\Clusterx\Share1\ + /// + /// + /// + /// + /// Address of a caller-allocated variable that receives TRUE if shadow copies are supported on the specified volume or + /// remote file share, or FALSE otherwise. + /// + /// + /// + /// 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. + /// + /// + /// IsVolumeSupported will return TRUE if it is possible to create shadow copies on the given volume, even if the + /// current configuration does not allow the creation of shadow copies on that volume at the present time. + /// + /// + /// For example, if the maximum number of shadow copies has been reached on a given volume (and therefore no more shadow copies can + /// be created on that volume), the method will still indicate that the volume can be shadow copied. + /// + /// + /// Note For more information about the maximum number of shadow copies that can be created on a volume, see the entry for + /// MaxShadowCopies in Registry Keys and Values for Backup and Restore. + /// + /// This method cannot be called for a virtual hard disk (VHD) that is nested inside another VHD. + /// Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: VHDs are not supported. + /// + bool IsVolumeSupported(Guid ProviderId, string pwszVolumeName); + + /// The DisableWriterClasses method prevents a specific class of writers from receiving any events. + /// An array containing one or more writer class identifiers. + /// The number of entries in the rgWriterClassId array. + /// + /// + /// If you have multiple running copies of the same writer, they will all have the same writer class identifier, but they will have + /// different writer instance identifiers. Disabling a writer class causes all of the writer's instances to be disabled. + /// + /// + /// If the DisableWriterClasses method and the IVssBackupComponents::EnableWriterClasses method are never called, all writer + /// classes are enabled. + /// + /// + /// After the first call to DisableWriterClasses returns, the writer classes that were specified in the rgWriterClassId array + /// are disabled, and all other writer classes are enabled. + /// + /// + /// If you call DisableWriterClasses more than once, each call adds the writers in the rgWriterClassId array to the list of + /// disabled writers. + /// + /// + /// If you call DisableWriterClasses one or more times and then call EnableWriterClasses, the first call to + /// EnableWriterClasses cancels the effect of the calls to DisableWriterClasses and enables only the writers in the + /// rgWriterClassId array. + /// + /// + /// If you call DisableWriterClasses, you must do so before calling the IVssBackupComponents::GatherWriterMetadata method. If + /// you call GatherWriterMetadata first and then call DisableWriterClasses, the call to DisableWriterClasses + /// has no effect. If you need to call GatherWriterMetadata first, to determine which writer classes to disable, you must + /// call it from a different instance of the IVssBackupComponents interface. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-disablewriterclasses HRESULT + // DisableWriterClasses( [in] const VSS_ID *rgWriterClassId, [in] UINT cClassId ); + void DisableWriterClasses([In] Guid[] rgWriterClassId); + + /// The EnableWriterClasses method enables the specified writers to receive all events. + /// An array containing one or more writer class identifiers. + /// The number of entries in the rgWriterClassId array. + /// + /// + /// If the EnableWriterClasses method and the IVssBackupComponents::DisableWriterClasses method are never called, all writer + /// classes are enabled. + /// + /// + /// After the first call to EnableWriterClasses returns, the writer classes that were specified in the rgWriterClassId array + /// are enabled, and all other writer classes are disabled. + /// + /// + /// If you call EnableWriterClasses more than once, each call adds the writers in the rgWriterClassId array to the list of + /// enabled writers. + /// + /// + /// If you call EnableWriterClasses one or more times and then call DisableWriterClasses, the call to + /// DisableWriterClasses disables any writers in the rgWriterClassId array that were enabled in the calls to EnableWriterClasses. + /// + /// + /// If you call EnableWriterClasses, you must do so before calling the IVssBackupComponents::GatherWriterMetadata method. If + /// you call GatherWriterMetadata first and then call EnableWriterClasses, the call to EnableWriterClasses has + /// no effect. If you need to call GatherWriterMetadata first, to determine which writer classes to enable, you must call it + /// from a different instance of the IVssBackupComponents interface. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-enablewriterclasses HRESULT + // EnableWriterClasses( [in] const VSS_ID *rgWriterClassId, [in] UINT cClassId ); + void EnableWriterClasses([In] Guid[] rgWriterClassId); + + /// The DisableWriterInstances method disables a specified writer instance or instances. + /// An array containing one or more writer instance identifiers. + /// The number of entries in the rgWriterInstanceId array. + /// + /// + /// If you have multiple running copies of the same writer, they will all have the same writer class identifier, but they will have + /// different writer instance identifiers. Disabling one instance of a writer does not cause the writer's other instances to be disabled. + /// + /// + /// If you call DisableWriterInstances, you must do so before calling the IVssBackupComponents::GatherWriterMetadata method. + /// If you call GatherWriterMetadata first and then call DisableWriterInstances, the call to + /// DisableWriterInstances has no effect. If you need to call GatherWriterMetadata first, to determine which writer + /// instances to disable, you must call it from a different instance of the IVssBackupComponents interface. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-disablewriterinstances HRESULT + // DisableWriterInstances( [in] const VSS_ID *rgWriterInstanceId, [in] UINT cInstanceId ); + void DisableWriterInstances([In] Guid[] rgWriterInstanceId); + + /// The ExposeSnapshot method exposes a shadow copy as a drive letter, mounted folder, or file share. + /// Shadow copy identifier. + /// + /// + /// The path to the portion of the volume made available when exposing a shadow copy as a file share. The value of this parameter + /// must be when exposing a shadow copy locally; that is, exposing it as a drive letter or mounted folder. + /// + /// The path cannot contain environment variables (for example, %MyEnv%) or wildcard characters. + /// + /// There is no requirement that the path end with a backslash (""). It is up to applications that retrieve this information to check. + /// + /// + /// + /// Attributes of the exposed shadow copy indicating whether it is exposed locally or remotely. The value must be either the + /// VSS_VOLSNAP_ATTR_EXPOSED_LOCALLY or the VSS_VOLSNAP_ATTR_EXPOSED_REMOTELY value of _VSS_VOLUME_SNAPSHOT_ATTRIBUTES. + /// + /// + /// When a shadow copy is exposed as a file share, the value of this parameter is the share name. If a shadow copy is exposed by + /// mounting it as a device, the parameter value is a drive letter followed by a colon—for example, "X:" or a mounted folder path + /// (for example, "Y:\MountX"). If the value of this parameter is , then VSS determines the share name or + /// drive letter if the lAttributes parameter is VSS_VOLSNAP_ATTR_EXPOSED_REMOTELY. + /// + /// + /// The exposed name of the shadow copy. This is either a share name, a drive letter followed by a colon, or a mounted folder. The + /// value is if ExposeSnapshot failed. VSS allocates the memory for this string. + /// + /// + /// + /// The caller is responsible for freeing the string that the pwszExposed parameter points to by calling the CoTaskMemFree function. + /// + /// When exposing a persistent shadow copy, it remains exposed through subsequent boots. + /// + /// When exposing a shadow copy of a volume, the shadow copy may be treated either as a mountable device or as a file system + /// available for file sharing. + /// + /// + /// When it is exposed as a device—as with other mountable devices—the shadow copy of a volume is exposed at its mount point (drive + /// letter or mounted folder) starting with its root. + /// + /// When exposed as a file share, subsets (indicated by wszPathFromRoot) of the volume can be shared. + /// For more information on how to expose shadow copies, see Exposing and Surfacing Shadow Copied Volumes. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-exposesnapshot HRESULT + // ExposeSnapshot( [in] VSS_ID SnapshotId, [in] VSS_PWSZ wszPathFromRoot, [in] LONG lAttributes, [in] VSS_PWSZ wszExpose, [out] + // VSS_PWSZ *pwszExposed ); + string ExposeSnapshot(Guid SnapshotId, [Optional] string wszPathFromRoot, + VSS_VOLUME_SNAPSHOT_ATTRIBUTES lAttributes, [Optional] string wszExpose); + + /// + /// + /// The RevertToSnapshot method reverts a volume to a previous shadow copy. Only shadow copies created with persistent + /// contexts ( VSS_CTX_APP_ROLLBACK, VSS_CTX_CLIENT_ACCESSIBLE, VSS_CTX_CLIENT_ACCESSIBLE_WRITERS, or + /// VSS_CTX_NAS_ROLLBACK) are supported. + /// + /// Note This method is only supported on Windows Server operating systems. + /// + /// VSS_ID of the shadow copy to revert. + /// + /// If this parameter is TRUE, the volume will be dismounted and reverted even if the volume is in use. + /// + /// + /// This operation cannot be canceled, or undone once completed. If the computer is rebooted during the revert operation, the revert + /// process will continue when the system is restarted. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-reverttosnapshot HRESULT + // RevertToSnapshot( [in] VSS_ID SnapshotId, [in] BOOL bForceDismount ); + void RevertToSnapshot(Guid SnapshotId, bool bForceDismount); + + /// + /// The QueryRevertStatus method returns an IVssAsync interface pointer that can be used to determine the status of the + /// revert operation. + /// + /// + /// + /// String containing the name of the volume. The name must be in one of the following formats and must include a trailing backslash (\): + /// + /// + /// + /// The path of a mounted folder, for example, Y:\MountX\ + /// + /// + /// A drive letter, for example, D:\ + /// + /// + /// A volume GUID path of the form \\?\Volume{GUID}\ (where GUID identifies the volume) + /// + /// + /// + /// + /// An IVssAsync interface pointer that can be used to retrieve the status of the revert process. When the operation is complete, + /// the caller must release the interface pointer by calling the IUnknown::Release method. + /// + /// + /// The revert operation will continue even if the computer is rebooted, and cannot be canceled or undone, except by restoring a + /// backup created using another method. The QueryStatus method on the returned IVssAsync interface cannot return + /// VSS_S_ASYNC_CANCELLED as the revert operation cannot be canceled after it has started. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponents-queryrevertstatus HRESULT + // QueryRevertStatus( [in] VSS_PWSZ pwszVolume, [out] IVssAsync **ppAsync ); + IVssAsync QueryRevertStatus(string pwszVolume); + + /// + /// The SetSelectedForRestoreEx method indicates whether the specified selectable component is selected for restoration to a + /// specified writer instance. + /// + /// Globally unique identifier (GUID) of the writer class. + /// Type of the component. See VSS_COMPONENT_TYPE for the possible values. + /// + /// String containing the logical path of the component. 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. + /// The logical path can be . + /// There are no restrictions on the characters that can appear in a non- logical path. + /// + /// + /// String containing the name of the component. + /// + /// The string cannot be and should contain the same component name as was used when the component was added + /// to the backup set using the IVssBackupComponents::AddComponent method. + /// + /// + /// + /// If the value of this parameter is true, the selected component has been selected for restoration. If the value is + /// false, the selected component has not been selected for restoration. + /// + /// + /// GUID of the writer instance. + /// The default value for this parameter is Guid.Null. + /// + /// + /// + /// SetSelectedForRestoreEx, which moves a component to a different writer instance, can be called only for a writer that + /// supports running multiple writer instances with the same class ID and supports a requester moving a component to a different + /// writer instance at restore time. To determine whether a writer provides this support, call the + /// IVssExamineWriterMetadata::GetBackupSchema method. + /// + /// SetSelectedForRestoreEx has meaning only for restores taking place in component mode. + /// + /// SetSelectedForRestoreEx can be called only for components that were explicitly added to the backup document at backup + /// time using AddComponent. Restoring a component that was implicitly selected for backup as part of a component set must be done + /// by calling SetSelectedForRestoreEx on the closest ancestor component that was added to the document. If only this + /// component's data is to be restored, that should be accomplished through the IVssBackupComponents::AddRestoreSubcomponent method; + /// this can be done only if the component is selectable for restore (see Working with Selectability and Logical Paths). + /// + /// This method must be called before the IVssBackupComponents::PreRestore method. + /// + /// The distinction between the instanceId and writerID parameters is necessary because it is possible that multiple instances of + /// the same writer are running on the computer. + /// + /// + /// If the value of the instanceId parameter is Guid.Null, this is equivalent to calling the + /// IVssBackupComponents::SetSelectedForRestore method. + /// + /// + /// The instanceId parameter is used to specify that the component is to be restored to a different writer instance. If the value of + /// the instanceId parameter is not Guid.Null, it must match the instance ID of a writer instance with the same writer class ID + /// specified in in the writerID parameter. + /// + /// + /// A writer's class identifier, instance identifier, and instance name can be found by calling the + /// IVssExamineWriterMetadataEx::GetIdentityEx method. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex-setselectedforrestoreex HRESULT + // SetSelectedForRestoreEx( VSS_ID writerId, VSS_COMPONENT_TYPE ct, LPCWSTR wszLogicalPath, LPCWSTR wszComponentName, bool + // bSelectedForRestore, VSS_ID instanceId ); + void SetSelectedForRestoreEx(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional] string wszLogicalPath, + string wszComponentName, bool bSelectedForRestore, Guid instanceId = default); + + /// Unexposes a shadow copy either by deleting the file share or by removing the drive letter or mounted folder. + /// + /// The shadow copy identifier. The value of this identifier should be the same as the value that was used when the shadow copy was exposed. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex2-unexposesnapshot HRESULT + // UnexposeSnapshot( [in] VSS_ID snapshotId ); + void UnexposeSnapshot(Guid snapshotId); + + /// Marks the restore of a component as authoritative for a replicated data store. + /// The globally unique identifier (GUID) of the writer class. + /// The type of the component. See the VSS_COMPONENT_TYPE enumeration for the possible values. + /// + /// A string containing the logical path of the component. For more information, see Logical Pathing of Components. + /// + /// The value of the string containing the logical path used here should be the same as the string that was used when the component + /// was added. + /// + /// The logical path can be . + /// There are no restrictions on the characters that can appear in a non- logical path. + /// + /// + /// A string containing the name of the component. + /// + /// The string cannot be and should contain the same component name as the string that was used when the + /// component was added to the backup set using the IVssBackupComponents::AddComponent method. + /// + /// + /// + /// Set this variable to true to indicate that the restore of the component is authoritative, or false otherwise. + /// The default value is false. + /// + /// + /// The SetAuthoritativeRestore method can only be called during a restore operation. + /// + /// A writer indicates that it supports authoritative restore by setting the VSS_BS_AUTHORITATIVE_RESTORE flag in its backup + /// schema mask. + /// + /// For more information, see Setting VSS Restore Options. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex2-setauthoritativerestore HRESULT + // SetAuthoritativeRestore( [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] LPCWSTR + // wszComponentName, [in] bool bAuth ); + void SetAuthoritativeRestore(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional] string wszLogicalPath, + string wszComponentName, bool bAuth); + + /// + /// Sets the roll-forward operation type for a component and specifies the restore point for a partial roll-forward operation. + /// + /// The globally unique identifier (GUID) of the writer class. + /// The type of the component. See the VSS_COMPONENT_TYPE enumeration for the possible values. + /// + /// A string containing the logical path of the component. For more information, see Logical Pathing of Components. + /// + /// The value of the string containing the logical path used here should be the same as the string that was used when the component + /// was added. + /// + /// The logical path can be . + /// There are no restrictions on the characters that can appear in a non- logical path. + /// + /// + /// A string containing the name of the component. + /// + /// The string cannot be and should contain the same component name as the string that was used when the + /// component was added to the backup set using the IVssBackupComponents::AddComponent method. + /// + /// + /// A VSS_ROLLFORWARD_TYPE enumeration value indicating the type of roll-forward operation to be performed. + /// + /// A string specifying the roll-forward restore point. + /// + /// The format of this string is defined by the writer, and can be a timestamp, a log sequence number (LSN), or any marker defined + /// by the writer. + /// + /// + /// + /// The SetRollForward method can only be called during a restore operation. + /// + /// A writer indicates that it supports this method by setting the VSS_BS_ROLLFORWARD_RESTORE flag in its backup schema mask. + /// + /// For more information, see Setting VSS Restore Options. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex2-setrollforward HRESULT + // SetRollForward( [in] VSS_ID writerId, [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] LPCWSTR wszComponentName, + // [in] VSS_ROLLFORWARD_TYPE rollType, [in] LPCWSTR wszRollForwardPoint ); + void SetRollForward(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional] string wszLogicalPath, + string wszComponentName, VSS_ROLLFORWARD_TYPE rollType, string wszRollForwardPoint); + + /// Assigns a new logical name to a component that is being restored. + /// The globally unique identifier (GUID) of the writer class. + /// The type of the component. See the VSS_COMPONENT_TYPE enumeration for the possible values. + /// + /// A string containing the logical path of the component. For more information, see Logical Pathing of Components. + /// + /// The value of the string containing the logical path used here should be the same as the string that was used when the component + /// was added. + /// + /// The logical path can be . + /// There are no restrictions on the characters that can appear in a non- logical path. + /// + /// + /// A string containing the name of the component. + /// + /// The string cannot be and should contain the same component name as was the component name that was used + /// when the component was added to the backup set using the IVssBackupComponents::AddComponent method. + /// + /// + /// A string containing the restore name to be set for the component. + /// + /// The SetRestoreName method can only be called during a restore operation. + /// + /// A writer indicates that it supports this method by setting the VSS_BS_RESTORE_RENAME flag in its backup schema mask. + /// + /// For more information, see Setting VSS Restore Options. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex2-setrestorename HRESULT + // SetRestoreName( VSS_ID writerId, VSS_COMPONENT_TYPE ct, LPCWSTR wszLogicalPath, LPCWSTR wszComponentName, LPCWSTR wszRestoreName ); + void SetRestoreName(Guid writerId, VSS_COMPONENT_TYPE ct, [Optional] string wszLogicalPath, + string wszComponentName, string wszRestoreName); + + /// Breaks a shadow copy set according to requester-specified options. + /// A shadow copy set identifier. + /// A bitmask of _VSS_HARDWARE_OPTIONS flags that specify how the shadow copy set is broken. + /// + /// A variable that receives an IVssAsync interface pointer that can be used to retrieve the status of the shadow copy set break + /// operation. When the break operation is complete, the IUnknown::Release method must be called for this interface pointer. + /// + /// + /// + /// BreakSnapshotSetEx is similar to the IVssBackupComponents::BreakSnapshotSet method, except that it has extra parameters + /// to query status and specify how the shadow copy set is broken. + /// + /// + /// Like BreakSnapshotSet, BreakSnapshotSetEx can be used only for shadow copies that were created by a hardware shadow copy provider. + /// + /// + /// After this method returns, the shadow copy volume is still a volume, but it is no longer a shadow copy. For more information, + /// see Breaking Shadow Copies. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex2-breaksnapshotsetex HRESULT + // BreakSnapshotSetEx( VSS_ID SnapshotSetID, DWORD dwBreakFlags, [out] IVssAsync **ppAsync ); + IVssAsync BreakSnapshotSetEx(Guid SnapshotSetID, VSS_HARDWARE_OPTIONS dwBreakFlags); + + /// + /// Not supported. + /// This method is reserved for future use. + /// + /// This parameter is reserved for future use. + /// This parameter is reserved for future use. + /// This parameter is reserved for future use. + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex2-prefastrecovery HRESULT + // PreFastRecovery( VSS_ID SnapshotSetID, DWORD dwPreFastRecoveryFlags, IVssAsync **ppAsync ); + IVssAsync PreFastRecovery(Guid SnapshotSetID, [Optional] uint dwPreFastRecoveryFlags); + + /// + /// Not supported. + /// This method is reserved for future use. + /// + /// This parameter is reserved for future use. + /// This parameter is reserved for future use. + /// This parameter is reserved for future use. + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex2-fastrecovery HRESULT + // FastRecovery( VSS_ID SnapshotSetID, DWORD dwFastRecoveryFlags, IVssAsync **ppAsync ); + IVssAsync FastRecovery(Guid SnapshotSetID, [Optional] uint dwFastRecoveryFlags); + + /// + /// Specifies the volumes to be included in a LUN resynchronization operation. This method is supported only on Windows server + /// operating systems. + /// + /// + /// The identifier of the shadow copy that was returned by the IVssBackupComponents::AddToSnapshotSet method during backup. This + /// parameter is required and cannot be Guid.Null. + /// + /// This parameter is reserved and must be zero. + /// + /// This parameter is optional and can be . A value of means that the contents of the + /// shadow copy volume are to be copied back to the original volume. VSS identifies the original volume by the VDS_LUN_INFO + /// information in the Backup Components Document. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex3-addsnapshottorecoveryset HRESULT + // AddSnapshotToRecoverySet( [in] VSS_ID snapshotId, [in] DWORD dwFlags, [in, optional] VSS_PWSZ pwszDestinationVolume ); + void AddSnapshotToRecoverySet(Guid snapshotId, [Optional] uint dwFlags, string pwszDestinationVolume = default); + + /// Initiates a LUN resynchronization operation. This method is supported only on Windows server operating systems. + /// A bitmask of VSS_RECOVERY_OPTIONS flags that specify how the resynchronization is to be performed. + /// + /// A variable that receives an IVssAsync interface pointer that can be used to retrieve the status of the LUN resynchronization + /// operation. When the operation is complete, the caller must release the interface pointer by calling the IUnknown::Release method. + /// + /// + /// + /// At the end of the resynchronization operation, by default the newly resychronized LUN will have the same disk signature that the + /// destination LUN had before the resynchronization. + /// + /// + /// This method cannot be called in WinPE, and it cannot be called in Safe mode. Before calling this method, the caller must call + /// IVssBackupComponents::InitializeForRestore to prepare for the resynchronization. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex3-recoverset HRESULT RecoverSet( + // [in] DWORD dwFlags, [out] IVssAsync **ppAsync ); + IVssAsync RecoverSet(VSS_RECOVERY_OPTIONS dwFlags); + + /// Returns the requester's session identifier. + /// A variable that receives the session identifier. + /// + /// + /// The session identifier is an opaque value that uniquely identifies a backup or restore session. It is used to distinguish the + /// current session among multiple parallel backup or restore sessions. + /// + /// + /// As a best practice, writers and requesters should include the session ID in all diagnostics messages used for event logging and tracing. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex3-getsessionid HRESULT + // GetSessionId( [out] VSS_ID *idSession ); + Guid GetSessionId(); + + /// + /// Normalizes a local volume path or UNC share path so that it can be passed to the IVssBackupComponents::AddToSnapshotSet method. + /// + /// The path to be normalized. + /// Receives the root path that should be passed to the IVssBackupComponents::AddToSnapshotSet method. + /// + /// If pwszFilePath is a local path, this parameter receives the volume GUID name. If it's a UNC path, this parameter receives a + /// fully evaluated share path. + /// + /// + /// If pwszFilePath is a UNC share path, the server name portion can be + /// + /// + /// A host name + /// + /// + /// + /// A fully qualified domain name + /// + /// + /// + /// An IP address + /// + /// + /// + /// + /// This parameter specifies whether host name format or fully qualified domain name format should be used in the server name + /// portion of the normalized root path that is returned in the ppwszRootPath parameter. + /// + /// If this parameter is FALSE, simple host name format will be used. + /// The default value for this parameter is FALSE. + /// If this parameter is TRUE, fully qualified domain name will be used. + /// In a deployment where a host name could exist in multiple domain suffixes, this parameter should be TRUE. + /// + /// + /// + /// This method normalizes a local volume path or UNC share path and separates it into a root path and a logical prefix path. The + /// root path can then be passed to the IVssBackupComponents::AddToSnapshotSet method. + /// + /// + /// If pwszFilePath is a local volume path, the root path will be similar to a volume mount point. In this case, the root and the + /// logical prefix paths map to the results of GetVolumePathName and GetVolumeNameForVolumeMountPoint, respectively. + /// + /// + /// If pwszFilePath is a UNC share path, the root and logical prefix paths map to the root path of the file share and the fully + /// evaluated physical share path (which will take into account DFS and cluster deployment), respectively. + /// + /// + /// If you call this method more than once for the same shadow copy set creation operation, you must set the + /// bNormalizeFQDNforRootPath to the same value for every call. Fully qualified domain name format and host name format cannot be + /// mixed in the same shadow copy set. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssbackupcomponentsex4-getrootandlogicalprefixpaths + // HRESULT GetRootAndLogicalPrefixPaths( [in] VSS_PWSZ pwszFilePath, [out] VSS_PWSZ *ppwszRootPath, [out] VSS_PWSZ + // *ppwszLogicalPrefix, [in, optional] BOOL bNormalizeFQDNforRootPath ); + void GetRootAndLogicalPrefixPaths(string pwszFilePath, out string ppwszRootPath, + out string ppwszLogicalPrefix, bool bNormalizeFQDNforRootPath = false); + } + + /// + /// + /// The IVssExamineWriterMetadata interface is a C++ (not COM) interface that allows a requester to examine the metadata of a + /// specific writer instance. This metadata may come from a currently executing (live) writer, or it may have been stored as an XML document. + /// + /// An IVssExamineWriterMetadata interface to a live writer's metadata is obtained by a call to IVssBackupComponents::GetWriterMetadata. + /// + /// Metadata obtained from a stored XML document can be examined by an instance of IVssExamineWriterMetadata obtained by a call + /// to CreateVssExamineWriterMetadata. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nl-vsbackup-ivssexaminewritermetadata + [PInvokeData("vsbackup.h", MSDNShortId = "NL:vsbackup.IVssExamineWriterMetadata")] + public interface IVssExamineWriterMetadata + { + /// The AlternateLocationMappings property obtains alternate location mappings of a file set. + /// + /// + /// The value returned by IVssExamineWriterMetadata::GetAlternateLocationMapping should not be confused with that returned by IVssComponent::GetAlternateLocationMapping. + /// + /// IVssComponent::GetAlternateLocationMapping is the alternate location to which a file was restored. + /// + /// IVssExamineWriterMetadata::GetAlternateLocationMapping is the alternate location mapping to which a file may be restored + /// if necessary. + /// + /// A file should always be restored to its alternate location mapping if either of the following is true: + /// + /// + /// The restore method (set at backup time) is VSS_RME_RESTORE_TO_ALTERNATE_LOCATION. + /// + /// + /// Its restore target was set (at restore time) to VSS_RT_ALTERNATE. + /// + /// + /// In either case, if no valid alternate location mapping is defined, this constitutes a writer error. + /// A file may be restored to an alternate location mapping if either of the following is true: + /// + /// + /// The restore method is VSS_RME_RESTORE_IF_NOT_THERE and a version of the file is already present on disk. + /// + /// + /// The restore method is VSS_RME_RESTORE_IF_CAN_REPLACE and a version of the file is present on disk and cannot be replaced. + /// + /// + /// Again, if no valid alternate location mapping is defined, this constitutes a writer error. + /// + /// An alternate location mapping is used only during a restore operation and should not be confused with an alternate path, which + /// is used only during a backup operation. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadata-getalternatelocationmapping + // HRESULT GetAlternateLocationMapping( [in] UINT iMapping, [out] IVssWMFiledesc **ppFiledesc ); + IReadOnlyList AlternateLocationMappings { get; } + + /// + /// The BackupSchema property is used by a requester to determine from the Writer Metadata Document the types of backup + /// operations that a given writer can participate in. + /// + /// + /// The types of backup operations that a given writer supports, expressed as a bit mask (or bitwise OR) of VSS_BACKUP_SCHEMA + /// enumeration values. + /// + /// + /// + /// The default backup schema is VSS_BS_UNDEFINED: the writer supports only simple full backup and restoration of entire files (as + /// defined by VSS_BT_FULL), there is no support for incremental or differential backups, and partial files are not supported. + /// + /// The writer calls IVssCreateWriterMetadata::SetBackupSchema to indicate its supported schema in its Writer Metadata Document. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadata-getbackupschema HRESULT + // GetBackupSchema( DWORD *pdwSchemaMask ); + VSS_BACKUP_SCHEMA BackupSchema { get; } + + /// The Components property obtains the Writer Metadata Documents. + /// List of IVssWMComponent objects containing the component information. + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadata-getcomponent HRESULT + // GetComponent( [in] UINT iComponent, [out] IVssWMComponent **ppComponent ); + IReadOnlyList Components { get; } + + /// The ExcludeFiles property obtains information about files that have been explicitly excluded from backup. + /// For more information on excluding files, see Exclude File List Specification. + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadata-getexcludefile HRESULT + // GetExcludeFile( [in] UINT iFile, [out] IVssWMFiledesc **ppFiledesc ); + IReadOnlyList ExcludeFiles { get; } + + /// Obtains information about file sets that have been explicitly excluded. + /// + /// The GetExcludeFromSnapshotFile method is intended to report information about file sets excluded from a shadow copy. + /// Requesters should not exclude files from backup based on the information returned by this method. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadataex2-getexcludefromsnapshotfile + // HRESULT GetExcludeFromSnapshotFile( [in] UINT iFile, [out] IVssWMFiledesc **ppFiledesc ); + IReadOnlyList ExcludeFromSnapshotFiles { get; } + + /// Obtains the version information for a writer application. + /// The version of the writer application. + /// + /// The GetVersion method returns nonzero results only if the writer was initialized by calling the + /// CVssWriterEx::InitializeEx method and explicit version information was specified. If the writer is initialized by calling the + /// CVssWriter::Initialize method, or if no version information was specified in the call to the CVssWriterEx::InitializeEx + /// method, the GetVersion method returns zero in the Major and Minor fields. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadataex2-getversion HRESULT + // GetVersion( [out] DWORD *pdwMajorVersion, [out] DWORD *pdwMinorVersion ); + Version Version { get; } + + /// + /// The GetIdentityEx method obtains the writer instance name and other basic information about a specific writer instance. + /// + /// Globally unique identifier (GUID) of the writer instance. + /// GUID of the writer class. + /// A string specifying the name of the writer. + /// A string specifying the writer instance name. + /// A VSS_USAGE_TYPE enumeration value indicating how the data managed by the writer is used on the host system. + /// A VSS_SOURCE_TYPE enumeration value indicating the type of data managed by the writer. + /// + /// This method is identical to the IVssExamineWriterMetadata::GetIdentity method except for the pbstrInstanceName parameter. + /// The pbstrInstanceName parameter is the writer instance name that was specified during writer initialization by CVssWriter::Initialize. + /// + /// The writer instance name is useful for writers that support running multiple writer instances with the same writer class ID on a + /// single computer. The writer instance name can be used to identify the specific instance. Therefore, the writer must make the + /// instance name unique within the writer class. Also, the writer instance name is expected to persist between backup and restore, + /// and it is used by VSS to correctly restore multiple-instance writers. + /// + /// The caller must free the memory held by the pbstrWriterName and pbstrInstanceName parameters by calling SysFreeString. + /// + /// An IVssExamineWriterMetadataEx interface might be from stored writer state information (created by a call to + /// CreateVssExamineWriterMetadata). If this is the case, then the following are true: + /// + /// + /// + /// pidInstance may not mean anything in terms of live writers. + /// + /// + /// If pidWriter does not match the writer class of any live writer, a requester should not use that writer's components. + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadataex-getidentityex HRESULT + // GetIdentityEx( [out] VSS_ID *pidInstance, [out] VSS_ID *pidWriter, [out] BSTR *pbstrWriterName, [out] BSTR + // *pbstrInstanceName, [out] VSS_USAGE_TYPE *pUsage, [out] VSS_SOURCE_TYPE *pSource ); + void GetIdentity(out Guid pidInstance, out Guid pidWriter, out string pbstrWriterName, + out string pbstrInstanceName, out VSS_USAGE_TYPE pUsage, out VSS_SOURCE_TYPE pSource); + + /// The GetRestoreMethod method returns information about how a writer wants its data to be restored. + /// + /// A VSS_RESTOREMETHOD_ENUM value that specifies file overwriting, the use of alternate locations specifying the method that will + /// be used in the restore operation. + /// + /// + /// If the value of pMethod is VSS_RME_STOP_RESTORE_START or VSS_RME_RESTORE_STOP_START, a pointer to a string containing the name + /// of the service that is started and stopped. Otherwise, the value is . + /// + /// + /// Pointer to the URL of an HTML or XML document describing to the user how the restore is to be performed. The value may be . + /// + /// + /// A VSS_WRITERRESTORE_ENUM value specifying whether the writer will be involved in restoring its data. + /// + /// + /// A Boolean value indicating whether a reboot will be required after the restore operation is complete. The value receives + /// true if a reboot will be required, or false otherwise. + /// + /// Pointer to the number of alternate mappings associated with the writer. + /// + /// The caller must free the memory used by the pbstrUserProcedure and pbstrService parameters by calling SysFreeString. + /// A file should always be restored to its alternate location mapping if either of the following is true: + /// + /// + /// The restore method (set at backup time) is VSS_RME_RESTORE_TO_ALTERNATE_LOCATION. + /// + /// + /// Its restore target was set (at restore time) to VSS_RT_ALTERNATE. + /// + /// + /// In either case, if no valid alternate location mapping is defined, this constitutes a writer error. + /// A file can be restored to an alternate location mapping if : + /// + /// + /// The restore method is VSS_RME_RESTORE_IF_NOT_THERE and a version of the file is already present on disk. + /// + /// + /// The restore method is VSS_RME_RESTORE_IF_CAN_REPLACE and a version of the file is present on disk and cannot be replaced. + /// + /// + /// Again, if no valid alternate location mapping is defined, this constitutes a writer error. + /// + /// An alternate location mapping is used only during a restore operation and should not be confused with an alternate path, which + /// is used only during a backup operation. + /// + /// For more information about restore methods, see Setting VSS Restore Methods. + /// + /// If the restore method is VSS_RME_STOP_RESTORE_START or VSS_RME_RESTORE_STOP_START, a requester uses the name returned by + /// pbstrService to determine which service must be stopped during and then restarted after restore. See Stopping Services For + /// Restore by Requesters for information on writer participation in stopping and restarting services during a restore operation. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadata-getrestoremethod HRESULT + // GetRestoreMethod( [out] VSS_RESTOREMETHOD_ENUM *pMethod, [out] BSTR *pbstrService, [out] BSTR *pbstrUserProcedure, [out] + // VSS_WRITERRESTORE_ENUM *pwriterRestore, [out] bool *pbRebootRequired, [out] UINT *pcMappings ); + void GetRestoreMethod(out VSS_RESTOREMETHOD_ENUM pMethod, out string pbstrService, out string pbstrUserProcedure, + out VSS_WRITERRESTORE_ENUM pwriterRestore, out bool pbRebootRequired, out uint pcMappings); + + /// + /// The LoadFromXML method loads an XML document that contains a writer's metadata document into an IVssExamineWriterMetadata interface. + /// + /// String that contains an XML document that represents a writer's metadata document. + /// + /// + /// This method is used at restore time to load writer metadata that was saved by IVssExamineWriterMetadata::SaveAsXML at the time + /// of the backup operation. + /// + /// Users should not tamper with this metadata document. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadata-loadfromxml HRESULT + // LoadFromXML( [in] BSTR bstrXML ); + void LoadFromXML(string bstrXML); + + /// + /// The SaveAsXML method saves the Writer Metadata Document that contains a writer's state information to a specified string. + /// This string can be saved as part of a backup operation. + /// + /// The Writer Metadata Document that contains a writer's state information. + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivssexaminewritermetadata-saveasxml HRESULT SaveAsXML( + // [in] BSTR *pbstrXML ); + string SaveAsXML(); + } + + /// + /// + /// The IVssWMComponent is a C++ (not COM) interface that allows access to component information stored in a Writer Metadata Document. + /// + /// Instances of IVssWMComponent are obtained by calling IVssExamineWriterMetadata::GetComponent. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nl-vsbackup-ivsswmcomponent + [PInvokeData("vsbackup.h", MSDNShortId = "NL:vsbackup.IVssWMComponent")] + public interface IVssWMComponent + { + /// + /// The DatabaseFiles property obtains a list of IVssWMFiledesc objects containing information about the database backup + /// component files. + /// + /// List of IVssWMFiledesc objects containing the returned file descriptor information. + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivsswmcomponent-getdatabasefile HRESULT GetDatabaseFile( + // [in] UINT iDBFile, [out] IVssWMFiledesc **ppFiledesc ); + IReadOnlyList DatabaseFiles { get; } + + /// + /// The DatabaseLogFiles property obtains file descriptors for the log file associated with the database backup component. + /// + /// List of IVssWMFiledesc objects containing the returned file descriptor information. + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivsswmcomponent-getdatabaselogfile HRESULT + // GetDatabaseLogFile( [in] UINT iDbLogFile, [out] IVssWMFiledesc **ppFiledesc ); + IReadOnlyList DatabaseLogFiles { get; } + + /// + /// The Dependencies property returns a list of IVssWMDependency interfaces containing accessors for obtaining information + /// about explicit writer-component dependencies of the current components. + /// + /// List of IVssWMDependency interfaces. + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivsswmcomponent-getdependency HRESULT GetDependency( [in] + // UINT iDependency, [out] IVssWMDependency **ppDependency ); + IReadOnlyList Dependencies { get; } + + /// The Files property obtains the file descriptors associated with the component. + /// List of IVssWMFiledesc objects containing the returned file descriptor information. + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivsswmcomponent-getfile HRESULT GetFile( [in] UINT iFile, + // [out] IVssWMFiledesc **ppFiledesc ); + IReadOnlyList Files { get; } + + /// The GetComponentInfo method obtains basic information about the specified writer metadata component. + /// Doubly indirect pointer to a structure containing the returned component information. + /// The caller is responsible for freeing the returned VSS_COMPONENTINFO structure by calling IVssWMComponent::FreeComponentInfo. + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-ivsswmcomponent-getcomponentinfo HRESULT + // GetComponentInfo( [out] PVSSCOMPONENTINFO *ppInfo ); + VSS_COMPONENTINFO GetComponentInfo(); + } + + /// + /// + /// The IVssWriterComponentsExt interface is a C++ (not COM) interface used by requesters to access and modify the components of + /// a writer involved in a backup. + /// + /// + /// IVssWriterComponentsExt is returned by IVssBackupComponents::GetWriterComponents and inherits from IVssWriterComponents and IUnknown. + /// + /// + /// Note During the restore phase, the requester should call IVssWriterComponentsExt::GetComponent or + /// IVssWriterComponentsExt::GetComponentCount only after the call to IVssBackupComponents::PreRestore has returned, to allow time for + /// the writer to update the Backup Components Document. One example of such an update would be to change the restore target. + /// + /// + /// Life cycle management of IVssWriterComponentsExt is handled through the inherited IUnknown methods. Specifically, an + /// application is responsible for calling IUnknown::Release to release resources held by an IVssWriterComponentsExt object. + /// + /// IVssWriterComponentsExt does not define any methods. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nl-vsbackup-ivsswritercomponentsext + [PInvokeData("vsbackup.h", MSDNShortId = "NL:vsbackup.IVssWriterComponentsExt")] + //[ComVisible(true)] + public interface IVssWriterComponentsExt : IVssWriterComponents + { + } + + /// + /// The VSS_COMPONENTINFO structure contains information about a given component, and is returned to requesters by the + /// IVssWMComponent interface. + /// + /// + /// + /// To obtain VSS_COMPONENTINFO object for a given component, a requester must first obtain the corresponding IVssWMComponent + /// object through a call to IVssExamineWriterMetadata::GetComponent. A call to IVssWMComponent::GetComponentInfo then allocates and + /// returns a VSS_COMPONENTINFO structure. + /// + /// + /// Because VSS_COMPONENTINFO is allocated and returned by IVssWMComponent::GetComponentInfo, a requester should not free a + /// VSS_COMPONENTINFO object directly, but should use IVssWMComponent::FreeComponentInfo. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/ns-vsbackup-vss_componentinfo typedef struct _VSS_COMPONENTINFO { + // VSS_COMPONENT_TYPE type; BSTR bstrLogicalPath; BSTR bstrComponentName; BSTR bstrCaption; BYTE *pbIcon; UINT cbIcon; bool + // bRestoreMetadata; bool bNotifyOnBackupComplete; bool bSelectable; bool bSelectableForRestore; DWORD dwComponentFlags; UINT + // cFileCount; UINT cDatabases; UINT cLogFiles; UINT cDependencies; } VSS_COMPONENTINFO; + [PInvokeData("vsbackup.h", MSDNShortId = "NS:vsbackup._VSS_COMPONENTINFO")] + [StructLayout(LayoutKind.Sequential)] + public struct VSS_COMPONENTINFO + { + /// Component type. See VSS_COMPONENT_TYPE. + public VSS_COMPONENT_TYPE type; + + /// + /// A string containing the logical path of the component. + /// A logical path can be . + /// There are no restrictions on the characters that can appear in a non- logical path. + /// + public string bstrLogicalPath; + + /// A string containing the name of the component. A component name string cannot be . + public string bstrComponentName; + + /// A string containing the description of the component. A caption string can be . + public string bstrCaption; + + /// + /// + /// A buffer containing the binary data for a displayable icon representing the component. The buffer contents should use the same + /// format as the standard icon(.ico) files. The size, in bytes, of the buffer is specified by cbIcon. + /// + /// If the writer that created the component did not choose to specify an icon, pbIcon is . + /// + public byte[] pbIcon; + + /// + /// + /// Boolean that indicates whether there is private metadata associated with the restoration of the component. The Boolean is + /// true if there is metadata and false if there is not. + /// + /// + /// A writer indicates whether a component supports private metadata by setting this value when a component is added with + /// IVssCreateWriterMetadata::AddComponent. Writers later add restore metadata with IVssComponent::SetRestoreMetadata. Requesters + /// retrieve the information using IVssComponent::GetRestoreMetadata. + /// + /// + public bool bRestoreMetadata; + + /// Reserved for future use. The value of this parameter should always be set to false. + public bool bNotifyOnBackupComplete; + + /// + /// + /// Boolean that indicates(for component mode operations) if the component is selectable for backup. The value of bSelectable + /// helps determine whether a requester has the option of including or excluding a given component in backup operations. The Boolean + /// is true if the component is selectable for backup and false if it is not. + /// + /// + /// There is no default value for a component's selectability for backup. A writer must always explicitly set the value when it adds + /// the component to its Writer Metadata Document using IVssCreateWriterMetadata::AddComponent. + /// + /// + /// In addition, the value of bSelectable, the component's logical path, and the component's relationship to other components + /// as expressed in that path determine when and how a component is included in a backup operation: + /// + /// + /// + /// + /// For a nonselectable for backup component( bSelectable is false) with no selectable for backup ancestors in the + /// hierarchy of its logical path, inclusion in the backup set is always mandatory and always implicit. A requester explicitly adds + /// the component to the backup set in the Backup Components Document with IVssBackupComponents::AddComponent. + /// + /// + /// + /// + /// For a selectable for backup component( bSelectable is true) with no selectable for backup ancestor in the + /// hierarchy of its logical paths, inclusion in the backup set is always optional and always explicit. A requester explicitly adds + /// the component to the backup set in the Backup Components Document with IVssBackupComponents::AddComponent. + /// + /// If such a component is included as an ancestor in the logical path of other components, both those that are selectable for + /// backup and those that are not, it defines a component set containing these other components as subcomponents. If a selectable + /// for backup component is explicitly included in a backup, these subcomponents are implicitly included in the backup. + /// + /// + /// + /// + /// + /// For a nonselectable for backup component( bSelectable is false) that has a selectable for backup ancestor in the + /// hierarchy of its logical paths(and are therefore part of a component set defined by that ancestor), inclusion in the backup set + /// is always implicit and contingent on the inclusion of a selectable for backup ancestor. A requester never explicitly adds the + /// component to the backup set in the Backup Components Document; instead, it adds the selectable for backup ancestor to the + /// document using IVssBackupComponents::AddComponent. + /// + /// + /// + /// + /// For a selectable for backup component( bSelectable is true) that has a selectable for backup ancestor in the + /// hierarchy of its logical paths(and is therefore part of a component set defined by that ancestor), inclusion in the backup set + /// can be either optional and explicit, or if the component is not explicitly selected, its inclusion may be implicit and + /// contingent on the inclusion of a selectable for backup ancestor. If the inclusion of the component is explicit, a requester + /// explicitly adds the components to the backup set in the Backup Components Document with IVssBackupComponents::AddComponent. + /// If the inclusion is implicit, a requester does not add these components to a backup set in the Backup Components Document. + /// + /// If the inclusion of the component is explicit and the component defines a component set, the members of that component set are + /// implicitly selected. + /// + /// + /// A writer sets a component's selectability for backup( bSelectable) when adding the component to the Writer Metadata + /// Document by using IVssCreateWriterMetadata::AddComponent. + /// + /// See Working with Selectability and Logical Paths for more information. + /// + /// + /// + /// + public bool bSelectable; + + /// + /// + /// Boolean that indicates(for component-mode operations) whether the component is selectable for restore. + /// bSelectableForRestore allows the requester to determine whether this component can be individually selected for restore + /// if it had earlier been implicitly included in the backup. The Boolean is true if the component is selectable for restore + /// and false if it is not. + /// + /// + /// By default, a component's selectability for restore is false. A writer can override this default when it adds the + /// component to its Writer Metadata Document using IVssCreateWriterMetadata::AddComponent. + /// + /// + /// If a component is explicitly added to the backup document(see explicit component inclusion), then it can always be individually + /// selected for restore; so this flag then has no meaning. If a component is implicitly added to the backup document, then the + /// bSelectableForRestore flag determines whether the component can be individually restored using IVssBackupComponents::AddRestoreSubcomponent. + /// + /// See Working with Selectability and Logical Paths for more information. + /// + public bool bSelectableForRestore; + + /// + /// A bit mask(or bitwise OR) of values of the VSS_COMPONENT_FLAGS enumeration, indicating the features this component supports. + /// Windows Server 2003 and Windows XP: Before Windows Server 2003 with SP1, this member is reserved for system use. + /// + public VSS_COMPONENT_FLAGS dwComponentFlags; + + /// + /// If the component is a file group, the number of file descriptors for files in the group. Otherwise, this value is zero. + /// + public uint cFileCount; + + /// If the component is a database, the number of database file descriptors. Otherwise, this value is zero. + public uint cDatabases; + + /// + /// If the component is a database, the number of database log file descriptors. Otherwise, the value of this parameter is zero. + /// + public uint cLogFiles; + + /// + /// The number of explicit writer-component dependencies of the current component. This value is incremented when + /// IVssCreateWriterMetadata::AddComponentDependency is called by a writer. + /// + public uint cDependencies; + } + + /// VSS functions. + public static partial class Methods + { + private const string Lib_VssApi = "vssapi.dll"; /// /// The IsVolumeSnapshotted function determines whether any shadow copies exist for the specified volume. @@ -3724,8 +2664,8 @@ namespace Vanara.PInvoke /// /// /// - /// A pointer to a variable that receives true if the volume contains components from any writers that are listed in the - /// registry as writers that should block revert operations, or false otherwise. + /// A variable that receives true if the volume contains components from any writers that are listed in the registry as + /// writers that should block revert operations, or false otherwise. /// /// /// This function can return one of these values. @@ -3769,245 +2709,5 @@ namespace Vanara.PInvoke [DllImport(Lib_VssApi, SetLastError = false, ExactSpelling = true, EntryPoint = "ShouldBlockRevertInternal")] [PInvokeData("vsbackup.h", MSDNShortId = "NF:vsbackup.ShouldBlockRevert")] public static extern HRESULT ShouldBlockRevert([MarshalAs(UnmanagedType.LPWStr)] string wszVolumeName, [MarshalAs(UnmanagedType.Bool)] out bool pbBlock); - - /// - /// - /// The VssFreeSnapshotProperties function is used to free the contents of a VSS_SNAPSHOT_PROP structure as part of managing - /// its life cycle. The VSS_SNAPSHOT_PROP structure is typically obtained by using the - /// IVssBackupComponents::GetSnapshotProperties method or the IVssSoftwareSnapshotProvider::GetSnapshotProperties method. - /// - /// This function can also be used to initialize a VSS_SNAPSHOT_PROP structure before use or before freeing the structure. - /// - /// Note This function is exported as VssFreeSnapshotPropertiesInternal, but you should call - /// VssFreeSnapshotProperties, not VssFreeSnapshotPropertiesInternal. - /// - /// - /// Pointer to a valid VSS_SNAPSHOT_PROP object. - /// None - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nf-vsbackup-vssfreesnapshotproperties void VssFreeSnapshotProperties( - // [in] VSS_SNAPSHOT_PROP *pProp); - [DllImport(Lib_VssApi, SetLastError = false, CharSet = CharSet.Unicode, EntryPoint = "VssFreeSnapshotPropertiesInternal")] - [PInvokeData("vsbackup.h", MSDNShortId = "NF:vsbackup.VssFreeSnapshotProperties")] - public static extern void VssFreeSnapshotProperties(in VSS_SNAPSHOT_PROP pProp); - - /// - /// The VSS_COMPONENTINFO structure contains information about a given component, and is returned to requesters by the - /// IVssWMComponent interface. - /// - /// - /// - /// To obtain VSS_COMPONENTINFO object for a given component, a requester must first obtain the corresponding IVssWMComponent - /// object through a call to IVssExamineWriterMetadata::GetComponent. A call to IVssWMComponent::GetComponentInfo then allocates and - /// returns a VSS_COMPONENTINFO structure. - /// - /// - /// Because VSS_COMPONENTINFO is allocated and returned by IVssWMComponent::GetComponentInfo, a requester should not free a - /// VSS_COMPONENTINFO object directly, but should use IVssWMComponent::FreeComponentInfo. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/ns-vsbackup-vss_componentinfo typedef struct _VSS_COMPONENTINFO { - // VSS_COMPONENT_TYPE type; BSTR bstrLogicalPath; BSTR bstrComponentName; BSTR bstrCaption; BYTE *pbIcon; UINT cbIcon; bool - // bRestoreMetadata; bool bNotifyOnBackupComplete; bool bSelectable; bool bSelectableForRestore; DWORD dwComponentFlags; UINT - // cFileCount; UINT cDatabases; UINT cLogFiles; UINT cDependencies; } VSS_COMPONENTINFO; - [PInvokeData("vsbackup.h", MSDNShortId = "NS:vsbackup._VSS_COMPONENTINFO")] - [StructLayout(LayoutKind.Sequential)] - public struct VSS_COMPONENTINFO - { - /// Component type. See VSS_COMPONENT_TYPE. - public VSS_COMPONENT_TYPE type; - - /// - /// A string containing the logical path of the component. - /// A logical path can be NULL. - /// There are no restrictions on the characters that can appear in a non- NULL logical path. - /// - [MarshalAs(UnmanagedType.BStr)] - public string bstrLogicalPath; - - /// A string containing the name of the component. A component name string cannot be NULL. - [MarshalAs(UnmanagedType.BStr)] - public string bstrComponentName; - - /// A string containing the description of the component. A caption string can be NULL. - [MarshalAs(UnmanagedType.BStr)] - public string bstrCaption; - - /// - /// - /// Pointer to a buffer containing the binary data for a displayable icon representing the component. The buffer contents should - /// use the same format as the standard icon(.ico) files. The size, in bytes, of the buffer is specified by cbIcon. - /// - /// If the writer that created the component did not choose to specify an icon, pbIcon is NULL. - /// - public IntPtr pbIcon; - - /// - /// The size, in bytes, of the displayable icon( pbIcon) representing the component. If pbIcon is NULL, - /// cbIcon should be zero. - /// - public uint cbIcon; - - /// - /// - /// Boolean that indicates whether there is private metadata associated with the restoration of the component. The Boolean is - /// true if there is metadata and false if there is not. - /// - /// - /// A writer indicates whether a component supports private metadata by setting this value when a component is added with - /// IVssCreateWriterMetadata::AddComponent. Writers later add restore metadata with IVssComponent::SetRestoreMetadata. - /// Requesters retrieve the information using IVssComponent::GetRestoreMetadata. - /// - /// - [MarshalAs(UnmanagedType.Bool)] - public bool bRestoreMetadata; - - /// Reserved for future use. The value of this parameter should always be set to false. - [MarshalAs(UnmanagedType.Bool)] - public bool bNotifyOnBackupComplete; - - /// - /// - /// Boolean that indicates(for component mode operations) if the component is selectable for backup. The value of - /// bSelectable helps determine whether a requester has the option of including or excluding a given component in backup - /// operations. The Boolean is true if the component is selectable for backup and false if it is not. - /// - /// - /// There is no default value for a component's selectability for backup. A writer must always explicitly set the value when it - /// adds the component to its Writer Metadata Document using IVssCreateWriterMetadata::AddComponent. - /// - /// - /// In addition, the value of bSelectable, the component's logical path, and the component's relationship to other - /// components as expressed in that path determine when and how a component is included in a backup operation: - /// - /// - /// - /// - /// For a nonselectable for backup component( bSelectable is false) with no selectable for backup ancestors in the - /// hierarchy of its logical path, inclusion in the backup set is always mandatory and always implicit. A requester explicitly - /// adds the component to the backup set in the Backup Components Document with IVssBackupComponents::AddComponent. - /// - /// - /// - /// - /// For a selectable for backup component( bSelectable is true) with no selectable for backup ancestor in the - /// hierarchy of its logical paths, inclusion in the backup set is always optional and always explicit. A requester explicitly - /// adds the component to the backup set in the Backup Components Document with IVssBackupComponents::AddComponent. - /// - /// If such a component is included as an ancestor in the logical path of other components, both those that are selectable for - /// backup and those that are not, it defines a component set containing these other components as subcomponents. If a - /// selectable for backup component is explicitly included in a backup, these subcomponents are implicitly included in the backup. - /// - /// - /// - /// - /// - /// For a nonselectable for backup component( bSelectable is false) that has a selectable for backup ancestor in - /// the hierarchy of its logical paths(and are therefore part of a component set defined by that ancestor), inclusion in the - /// backup set is always implicit and contingent on the inclusion of a selectable for backup ancestor. A requester never - /// explicitly adds the component to the backup set in the Backup Components Document; instead, it adds the selectable for - /// backup ancestor to the document using IVssBackupComponents::AddComponent. - /// - /// - /// - /// - /// For a selectable for backup component( bSelectable is true) that has a selectable for backup ancestor in the - /// hierarchy of its logical paths(and is therefore part of a component set defined by that ancestor), inclusion in the backup - /// set can be either optional and explicit, or if the component is not explicitly selected, its inclusion may be implicit and - /// contingent on the inclusion of a selectable for backup ancestor. If the inclusion of the component is explicit, a requester - /// explicitly adds the components to the backup set in the Backup Components Document with IVssBackupComponents::AddComponent. - /// If the inclusion is implicit, a requester does not add these components to a backup set in the Backup Components Document. - /// - /// If the inclusion of the component is explicit and the component defines a component set, the members of that component set - /// are implicitly selected. - /// - /// - /// A writer sets a component's selectability for backup( bSelectable) when adding the component to the Writer Metadata - /// Document by using IVssCreateWriterMetadata::AddComponent. - /// - /// See Working with Selectability and Logical Paths for more information. - /// - /// - /// - /// - [MarshalAs(UnmanagedType.Bool)] - public bool bSelectable; - - /// - /// - /// Boolean that indicates(for component-mode operations) whether the component is selectable for restore. - /// bSelectableForRestore allows the requester to determine whether this component can be individually selected for - /// restore if it had earlier been implicitly included in the backup. The Boolean is true if the component is selectable - /// for restore and false if it is not. - /// - /// - /// By default, a component's selectability for restore is false. A writer can override this default when it adds the - /// component to its Writer Metadata Document using IVssCreateWriterMetadata::AddComponent. - /// - /// - /// If a component is explicitly added to the backup document(see explicit component inclusion), then it can always be - /// individually selected for restore; so this flag then has no meaning. If a component is implicitly added to the backup - /// document, then the bSelectableForRestore flag determines whether the component can be individually restored using IVssBackupComponents::AddRestoreSubcomponent. - /// - /// See Working with Selectability and Logical Paths for more information. - /// - [MarshalAs(UnmanagedType.Bool)] - public bool bSelectableForRestore; - - /// - /// - /// A bit mask(or bitwise OR) of values of the VSS_COMPONENT_FLAGS enumeration, indicating the features this component supports. - /// - /// - /// Windows Server 2003 and Windows XP: Before Windows Server 2003 with SP1, this member is reserved for system use. - /// - /// - public VSS_COMPONENT_FLAGS dwComponentFlags; - - /// - /// If the component is a file group, the number of file descriptors for files in the group. Otherwise, this value is zero. - /// - public uint cFileCount; - - /// If the component is a database, the number of database file descriptors. Otherwise, this value is zero. - public uint cDatabases; - - /// - /// If the component is a database, the number of database log file descriptors. Otherwise, the value of this parameter is zero. - /// - public uint cLogFiles; - - /// - /// The number of explicit writer-component dependencies of the current component. This value is incremented when - /// IVssCreateWriterMetadata::AddComponentDependency is called by a writer. - /// - public uint cDependencies; - } - - /// - /// - /// The IVssWriterComponentsExt interface is a C++ (not COM) interface used by requesters to access and modify the components - /// of a writer involved in a backup. - /// - /// - /// IVssWriterComponentsExt is returned by IVssBackupComponents::GetWriterComponents and inherits from IVssWriterComponents - /// and IUnknown. - /// - /// - /// Note During the restore phase, the requester should call IVssWriterComponentsExt::GetComponent or - /// IVssWriterComponentsExt::GetComponentCount only after the call to IVssBackupComponents::PreRestore has returned, to allow time - /// for the writer to update the Backup Components Document. One example of such an update would be to change the restore target. - /// - /// - /// Life cycle management of IVssWriterComponentsExt is handled through the inherited IUnknown methods. Specifically, an - /// application is responsible for calling IUnknown::Release to release resources held by an IVssWriterComponentsExt object. - /// - /// IVssWriterComponentsExt does not define any methods. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsbackup/nl-vsbackup-ivsswritercomponentsext - [PInvokeData("vsbackup.h", MSDNShortId = "NL:vsbackup.IVssWriterComponentsExt")] - [ComVisible(true)] - private class IVssWriterComponentsExt : IVssWriterComponents - { - } } } \ No newline at end of file diff --git a/PInvoke/VssApi/vsmgmt.cs b/PInvoke/VssApi/vsmgmt.cs index 0bcd47af..3ab279fe 100644 --- a/PInvoke/VssApi/vsmgmt.cs +++ b/PInvoke/VssApi/vsmgmt.cs @@ -3,893 +3,1033 @@ using System.Collections.Generic; using System.Runtime.InteropServices; using Vanara.Collections; -namespace Vanara.PInvoke +namespace Vanara.PInvoke.VssApi { - public static partial class VssApi + /// + /// The VSS_MGMT_OBJECT_TYPE enumeration type is a discriminant for the VSS_MGMT_OBJECT_UNION union within the + /// VSS_MGMT_OBJECT_PROP structure. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/ne-vsmgmt-vss_mgmt_object_type typedef enum _VSS_MGMT_OBJECT_TYPE { + // VSS_MGMT_OBJECT_UNKNOWN, VSS_MGMT_OBJECT_VOLUME, VSS_MGMT_OBJECT_DIFF_VOLUME, VSS_MGMT_OBJECT_DIFF_AREA } VSS_MGMT_OBJECT_TYPE, *PVSS_MGMT_OBJECT_TYPE; + [PInvokeData("vsmgmt.h", MSDNShortId = "NE:vsmgmt._VSS_MGMT_OBJECT_TYPE")] + public enum VSS_MGMT_OBJECT_TYPE { - /// Denotes that no maximum space is specified in AddDiffArea or ChangeDiffAreaMaximumSize - public const long VSS_ASSOC_NO_MAX_SPACE = -1; + /// The object type is unknown. + VSS_MGMT_OBJECT_UNKNOWN = 0, - /// If this constant is specified in ChangeDiffAreaMaximumSize then the association is removed - public const long VSS_ASSOC_REMOVE = 0; + /// The object is a volume to be shadow copied. + VSS_MGMT_OBJECT_VOLUME, + + /// The object is a volume to hold a shadow copy storage area. + VSS_MGMT_OBJECT_DIFF_VOLUME, + + /// The object is an association between a volume to be shadow copied and a volume to hold the shadow copy storage area. + VSS_MGMT_OBJECT_DIFF_AREA, + } + + /// + /// Defines the set of shadow copy protection faults. A shadow copy protection fault occurs when the VSS service is unable to perform a + /// copy-on-write operation to the shadow copy storage area (also called the diff area). + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/ne-vsmgmt-vss_protection_fault typedef enum _VSS_PROTECTION_FAULT { + // VSS_PROTECTION_FAULT_NONE, VSS_PROTECTION_FAULT_DIFF_AREA_MISSING, VSS_PROTECTION_FAULT_IO_FAILURE_DURING_ONLINE, + // VSS_PROTECTION_FAULT_META_DATA_CORRUPTION, VSS_PROTECTION_FAULT_MEMORY_ALLOCATION_FAILURE, + // VSS_PROTECTION_FAULT_MAPPED_MEMORY_FAILURE, VSS_PROTECTION_FAULT_COW_READ_FAILURE, VSS_PROTECTION_FAULT_COW_WRITE_FAILURE, + // VSS_PROTECTION_FAULT_DIFF_AREA_FULL, VSS_PROTECTION_FAULT_GROW_TOO_SLOW, VSS_PROTECTION_FAULT_GROW_FAILED, + // VSS_PROTECTION_FAULT_DESTROY_ALL_SNAPSHOTS, VSS_PROTECTION_FAULT_FILE_SYSTEM_FAILURE, VSS_PROTECTION_FAULT_IO_FAILURE, + // VSS_PROTECTION_FAULT_DIFF_AREA_REMOVED, VSS_PROTECTION_FAULT_EXTERNAL_WRITER_TO_DIFF_AREA, + // VSS_PROTECTION_FAULT_MOUNT_DURING_CLUSTER_OFFLINE } VSS_PROTECTION_FAULT, *PVSS_PROTECTION_FAULT; + [PInvokeData("vsmgmt.h", MSDNShortId = "NE:vsmgmt._VSS_PROTECTION_FAULT")] + public enum VSS_PROTECTION_FAULT + { + /// No shadow copy protection fault has occurred. + VSS_PROTECTION_FAULT_NONE = 0, /// - /// The VSS_MGMT_OBJECT_TYPE enumeration type is a discriminant for the VSS_MGMT_OBJECT_UNION union within the - /// VSS_MGMT_OBJECT_PROP structure. + /// The volume that contains the shadow copy storage area could not be found. Usually this fault means that the volume has not yet + /// arrived in the system. /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/ne-vsmgmt-vss_mgmt_object_type typedef enum _VSS_MGMT_OBJECT_TYPE { - // VSS_MGMT_OBJECT_UNKNOWN, VSS_MGMT_OBJECT_VOLUME, VSS_MGMT_OBJECT_DIFF_VOLUME, VSS_MGMT_OBJECT_DIFF_AREA } VSS_MGMT_OBJECT_TYPE, *PVSS_MGMT_OBJECT_TYPE; - [PInvokeData("vsmgmt.h", MSDNShortId = "NE:vsmgmt._VSS_MGMT_OBJECT_TYPE")] - public enum VSS_MGMT_OBJECT_TYPE - { - /// The object type is unknown. - VSS_MGMT_OBJECT_UNKNOWN = 0, + VSS_PROTECTION_FAULT_DIFF_AREA_MISSING, - /// The object is a volume to be shadow copied. - VSS_MGMT_OBJECT_VOLUME, + /// The volume that contains the shadow copy storage area could not be brought online because an I/O failure occurred. + VSS_PROTECTION_FAULT_IO_FAILURE_DURING_ONLINE, - /// The object is a volume to hold a shadow copy storage area. - VSS_MGMT_OBJECT_DIFF_VOLUME, - - /// - /// The object is an association between a volume to be shadow copied and a volume to hold the shadow copy storage area. - /// - VSS_MGMT_OBJECT_DIFF_AREA, - } + /// The shadow copy metadata for the shadow copy storage area has been corrupted. + VSS_PROTECTION_FAULT_META_DATA_CORRUPTION, /// - /// Defines the set of shadow copy protection faults. A shadow copy protection fault occurs when the VSS service is unable to - /// perform a copy-on-write operation to the shadow copy storage area (also called the diff area). + /// A memory allocation failure occurred. This could be caused by a temporary low-memory condition that does not happen again after + /// you clear the fault and restart the shadow copy operation. /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/ne-vsmgmt-vss_protection_fault typedef enum _VSS_PROTECTION_FAULT { - // VSS_PROTECTION_FAULT_NONE, VSS_PROTECTION_FAULT_DIFF_AREA_MISSING, VSS_PROTECTION_FAULT_IO_FAILURE_DURING_ONLINE, - // VSS_PROTECTION_FAULT_META_DATA_CORRUPTION, VSS_PROTECTION_FAULT_MEMORY_ALLOCATION_FAILURE, - // VSS_PROTECTION_FAULT_MAPPED_MEMORY_FAILURE, VSS_PROTECTION_FAULT_COW_READ_FAILURE, VSS_PROTECTION_FAULT_COW_WRITE_FAILURE, - // VSS_PROTECTION_FAULT_DIFF_AREA_FULL, VSS_PROTECTION_FAULT_GROW_TOO_SLOW, VSS_PROTECTION_FAULT_GROW_FAILED, - // VSS_PROTECTION_FAULT_DESTROY_ALL_SNAPSHOTS, VSS_PROTECTION_FAULT_FILE_SYSTEM_FAILURE, VSS_PROTECTION_FAULT_IO_FAILURE, - // VSS_PROTECTION_FAULT_DIFF_AREA_REMOVED, VSS_PROTECTION_FAULT_EXTERNAL_WRITER_TO_DIFF_AREA, - // VSS_PROTECTION_FAULT_MOUNT_DURING_CLUSTER_OFFLINE } VSS_PROTECTION_FAULT, *PVSS_PROTECTION_FAULT; - [PInvokeData("vsmgmt.h", MSDNShortId = "NE:vsmgmt._VSS_PROTECTION_FAULT")] - public enum VSS_PROTECTION_FAULT - { - /// No shadow copy protection fault has occurred. - VSS_PROTECTION_FAULT_NONE = 0, - - /// - /// The volume that contains the shadow copy storage area could not be found. Usually this fault means that the volume has not - /// yet arrived in the system. - /// - VSS_PROTECTION_FAULT_DIFF_AREA_MISSING, - - /// The volume that contains the shadow copy storage area could not be brought online because an I/O failure occurred. - VSS_PROTECTION_FAULT_IO_FAILURE_DURING_ONLINE, - - /// The shadow copy metadata for the shadow copy storage area has been corrupted. - VSS_PROTECTION_FAULT_META_DATA_CORRUPTION, - - /// - /// A memory allocation failure occurred. This could be caused by a temporary low-memory condition that does not happen again - /// after you clear the fault and restart the shadow copy operation. - /// - VSS_PROTECTION_FAULT_MEMORY_ALLOCATION_FAILURE, - - /// - /// A memory mapping failure occurred. This fault could mean that the page file is too small, or it could be caused by a - /// low-memory condition. - /// - VSS_PROTECTION_FAULT_MAPPED_MEMORY_FAILURE, - - /// - /// A read failure occurred during the copy-on-write operation when data was being copied from the live volume to the shadow - /// copy storage area volume. - /// - VSS_PROTECTION_FAULT_COW_READ_FAILURE, - - /// - /// A read or write failure occurred during the copy-on-write operation when data was being copied from the live volume to the - /// shadow copy storage area volume. One possible reason is that the shadow copy storage area volume has been removed from the system. - /// - VSS_PROTECTION_FAULT_COW_WRITE_FAILURE, - - /// - /// - /// This failure means that either the shadow copy storage area is full or the shadow copy storage area volume is full. After - /// clearing the protection fault, you can do one of the following: - /// - /// - /// - /// - /// Delete unused shadow copy storage areas by calling the IVssDifferentialSoftwareSnapshotMgmt3::DeleteUnusedDiffAreas method. - /// - /// - /// - /// - /// Increase the shadow copy storage area maximum size for the volume by calling the - /// IVssDifferentialSoftwareSnapshotMgmt::ChangeDiffAreaMaximumSize method or the - /// IVssDifferentialSoftwareSnapshotMgmt2::ChangeDiffAreaMaximumSizeEx method. - /// - /// - /// - /// - VSS_PROTECTION_FAULT_DIFF_AREA_FULL, - - /// - /// The size of the shadow copy storage area could not be increased because there was no longer enough space on the shadow copy - /// storage area volume. - /// - VSS_PROTECTION_FAULT_GROW_TOO_SLOW, - - /// The size of the shadow copy storage area could not be increased. - VSS_PROTECTION_FAULT_GROW_FAILED, - - /// An unexpected error occurred. - VSS_PROTECTION_FAULT_DESTROY_ALL_SNAPSHOTS, - - /// - /// Either the shadow copy storage area files could not be opened or the shadow copy storage area volume could not be mounted - /// because of a file system operation failure. - /// - VSS_PROTECTION_FAULT_FILE_SYSTEM_FAILURE, - - /// A read or write failure occurred on the shadow copy storage area volume. - VSS_PROTECTION_FAULT_IO_FAILURE, - - /// The shadow copy storage area volume was removed from the system or could not be accessed for some other reason. - VSS_PROTECTION_FAULT_DIFF_AREA_REMOVED, - - /// Another application attempted to write to the shadow copy storage area. - VSS_PROTECTION_FAULT_EXTERNAL_WRITER_TO_DIFF_AREA, - - /// - VSS_PROTECTION_FAULT_MOUNT_DURING_CLUSTER_OFFLINE, - } - - /// Defines the set of volume shadow copy protection levels. - /// - /// When a volume is in shadow copy protection mode, requesters must set shadow copy storage area (diff area) associations using the - /// IVssDifferentialSoftwareSnapshotMgmt::AddDiffArea method. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/VsMgmt/ne-vsmgmt-vss_protection_level typedef enum _VSS_PROTECTION_LEVEL { - // VSS_PROTECTION_LEVEL_ORIGINAL_VOLUME, VSS_PROTECTION_LEVEL_SNAPSHOT } VSS_PROTECTION_LEVEL, *PVSS_PROTECTION_LEVEL; - [PInvokeData("vsmgmt.h", MSDNShortId = "NE:vsmgmt._VSS_PROTECTION_LEVEL")] - public enum VSS_PROTECTION_LEVEL - { - /// - /// - /// Specifies that I/O to the original volume must be maintained at the expense of shadow copies. This is the default protection - /// level. Shadow copies might be deleted if both of the following conditions occur: - /// - /// - /// - /// A write to the original volume occurs. - /// - /// - /// - /// The integrity of the shadow copy cannot be maintained for some reason, such as a failure to write to the shadow copy storage - /// area or a failure to allocate sufficient memory. - /// - /// - /// - /// - VSS_PROTECTION_LEVEL_ORIGINAL_VOLUME = 0, - - /// - /// - /// Specifies that shadow copies must be maintained at the expense of I/O to the original volume. This protection level is - /// called "shadow copy protection mode." All I/O to the original volume will fail if both of the following conditions occur: - /// - /// - /// - /// A write to the original volume occurs. - /// - /// - /// - /// The corresponding write to the shadow copy storage area cannot be completed for some reason, such as a failure to write to - /// the shadow copy storage area or a failure to allocate sufficient memory. - /// - /// - /// - /// - VSS_PROTECTION_LEVEL_SNAPSHOT, - } + VSS_PROTECTION_FAULT_MEMORY_ALLOCATION_FAILURE, /// - /// The IVssDifferentialSoftwareSnapshotMgmt interface contains methods that allow applications to query and manage shadow - /// copy storage areas generated by the system shadow copy provider. + /// A memory mapping failure occurred. This fault could mean that the page file is too small, or it could be caused by a low-memory condition. /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nn-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt - [PInvokeData("vsmgmt.h", MSDNShortId = "NN:vsmgmt.IVssDifferentialSoftwareSnapshotMgmt")] - [ComImport, Guid("214A0F28-B737-4026-B847-4F9E37D79529"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IVssDifferentialSoftwareSnapshotMgmt - { - /// - /// The AddDiffArea method adds a shadow copy storage area association for the specified volume. If the association is - /// not supported, an error code will be returned. - /// - /// - /// - /// The name of the volume that will be the source of shadow copies. This volume is associated with a shadow copy storage area - /// on the pwszDiffAreaVolumeName volume. - /// - /// The name of the volume must be in one of the following formats and must include a trailing backslash (\): - /// - /// - /// The path of a mounted folder, for example, Y:\MountX\ - /// - /// - /// A drive letter, for example, D:\ - /// - /// - /// A volume GUID path of the form \\?\Volume{GUID}\ (where GUID identifies the volume) - /// - /// - /// - /// - /// The name of the volume that will contain the shadow copy storage area to be associated with the pwszVolumeName volume. - /// The name of the volume must be in one of the following formats and must include a trailing backslash (\): - /// - /// - /// The path of a mounted folder - /// - /// - /// A drive letter, for example, D:\ - /// - /// - /// A volume GUID path of the form \\?\Volume{GUID}\ (where GUID identifies the volume) - /// - /// - /// - /// - /// - /// The maximum size, in bytes, of the shadow copy storage area on the volume. This value must be at least 320 MB, up to the - /// system-wide limit. If this value is –1, the maximum size is unlimited. - /// - /// - /// Windows Server 2003: Prior to Windows Server 2003 with SP1, the shadow copy storage area size was fixed at 100 MB. - /// - /// - /// - /// - /// A shadow copy storage area association cannot be created if any shadow copies already exist for the pwszVolumeName volume or - /// if there is already a shadow copy storage area association for that volume. - /// - /// - /// The shadow copy storage area for a virtual hard disk (VHD) source volume must reside on the same volume. Likewise, a shadow - /// copy storage area can only be created on a VHD volume if the source volume is the same for both volumes. - /// - /// Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: VHDs are not supported. - /// - /// To change the size of a shadow copy storage area, use the IVssDifferentialSoftwareSnapshotMgmt::ChangeDiffAreaMaximumSize or - /// IVssDifferentialSoftwareSnapshotMgmt2::ChangeDiffAreaMaximumSizeEx method. You can delete a shadow copy storage area by - /// changing its size to zero. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt-adddiffarea HRESULT - // AddDiffArea( [in] VSS_PWSZ pwszVolumeName, [in] VSS_PWSZ pwszDiffAreaVolumeName, [in] LONGLONG llMaximumDiffSpace ); - void AddDiffArea([MarshalAs(UnmanagedType.LPWStr)] string pwszVolumeName, - [MarshalAs(UnmanagedType.LPWStr)] string pwszDiffAreaVolumeName, - long llMaximumDiffSpace); + VSS_PROTECTION_FAULT_MAPPED_MEMORY_FAILURE, - /// - /// The ChangeDiffAreaMaximumSize method updates the shadow copy storage area maximum size for a certain volume. This may - /// not have an immediate effect. - /// - /// - /// - /// Name of the volume that is the source of shadow copies. This volume is associated with a shadow copy storage area on the - /// pwszDiffAreaVolumeName volume. - /// - /// The name of the volume must be in one of the following formats and must include a trailing backslash (\): - /// - /// - /// The path of a mounted folder, for example, Y:\MountX\ - /// - /// - /// A drive letter, for example, D:\ - /// - /// - /// A volume GUID path of the form \\?\Volume{GUID}\ (where GUID identifies the volume) - /// - /// - /// - /// - /// Name of the volume that contains the shadow copy storage area associated with the pwszVolumeName volume. - /// The name of the volume must be in one of the following formats and must include a trailing backslash (\): - /// - /// - /// The path of a mounted folder - /// - /// - /// A drive letter, for example, D:\ - /// - /// - /// A volume GUID path of the form \\?\Volume{GUID}\ (where GUID identifies the volume) - /// - /// - /// - /// - /// 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 deleted. If this value is –1, the maximum size is unlimited. - /// - /// - /// - /// The ChangeDiffAreaMaximumSize method makes the shadow copy storage area explicit, which means that it is not deleted - /// automatically when all shadow copies are deleted. - /// - /// If the shadow copy storage area does not exist, this method creates it. - /// - /// Windows Server 2008, Windows Vista and Windows Server 2003: If the shadow copy storage area does not exist, this - /// method does not create it. - /// - /// To create a shadow copy storage area, use the IVssDifferentialSoftwareSnapshotMgmt::AddDiffArea method. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt-changediffareamaximumsize - // HRESULT ChangeDiffAreaMaximumSize( [in] VSS_PWSZ pwszVolumeName, [in] VSS_PWSZ pwszDiffAreaVolumeName, [in] LONGLONG - // llMaximumDiffSpace ); - void ChangeDiffAreaMaximumSize([MarshalAs(UnmanagedType.LPWStr)] string pwszVolumeName, - [MarshalAs(UnmanagedType.LPWStr)] string pwszDiffAreaVolumeName, long llMaximumDiffSpace); + /// + /// A read failure occurred during the copy-on-write operation when data was being copied from the live volume to the shadow copy + /// storage area volume. + /// + VSS_PROTECTION_FAULT_COW_READ_FAILURE, - /// - /// The QueryVolumesSupportedForDiffAreas method queries volumes that support shadow copy storage areas (including - /// volumes with disabled shadow copy storage areas). - /// - /// - /// - /// 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 and must include a trailing backslash (\): - /// - /// - /// - /// The path of a mounted folder, for example, Y:\MountX\ - /// - /// - /// A drive letter, for example, D:\ - /// - /// - /// A volume GUID path of the form \\?\Volume{GUID}\ (where GUID identifies the volume) - /// - /// - /// - /// - /// The address of an IVssEnumMgmtObject interface pointer, which is initialized on return. Callers must release the interface. - /// - /// - /// The returned IVssEnumMgmtObject enumerator object will contain VSS_DIFF_VOLUME_PROP structures inside the - /// VSS_MGMT_OBJECT_UNION union inside the VSS_MGMT_OBJECT_PROP structure. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt-queryvolumessupportedfordiffareas - // HRESULT QueryVolumesSupportedForDiffAreas( [in] VSS_PWSZ pwszOriginalVolumeName, [out] IVssEnumMgmtObject **ppEnum ); - IVssEnumMgmtObject QueryVolumesSupportedForDiffAreas([MarshalAs(UnmanagedType.LPWStr)] string pwszOriginalVolumeName); - - /// The QueryDiffAreasForVolume method queries shadow copy storage areas in use by the volume. - /// - /// Name of the volume that contains shadow copy storage areas. - /// The name of the volume must be in one of the following formats and must include a trailing backslash (\): - /// - /// - /// The path of a mounted folder, for example, Y:\MountX\ - /// - /// - /// A drive letter, for example, D:\ - /// - /// - /// A volume GUID path of the form \\?\Volume{GUID}\ (where GUID identifies the volume) - /// - /// - /// - /// - /// The address of an IVssEnumMgmtObject interface pointer, which is initialized on return. Callers must release the interface. - /// - /// - /// The returned IVssEnumMgmtObject enumerator object will contain VSS_DIFF_AREA_PROP structures inside the - /// VSS_MGMT_OBJECT_UNION union inside the VSS_MGMT_OBJECT_PROP structure. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt-querydiffareasforvolume - // HRESULT QueryDiffAreasForVolume( [in] VSS_PWSZ pwszVolumeName, [out] IVssEnumMgmtObject **ppEnum ); - IVssEnumMgmtObject QueryDiffAreasForVolume([MarshalAs(UnmanagedType.LPWStr)] string pwszVolumeName); - - /// - /// The QueryDiffAreasOnVolume method queries shadow copy storage areas that physically reside on the given volume. - /// - /// - /// Name of the volume that contains shadow copy storage areas. - /// The name of the volume must be in one of the following formats and must include a trailing backslash (\): - /// - /// - /// The path of a mounted folder, for example, Y:\MountX\ - /// - /// - /// A drive letter, for example, D:\ - /// - /// - /// A volume GUID path of the form \\?\Volume{GUID}\ (where GUID identifies the volume) - /// - /// - /// - /// - /// The address of an IVssEnumMgmtObject interface pointer, which is initialized on return. Callers must release the interface. - /// - /// - /// The returned IVssEnumMgmtObject enumerator object will contain VSS_DIFF_AREA_PROP structures inside the - /// VSS_MGMT_OBJECT_UNION union inside the VSS_MGMT_OBJECT_PROP structure. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt-querydiffareasonvolume - // HRESULT QueryDiffAreasOnVolume( [in] VSS_PWSZ pwszVolumeName, [out] IVssEnumMgmtObject **ppEnum ); - IVssEnumMgmtObject QueryDiffAreasOnVolume([MarshalAs(UnmanagedType.LPWStr)] string pwszVolumeName); - - /// - /// The QueryDiffAreasForSnapshot method queries shadow copy storage areas in use by the original volume associated with - /// the input shadow copy. - /// - /// The VSS_ID of a shadow copy. - /// - /// The address of an IVssEnumMgmtObject interface pointer, which is initialized on return. Callers must release the interface. - /// - /// - /// The returned IVssEnumMgmtObject enumerator object will contain VSS_DIFF_AREA_PROP structures inside the - /// VSS_MGMT_OBJECT_UNION union inside the VSS_MGMT_OBJECT_PROP structure. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt-querydiffareasforsnapshot - // HRESULT QueryDiffAreasForSnapshot( [in] VSS_ID SnapshotId, [out] IVssEnumMgmtObject **ppEnum ); - IVssEnumMgmtObject QueryDiffAreasForSnapshot(Guid SnapshotId); - } + /// + /// A read or write failure occurred during the copy-on-write operation when data was being copied from the live volume to the + /// shadow copy storage area volume. One possible reason is that the shadow copy storage area volume has been removed from the system. + /// + VSS_PROTECTION_FAULT_COW_WRITE_FAILURE, /// /// - /// Defines additional methods that allow applications to query and manage shadow copy storage areas generated by the system shadow - /// copy provider. - /// - /// - /// To obtain an instance of the IVssDifferentialSoftwareSnapshotMgmt2 interface, call the QueryInterface method of the - /// IVssDifferentialSoftwareSnapshotMgmt interface, and pass the IID_IVssDifferentialSoftwareSnapshotMgmt2 constant as the - /// interface identifier (IID) parameter. + /// This failure means that either the shadow copy storage area is full or the shadow copy storage area volume is full. After + /// clearing the protection fault, you can do one of the following: /// + /// + /// + /// Delete unused shadow copy storage areas by calling the IVssDifferentialSoftwareSnapshotMgmt3::DeleteUnusedDiffAreas method. + /// + /// + /// + /// Increase the shadow copy storage area maximum size for the volume by calling the + /// IVssDifferentialSoftwareSnapshotMgmt::ChangeDiffAreaMaximumSize method or the + /// IVssDifferentialSoftwareSnapshotMgmt2::ChangeDiffAreaMaximumSizeEx method. + /// + /// + /// /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nn-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt2 - [PInvokeData("vsmgmt.h", MSDNShortId = "NN:vsmgmt.IVssDifferentialSoftwareSnapshotMgmt2")] - [ComImport, Guid("949d7353-675f-4275-8969-f044c6277815"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IVssDifferentialSoftwareSnapshotMgmt2 : IVssDifferentialSoftwareSnapshotMgmt - { - /// - /// Updates the shadow copy storage area maximum size for a certain volume. This may not have an immediate effect. If the - /// bVolatile parameter is FALSE, the change continues even if the computer is rebooted. - /// - /// - /// - /// The name of the volume that is the source of shadow copies. This volume is associated with a shadow copy storage area on the - /// pwszDiffAreaVolumeName volume. - /// - /// The name of the volume must be in one of the following formats and must include a trailing backslash (\): - /// - /// - /// The path of a mounted folder, for example, Y:\MountX\ - /// - /// - /// A drive letter, for example, D:\ - /// - /// - /// A volume GUID path of the form \\?\Volume{GUID}\ (where GUID identifies the volume) - /// - /// - /// - /// - /// The name of the volume that contains the shadow copy storage area that is associated with the pwszVolumeName volume. - /// The name of the volume must be in one of the following formats and must include a trailing backslash (\): - /// - /// - /// The path of a mounted folder - /// - /// - /// A drive letter with, for example, D:\ - /// - /// - /// A volume GUID path of the form \\?\Volume{GUID}\ (where GUID identifies the volume) - /// - /// - /// - /// - /// 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 deleted. If this value is –1, the maximum size is unlimited. - /// - /// - /// - /// TRUE to indicate that the effect of calling the ChangeDiffAreaMaximumSizeEx method should not continue if the - /// computer is rebooted; otherwise, FALSE. - /// - /// The default value is FALSE. - /// If the llMaximumDiffSpace parameter is zero, the bVolatile parameter must be FALSE. - /// - /// - /// - /// The ChangeDiffAreaMaximumSizeEx method is identical to the - /// IVssDifferentialSoftwareSnapshotMgmt::ChangeDiffAreaMaximumSize method except for the bVolatile parameter. - /// - /// - /// Calling the ChangeDiffAreaMaximumSizeEx method with the bVolatile parameter set to FALSE is the same as - /// calling the ChangeDiffAreaMaximumSize method. - /// - /// - /// ChangeDiffAreaMaximumSizeEx makes the shadow copy storage area explicit, which means that it is not deleted - /// automatically when all shadow copies are deleted. - /// - /// If the shadow copy storage area does not exist, this method creates it. - /// - /// Windows Server 2008, Windows Vista and Windows Server 2003: If the shadow copy storage area does not exist, this - /// method does not create it. - /// - /// To create a shadow copy storage area, use the IVssDifferentialSoftwareSnapshotMgmt::AddDiffArea method. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt2-changediffareamaximumsizeex - // HRESULT ChangeDiffAreaMaximumSizeEx( [in] VSS_PWSZ pwszVolumeName, [in] VSS_PWSZ pwszDiffAreaVolumeName, [in] LONGLONG - // llMaximumDiffSpace, [in] BOOL bVolatile ); - void ChangeDiffAreaMaximumSizeEx([MarshalAs(UnmanagedType.LPWStr)] string pwszVolumeName, - [MarshalAs(UnmanagedType.LPWStr)] string pwszDiffAreaVolumeName, long llMaximumDiffSpace, - [MarshalAs(UnmanagedType.Bool)] bool bVolatile); - - /// - /// Not supported. - /// This method is reserved for future use. - /// - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt2-migratediffareas - // HRESULT MigrateDiffAreas( [in] VSS_PWSZ pwszVolumeName, [in] VSS_PWSZ pwszDiffAreaVolumeName, [in] VSS_PWSZ - // pwszNewDiffAreaVolumeName ); - void MigrateDiffAreas([MarshalAs(UnmanagedType.LPWStr)] string pwszVolumeName, - [MarshalAs(UnmanagedType.LPWStr)] string pwszDiffAreaVolumeName, - [MarshalAs(UnmanagedType.LPWStr)] string pwszNewDiffAreaVolumeName); - - /// - /// Not supported. - /// This method is reserved for future use. - /// - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt2-querymigrationstatus - // HRESULT QueryMigrationStatus( [in] VSS_PWSZ pwszVolumeName, [in] VSS_PWSZ pwszDiffAreaVolumeName, [out] IVssAsync **ppAsync ); - IVssAsync QueryMigrationStatus([MarshalAs(UnmanagedType.LPWStr)] string pwszVolumeName, - [MarshalAs(UnmanagedType.LPWStr)] string pwszDiffAreaVolumeName); - - /// - /// Not supported. - /// This method is reserved for future use. - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt2-setsnapshotpriority - // HRESULT SetSnapshotPriority( [in] VSS_ID idSnapshot, [in] BYTE priority ); - void SetSnapshotPriority(Guid idSnapshot, byte priority); - } + VSS_PROTECTION_FAULT_DIFF_AREA_FULL, /// - /// Defines methods that allow applications to use the shadow copy protection feature of VSS. - /// - /// To obtain an instance of the IVssDifferentialSoftwareSnapshotMgmt3 interface, call the QueryInterface method of the - /// IVssDifferentialSoftwareSnapshotMgmt interface and pass the IID_IVssDifferentialSoftwareSnapshotMgmt3 constant as the - /// interface identifier (IID) parameter. - /// + /// The size of the shadow copy storage area could not be increased because there was no longer enough space on the shadow copy + /// storage area volume. /// + VSS_PROTECTION_FAULT_GROW_TOO_SLOW, + + /// The size of the shadow copy storage area could not be increased. + VSS_PROTECTION_FAULT_GROW_FAILED, + + /// An unexpected error occurred. + VSS_PROTECTION_FAULT_DESTROY_ALL_SNAPSHOTS, + + /// + /// Either the shadow copy storage area files could not be opened or the shadow copy storage area volume could not be mounted + /// because of a file system operation failure. + /// + VSS_PROTECTION_FAULT_FILE_SYSTEM_FAILURE, + + /// A read or write failure occurred on the shadow copy storage area volume. + VSS_PROTECTION_FAULT_IO_FAILURE, + + /// The shadow copy storage area volume was removed from the system or could not be accessed for some other reason. + VSS_PROTECTION_FAULT_DIFF_AREA_REMOVED, + + /// Another application attempted to write to the shadow copy storage area. + VSS_PROTECTION_FAULT_EXTERNAL_WRITER_TO_DIFF_AREA, + + /// + VSS_PROTECTION_FAULT_MOUNT_DURING_CLUSTER_OFFLINE, + } + + /// Defines the set of volume shadow copy protection levels. + /// + /// When a volume is in shadow copy protection mode, requesters must set shadow copy storage area (diff area) associations using the + /// IVssDifferentialSoftwareSnapshotMgmt::AddDiffArea method. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/VsMgmt/ne-vsmgmt-vss_protection_level typedef enum _VSS_PROTECTION_LEVEL { + // VSS_PROTECTION_LEVEL_ORIGINAL_VOLUME, VSS_PROTECTION_LEVEL_SNAPSHOT } VSS_PROTECTION_LEVEL, *PVSS_PROTECTION_LEVEL; + [PInvokeData("vsmgmt.h", MSDNShortId = "NE:vsmgmt._VSS_PROTECTION_LEVEL")] + public enum VSS_PROTECTION_LEVEL + { + /// + /// + /// Specifies that I/O to the original volume must be maintained at the expense of shadow copies. This is the default protection + /// level. Shadow copies might be deleted if both of the following conditions occur: + /// + /// + /// + /// A write to the original volume occurs. + /// + /// + /// + /// The integrity of the shadow copy cannot be maintained for some reason, such as a failure to write to the shadow copy storage + /// area or a failure to allocate sufficient memory. + /// + /// + /// + /// + VSS_PROTECTION_LEVEL_ORIGINAL_VOLUME = 0, + + /// + /// + /// Specifies that shadow copies must be maintained at the expense of I/O to the original volume. This protection level is called + /// "shadow copy protection mode." All I/O to the original volume will fail if both of the following conditions occur: + /// + /// + /// + /// A write to the original volume occurs. + /// + /// + /// + /// The corresponding write to the shadow copy storage area cannot be completed for some reason, such as a failure to write to the + /// shadow copy storage area or a failure to allocate sufficient memory. + /// + /// + /// + /// + VSS_PROTECTION_LEVEL_SNAPSHOT, + } + + /// + /// The IVssDifferentialSoftwareSnapshotMgmt interface contains methods that allow applications to query and manage shadow copy + /// storage areas generated by the system shadow copy provider. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nn-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt + [PInvokeData("vsmgmt.h", MSDNShortId = "NN:vsmgmt.IVssDifferentialSoftwareSnapshotMgmt")] + [ComImport, Guid("214A0F28-B737-4026-B847-4F9E37D79529"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IVssDifferentialSoftwareSnapshotMgmt + { + /// + /// The AddDiffArea method adds a shadow copy storage area association for the specified volume. If the association is not + /// supported, an error code will be returned. + /// + /// + /// + /// The name of the volume that will be the source of shadow copies. This volume is associated with a shadow copy storage area on + /// the pwszDiffAreaVolumeName volume. + /// + /// The name of the volume must be in one of the following formats and must include a trailing backslash (\): + /// + /// + /// The path of a mounted folder, for example, Y:\MountX\ + /// + /// + /// A drive letter, for example, D:\ + /// + /// + /// A volume GUID path of the form \\?\Volume{GUID}\ (where GUID identifies the volume) + /// + /// + /// + /// + /// The name of the volume that will contain the shadow copy storage area to be associated with the pwszVolumeName volume. + /// The name of the volume must be in one of the following formats and must include a trailing backslash (\): + /// + /// + /// The path of a mounted folder + /// + /// + /// A drive letter, for example, D:\ + /// + /// + /// A volume GUID path of the form \\?\Volume{GUID}\ (where GUID identifies the volume) + /// + /// + /// + /// + /// + /// The maximum size, in bytes, of the shadow copy storage area on the volume. This value must be at least 320 MB, up to the + /// system-wide limit. If this value is –1, the maximum size is unlimited. + /// + /// + /// Windows Server 2003: Prior to Windows Server 2003 with SP1, the shadow copy storage area size was fixed at 100 MB. + /// + /// /// /// - /// An application with administrator privilege can use the SetVolumeProtectLevel method to specify a shadow copy protection level - /// for a volume and the separate volume that contains its shadow copy storage area. The same protection level should be set for - /// both volumes. The possible protection levels are defined by the VSS_PROTECTION_LEVEL enumeration. + /// A shadow copy storage area association cannot be created if any shadow copies already exist for the pwszVolumeName volume or if + /// there is already a shadow copy storage area association for that volume. /// /// - /// When a volume protection fault occurs, the application must call the GetVolumeProtectLevel method for the volume to identify the - /// cause of the fault. + /// The shadow copy storage area for a virtual hard disk (VHD) source volume must reside on the same volume. Likewise, a shadow copy + /// storage area can only be created on a VHD volume if the source volume is the same for both volumes. + /// + /// Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: VHDs are not supported. + /// + /// To change the size of a shadow copy storage area, use the IVssDifferentialSoftwareSnapshotMgmt::ChangeDiffAreaMaximumSize or + /// IVssDifferentialSoftwareSnapshotMgmt2::ChangeDiffAreaMaximumSizeEx method. You can delete a shadow copy storage area by changing + /// its size to zero. /// /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nn-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt3 - [PInvokeData("vsmgmt.h", MSDNShortId = "NN:vsmgmt.IVssDifferentialSoftwareSnapshotMgmt3")] - [ComImport, Guid("383f7e71-a4c5-401f-b27f-f826289f8458"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IVssDifferentialSoftwareSnapshotMgmt3 : IVssDifferentialSoftwareSnapshotMgmt2 - { - /// Sets the shadow copy protection level for an original volume or a shadow copy storage area volume. - /// - /// The name of the volume. This parameter is required and cannot be NULL. - /// The name must be in one of the following formats and must include a trailing backslash (\): - /// - /// - /// The path of a mounted folder, for example, Y:\MountX\ - /// - /// - /// A drive letter, for example, D:\ - /// - /// - /// A volume GUID path in the form \\?\Volume{GUID}\ (where GUID identifies the volume) - /// - /// - /// - /// - /// A value from the VSS_PROTECTION_LEVEL enumeration that specifies the shadow copy protection level. - /// - /// - /// - /// The SetVolumeProtectLevel method checks the current shadow copy protection level of the volume. If the volume is in a - /// faulted state and VSS_PROTECTION_LEVEL_ORIGINAL_VOLUME is specified for the protectionLevel parameter, - /// SetVolumeProtectLevel 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, - /// SetVolumeProtectLevel does nothing. - /// - /// - /// If the value of the protectionLevel parameter is VSS_PROTECTION_LEVEL_SNAPSHOT, requesters must set shadow copy - /// storage area (diff area) associations using the IVssDifferentialSoftwareSnapshotMgmt::AddDiffArea method. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt3-setvolumeprotectlevel - // HRESULT SetVolumeProtectLevel( [in] VSS_PWSZ pwszVolumeName, [in] VSS_PROTECTION_LEVEL protectionLevel ); - void SetVolumeProtectLevel([MarshalAs(UnmanagedType.LPWStr)] string pwszVolumeName, VSS_PROTECTION_LEVEL protectionLevel); + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt-adddiffarea HRESULT + // AddDiffArea( [in] VSS_PWSZ pwszVolumeName, [in] VSS_PWSZ pwszDiffAreaVolumeName, [in] LONGLONG llMaximumDiffSpace ); + void AddDiffArea([MarshalAs(UnmanagedType.LPWStr)] string pwszVolumeName, + [MarshalAs(UnmanagedType.LPWStr)] string pwszDiffAreaVolumeName, + long llMaximumDiffSpace); - /// Gets the shadow copy protection level and status for the specified volume. - /// - /// The name of the volume. This parameter is required and cannot be NULL. - /// The name must be in one of the following formats and must include a trailing backslash (\): - /// - /// - /// The path of a mounted folder, for example, Y:\MountX\ - /// - /// - /// A drive letter, for example, D:\ - /// - /// - /// A volume GUID path in the form \\?\Volume{GUID}\ (where GUID identifies the volume) - /// - /// - /// - /// - /// The address of a caller-allocated buffer that receives a VSS_VOLUME_PROTECTION_INFO structure containing information about - /// the volume's shadow copy protection level. - /// - /// - /// - /// The GetVolumeProtectLevel method gets information about the volume's current protection level. If the volume is in a - /// faulted state, the m_protectionFault member of the VSS_VOLUME_PROTECTION_INFO structure contains the current - /// protection fault, and the m_failureStatus member contains the reason why the volume is in a faulted state. If the - /// volume is not in a faulted state, the m_protectionFault and m_failureStatus members will be zero. - /// - /// - /// If the value of the protectionLevel parameter is VSS_PROTECTION_LEVEL_SNAPSHOT, requesters must set shadow copy - /// storage area (diff area) associations using the IVssDifferentialSoftwareSnapshotMgmt::AddDiffArea method. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt3-getvolumeprotectlevel - // HRESULT GetVolumeProtectLevel( [in] VSS_PWSZ pwszVolumeName, [out] VSS_VOLUME_PROTECTION_INFO *protectionLevel ); - VSS_VOLUME_PROTECTION_INFO GetVolumeProtectLevel([MarshalAs(UnmanagedType.LPWStr)] string pwszVolumeName); + /// + /// The ChangeDiffAreaMaximumSize method updates the shadow copy storage area maximum size for a certain volume. This may not + /// have an immediate effect. + /// + /// + /// + /// Name of the volume that is the source of shadow copies. This volume is associated with a shadow copy storage area on the + /// pwszDiffAreaVolumeName volume. + /// + /// The name of the volume must be in one of the following formats and must include a trailing backslash (\): + /// + /// + /// The path of a mounted folder, for example, Y:\MountX\ + /// + /// + /// A drive letter, for example, D:\ + /// + /// + /// A volume GUID path of the form \\?\Volume{GUID}\ (where GUID identifies the volume) + /// + /// + /// + /// + /// Name of the volume that contains the shadow copy storage area associated with the pwszVolumeName volume. + /// The name of the volume must be in one of the following formats and must include a trailing backslash (\): + /// + /// + /// The path of a mounted folder + /// + /// + /// A drive letter, for example, D:\ + /// + /// + /// A volume GUID path of the form \\?\Volume{GUID}\ (where GUID identifies the volume) + /// + /// + /// + /// + /// 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 deleted. If this value is –1, the maximum size is unlimited. + /// + /// + /// + /// The ChangeDiffAreaMaximumSize method makes the shadow copy storage area explicit, which means that it is not deleted + /// automatically when all shadow copies are deleted. + /// + /// If the shadow copy storage area does not exist, this method creates it. + /// + /// Windows Server 2008, Windows Vista and Windows Server 2003: If the shadow copy storage area does not exist, this method + /// does not create it. + /// + /// To create a shadow copy storage area, use the IVssDifferentialSoftwareSnapshotMgmt::AddDiffArea method. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt-changediffareamaximumsize + // HRESULT ChangeDiffAreaMaximumSize( [in] VSS_PWSZ pwszVolumeName, [in] VSS_PWSZ pwszDiffAreaVolumeName, [in] LONGLONG + // llMaximumDiffSpace ); + void ChangeDiffAreaMaximumSize([MarshalAs(UnmanagedType.LPWStr)] string pwszVolumeName, + [MarshalAs(UnmanagedType.LPWStr)] string pwszDiffAreaVolumeName, long llMaximumDiffSpace); - /// Clears the protection fault state for the specified volume. - /// - /// The name of the volume. This parameter is required and cannot be NULL. - /// The name must be in one of the following formats and must include a trailing backslash (\): - /// - /// - /// The path of a mounted folder, for example, Y:\MountX\ - /// - /// - /// A drive letter, for example, D:\ - /// - /// - /// A volume GUID path in the form \\?\Volume{GUID}\ (where GUID identifies the volume) - /// - /// - /// - /// - /// The ClearVolumeProtectFault 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. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt3-clearvolumeprotectfault - // HRESULT ClearVolumeProtectFault( [in] VSS_PWSZ pwszVolumeName ); - void ClearVolumeProtectFault([MarshalAs(UnmanagedType.LPWStr)] string pwszVolumeName); + /// + /// The QueryVolumesSupportedForDiffAreas method queries volumes that support shadow copy storage areas (including volumes + /// with disabled shadow copy storage areas). + /// + /// + /// + /// 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 and must include a trailing backslash (\): + /// + /// + /// + /// The path of a mounted folder, for example, Y:\MountX\ + /// + /// + /// A drive letter, for example, D:\ + /// + /// + /// A volume GUID path of the form \\?\Volume{GUID}\ (where GUID identifies the volume) + /// + /// + /// + /// + /// The address of an IVssEnumMgmtObject interface pointer, which is initialized on return. Callers must release the interface. + /// + /// + /// The returned IVssEnumMgmtObject enumerator object will contain VSS_DIFF_VOLUME_PROP structures inside the VSS_MGMT_OBJECT_UNION + /// union inside the VSS_MGMT_OBJECT_PROP structure. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt-queryvolumessupportedfordiffareas + // HRESULT QueryVolumesSupportedForDiffAreas( [in] VSS_PWSZ pwszOriginalVolumeName, [out] IVssEnumMgmtObject **ppEnum ); + IVssEnumMgmtObject QueryVolumesSupportedForDiffAreas([MarshalAs(UnmanagedType.LPWStr)] string pwszOriginalVolumeName); - /// Deletes all shadow copy storage areas (also called diff areas) on the specified volume that are not in use. - /// - /// The name of the volume. This parameter is required and cannot be NULL. - /// The name must be in one of the following formats and must include a trailing backslash (\): - /// - /// - /// The path of a mounted folder, for example, Y:\MountX\ - /// - /// - /// A drive letter, for example, D:\ - /// - /// - /// A volume GUID path in the form \\?\Volume{GUID}\ (where GUID identifies the volume) - /// - /// - /// - /// - /// 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 method is the only way to recover the abandoned storage area space. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt3-deleteunuseddiffareas - // HRESULT DeleteUnusedDiffAreas( [in] VSS_PWSZ pwszDiffAreaVolumeName ); - void DeleteUnusedDiffAreas([MarshalAs(UnmanagedType.LPWStr)] string pwszDiffAreaVolumeName); + /// The QueryDiffAreasForVolume method queries shadow copy storage areas in use by the volume. + /// + /// Name of the volume that contains shadow copy storage areas. + /// The name of the volume must be in one of the following formats and must include a trailing backslash (\): + /// + /// + /// The path of a mounted folder, for example, Y:\MountX\ + /// + /// + /// A drive letter, for example, D:\ + /// + /// + /// A volume GUID path of the form \\?\Volume{GUID}\ (where GUID identifies the volume) + /// + /// + /// + /// + /// The address of an IVssEnumMgmtObject interface pointer, which is initialized on return. Callers must release the interface. + /// + /// + /// The returned IVssEnumMgmtObject enumerator object will contain VSS_DIFF_AREA_PROP structures inside the VSS_MGMT_OBJECT_UNION + /// union inside the VSS_MGMT_OBJECT_PROP structure. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt-querydiffareasforvolume + // HRESULT QueryDiffAreasForVolume( [in] VSS_PWSZ pwszVolumeName, [out] IVssEnumMgmtObject **ppEnum ); + IVssEnumMgmtObject QueryDiffAreasForVolume([MarshalAs(UnmanagedType.LPWStr)] string pwszVolumeName); - /// - /// Not supported. - /// This method is reserved for future use. - /// - /// - /// - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt3-querysnapshotdeltabitmap - // HRESULT QuerySnapshotDeltaBitmap( [in] VSS_ID idSnapshotOlder, [in] VSS_ID idSnapshotYounger, [out] ULONG *pcBlockSizePerBit, - // [out] ULONG *pcBitmapLength, [out] BYTE **ppbBitmap ); - void QuerySnapshotDeltaBitmap(Guid idSnapshotOlder, Guid idSnapshotYounger, out uint pcBlockSizePerBit, - out uint pcBitmapLength, out IntPtr ppbBitmap); - } + /// The QueryDiffAreasOnVolume method queries shadow copy storage areas that physically reside on the given volume. + /// + /// Name of the volume that contains shadow copy storage areas. + /// The name of the volume must be in one of the following formats and must include a trailing backslash (\): + /// + /// + /// The path of a mounted folder, for example, Y:\MountX\ + /// + /// + /// A drive letter, for example, D:\ + /// + /// + /// A volume GUID path of the form \\?\Volume{GUID}\ (where GUID identifies the volume) + /// + /// + /// + /// + /// The address of an IVssEnumMgmtObject interface pointer, which is initialized on return. Callers must release the interface. + /// + /// + /// The returned IVssEnumMgmtObject enumerator object will contain VSS_DIFF_AREA_PROP structures inside the VSS_MGMT_OBJECT_UNION + /// union inside the VSS_MGMT_OBJECT_PROP structure. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt-querydiffareasonvolume + // HRESULT QueryDiffAreasOnVolume( [in] VSS_PWSZ pwszVolumeName, [out] IVssEnumMgmtObject **ppEnum ); + IVssEnumMgmtObject QueryDiffAreasOnVolume([MarshalAs(UnmanagedType.LPWStr)] string pwszVolumeName); + + /// + /// The QueryDiffAreasForSnapshot method queries shadow copy storage areas in use by the original volume associated with the + /// input shadow copy. + /// + /// The VSS_ID of a shadow copy. + /// + /// The address of an IVssEnumMgmtObject interface pointer, which is initialized on return. Callers must release the interface. + /// + /// + /// The returned IVssEnumMgmtObject enumerator object will contain VSS_DIFF_AREA_PROP structures inside the VSS_MGMT_OBJECT_UNION + /// union inside the VSS_MGMT_OBJECT_PROP structure. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt-querydiffareasforsnapshot + // HRESULT QueryDiffAreasForSnapshot( [in] VSS_ID SnapshotId, [out] IVssEnumMgmtObject **ppEnum ); + IVssEnumMgmtObject QueryDiffAreasForSnapshot(Guid SnapshotId); + } + + /// + /// + /// Defines additional methods that allow applications to query and manage shadow copy storage areas generated by the system shadow copy provider. + /// + /// + /// To obtain an instance of the IVssDifferentialSoftwareSnapshotMgmt2 interface, call the QueryInterface method of the + /// IVssDifferentialSoftwareSnapshotMgmt interface, and pass the IID_IVssDifferentialSoftwareSnapshotMgmt2 constant as the + /// interface identifier (IID) parameter. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nn-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt2 + [PInvokeData("vsmgmt.h", MSDNShortId = "NN:vsmgmt.IVssDifferentialSoftwareSnapshotMgmt2")] + [ComImport, Guid("949d7353-675f-4275-8969-f044c6277815"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IVssDifferentialSoftwareSnapshotMgmt2 : IVssDifferentialSoftwareSnapshotMgmt + { + /// + /// Updates the shadow copy storage area maximum size for a certain volume. This may not have an immediate effect. If the bVolatile + /// parameter is FALSE, the change continues even if the computer is rebooted. + /// + /// + /// + /// The name of the volume that is the source of shadow copies. This volume is associated with a shadow copy storage area on the + /// pwszDiffAreaVolumeName volume. + /// + /// The name of the volume must be in one of the following formats and must include a trailing backslash (\): + /// + /// + /// The path of a mounted folder, for example, Y:\MountX\ + /// + /// + /// A drive letter, for example, D:\ + /// + /// + /// A volume GUID path of the form \\?\Volume{GUID}\ (where GUID identifies the volume) + /// + /// + /// + /// + /// The name of the volume that contains the shadow copy storage area that is associated with the pwszVolumeName volume. + /// The name of the volume must be in one of the following formats and must include a trailing backslash (\): + /// + /// + /// The path of a mounted folder + /// + /// + /// A drive letter with, for example, D:\ + /// + /// + /// A volume GUID path of the form \\?\Volume{GUID}\ (where GUID identifies the volume) + /// + /// + /// + /// + /// 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 deleted. If this value is –1, the maximum size is unlimited. + /// + /// + /// + /// TRUE to indicate that the effect of calling the ChangeDiffAreaMaximumSizeEx method should not continue if the computer is + /// rebooted; otherwise, FALSE. + /// + /// The default value is FALSE. + /// If the llMaximumDiffSpace parameter is zero, the bVolatile parameter must be FALSE. + /// + /// + /// + /// The ChangeDiffAreaMaximumSizeEx method is identical to the + /// IVssDifferentialSoftwareSnapshotMgmt::ChangeDiffAreaMaximumSize method except for the bVolatile parameter. + /// + /// + /// Calling the ChangeDiffAreaMaximumSizeEx method with the bVolatile parameter set to FALSE is the same as calling + /// the ChangeDiffAreaMaximumSize method. + /// + /// + /// ChangeDiffAreaMaximumSizeEx makes the shadow copy storage area explicit, which means that it is not deleted automatically + /// when all shadow copies are deleted. + /// + /// If the shadow copy storage area does not exist, this method creates it. + /// + /// Windows Server 2008, Windows Vista and Windows Server 2003: If the shadow copy storage area does not exist, this method + /// does not create it. + /// + /// To create a shadow copy storage area, use the IVssDifferentialSoftwareSnapshotMgmt::AddDiffArea method. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt2-changediffareamaximumsizeex + // HRESULT ChangeDiffAreaMaximumSizeEx( [in] VSS_PWSZ pwszVolumeName, [in] VSS_PWSZ pwszDiffAreaVolumeName, [in] LONGLONG + // llMaximumDiffSpace, [in] BOOL bVolatile ); + void ChangeDiffAreaMaximumSizeEx([MarshalAs(UnmanagedType.LPWStr)] string pwszVolumeName, + [MarshalAs(UnmanagedType.LPWStr)] string pwszDiffAreaVolumeName, long llMaximumDiffSpace, + [MarshalAs(UnmanagedType.Bool)] bool bVolatile); + + /// + /// Not supported. + /// This method is reserved for future use. + /// + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt2-migratediffareas + // HRESULT MigrateDiffAreas( [in] VSS_PWSZ pwszVolumeName, [in] VSS_PWSZ pwszDiffAreaVolumeName, [in] VSS_PWSZ + // pwszNewDiffAreaVolumeName ); + void MigrateDiffAreas([MarshalAs(UnmanagedType.LPWStr)] string pwszVolumeName, + [MarshalAs(UnmanagedType.LPWStr)] string pwszDiffAreaVolumeName, + [MarshalAs(UnmanagedType.LPWStr)] string pwszNewDiffAreaVolumeName); + + /// + /// Not supported. + /// This method is reserved for future use. + /// + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt2-querymigrationstatus + // HRESULT QueryMigrationStatus( [in] VSS_PWSZ pwszVolumeName, [in] VSS_PWSZ pwszDiffAreaVolumeName, [out] IVssAsync **ppAsync ); + IVssAsync QueryMigrationStatus([MarshalAs(UnmanagedType.LPWStr)] string pwszVolumeName, + [MarshalAs(UnmanagedType.LPWStr)] string pwszDiffAreaVolumeName); + + /// + /// Not supported. + /// This method is reserved for future use. + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt2-setsnapshotpriority + // HRESULT SetSnapshotPriority( [in] VSS_ID idSnapshot, [in] BYTE priority ); + void SetSnapshotPriority(Guid idSnapshot, byte priority); + } + + /// + /// Defines methods that allow applications to use the shadow copy protection feature of VSS. + /// + /// To obtain an instance of the IVssDifferentialSoftwareSnapshotMgmt3 interface, call the QueryInterface method of the + /// IVssDifferentialSoftwareSnapshotMgmt interface and pass the IID_IVssDifferentialSoftwareSnapshotMgmt3 constant as the + /// interface identifier (IID) parameter. + /// + /// + /// + /// + /// An application with administrator privilege can use the SetVolumeProtectLevel method to specify a shadow copy protection level for a + /// volume and the separate volume that contains its shadow copy storage area. The same protection level should be set for both volumes. + /// The possible protection levels are defined by the VSS_PROTECTION_LEVEL enumeration. + /// + /// + /// When a volume protection fault occurs, the application must call the GetVolumeProtectLevel method for the volume to identify the + /// cause of the fault. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nn-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt3 + [PInvokeData("vsmgmt.h", MSDNShortId = "NN:vsmgmt.IVssDifferentialSoftwareSnapshotMgmt3")] + [ComImport, Guid("383f7e71-a4c5-401f-b27f-f826289f8458"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IVssDifferentialSoftwareSnapshotMgmt3 : IVssDifferentialSoftwareSnapshotMgmt2 + { + /// Sets the shadow copy protection level for an original volume or a shadow copy storage area volume. + /// + /// The name of the volume. This parameter is required and cannot be NULL. + /// The name must be in one of the following formats and must include a trailing backslash (\): + /// + /// + /// The path of a mounted folder, for example, Y:\MountX\ + /// + /// + /// A drive letter, for example, D:\ + /// + /// + /// A volume GUID path in the form \\?\Volume{GUID}\ (where GUID identifies the volume) + /// + /// + /// + /// A value from the VSS_PROTECTION_LEVEL enumeration that specifies the shadow copy protection level. + /// + /// + /// The SetVolumeProtectLevel method checks the current shadow copy protection level of the volume. If the volume is in a + /// faulted state and VSS_PROTECTION_LEVEL_ORIGINAL_VOLUME is specified for the protectionLevel parameter, + /// SetVolumeProtectLevel 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, + /// SetVolumeProtectLevel does nothing. + /// + /// + /// If the value of the protectionLevel parameter is VSS_PROTECTION_LEVEL_SNAPSHOT, requesters must set shadow copy storage + /// area (diff area) associations using the IVssDifferentialSoftwareSnapshotMgmt::AddDiffArea method. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt3-setvolumeprotectlevel + // HRESULT SetVolumeProtectLevel( [in] VSS_PWSZ pwszVolumeName, [in] VSS_PROTECTION_LEVEL protectionLevel ); + void SetVolumeProtectLevel([MarshalAs(UnmanagedType.LPWStr)] string pwszVolumeName, VSS_PROTECTION_LEVEL protectionLevel); + + /// Gets the shadow copy protection level and status for the specified volume. + /// + /// The name of the volume. This parameter is required and cannot be NULL. + /// The name must be in one of the following formats and must include a trailing backslash (\): + /// + /// + /// The path of a mounted folder, for example, Y:\MountX\ + /// + /// + /// A drive letter, for example, D:\ + /// + /// + /// A volume GUID path in the form \\?\Volume{GUID}\ (where GUID identifies the volume) + /// + /// + /// + /// + /// The address of a caller-allocated buffer that receives a VSS_VOLUME_PROTECTION_INFO structure containing information about the + /// volume's shadow copy protection level. + /// + /// + /// + /// The GetVolumeProtectLevel method gets information about the volume's current protection level. If the volume is in a + /// faulted state, the m_protectionFault member of the VSS_VOLUME_PROTECTION_INFO structure contains the current protection + /// fault, and the m_failureStatus member contains the reason why the volume is in a faulted state. If the volume is not in a + /// faulted state, the m_protectionFault and m_failureStatus members will be zero. + /// + /// + /// If the value of the protectionLevel parameter is VSS_PROTECTION_LEVEL_SNAPSHOT, requesters must set shadow copy storage + /// area (diff area) associations using the IVssDifferentialSoftwareSnapshotMgmt::AddDiffArea method. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt3-getvolumeprotectlevel + // HRESULT GetVolumeProtectLevel( [in] VSS_PWSZ pwszVolumeName, [out] VSS_VOLUME_PROTECTION_INFO *protectionLevel ); + VSS_VOLUME_PROTECTION_INFO GetVolumeProtectLevel([MarshalAs(UnmanagedType.LPWStr)] string pwszVolumeName); + + /// Clears the protection fault state for the specified volume. + /// + /// The name of the volume. This parameter is required and cannot be NULL. + /// The name must be in one of the following formats and must include a trailing backslash (\): + /// + /// + /// The path of a mounted folder, for example, Y:\MountX\ + /// + /// + /// A drive letter, for example, D:\ + /// + /// + /// A volume GUID path in the form \\?\Volume{GUID}\ (where GUID identifies the volume) + /// + /// + /// + /// + /// The ClearVolumeProtectFault 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. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt3-clearvolumeprotectfault + // HRESULT ClearVolumeProtectFault( [in] VSS_PWSZ pwszVolumeName ); + void ClearVolumeProtectFault([MarshalAs(UnmanagedType.LPWStr)] string pwszVolumeName); + + /// Deletes all shadow copy storage areas (also called diff areas) on the specified volume that are not in use. + /// + /// The name of the volume. This parameter is required and cannot be NULL. + /// The name must be in one of the following formats and must include a trailing backslash (\): + /// + /// + /// The path of a mounted folder, for example, Y:\MountX\ + /// + /// + /// A drive letter, for example, D:\ + /// + /// + /// A volume GUID path in the form \\?\Volume{GUID}\ (where GUID identifies the volume) + /// + /// + /// + /// + /// 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 + /// method is the only way to recover the abandoned storage area space. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt3-deleteunuseddiffareas + // HRESULT DeleteUnusedDiffAreas( [in] VSS_PWSZ pwszDiffAreaVolumeName ); + void DeleteUnusedDiffAreas([MarshalAs(UnmanagedType.LPWStr)] string pwszDiffAreaVolumeName); + + /// + /// Not supported. + /// This method is reserved for future use. + /// + /// + /// + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssdifferentialsoftwaresnapshotmgmt3-querysnapshotdeltabitmap + // HRESULT QuerySnapshotDeltaBitmap( [in] VSS_ID idSnapshotOlder, [in] VSS_ID idSnapshotYounger, [out] ULONG *pcBlockSizePerBit, + // [out] ULONG *pcBitmapLength, [out] BYTE **ppbBitmap ); + void QuerySnapshotDeltaBitmap(Guid idSnapshotOlder, Guid idSnapshotYounger, out uint pcBlockSizePerBit, + out uint pcBitmapLength, out IntPtr ppbBitmap); + } + + /// + /// + /// The IVssEnumMgmtObject interface contains methods to iterate over and perform other operations on a list of enumerated objects. + /// + /// + /// The calling application is responsible for calling IUnknown::Release to release the resources held by the returned + /// IVssEnumMgmtObject when it is no longer needed. It may also need to call IUnknown::Release to release temporary + /// objects (such as strings) returned during enumeration. + /// + /// + /// The IVssDifferentialSoftwareSnapshotMgmt::QueryDiffAreasForSnapshot, IVssDifferentialSoftwareSnapshotMgmt::QueryDiffAreasForVolume, + /// IVssDifferentialSoftwareSnapshotMgmt::QueryDiffAreasOnVolume, and + /// IVssDifferentialSoftwareSnapshotMgmt::QueryVolumesSupportedForDiffAreas methods return an IVssEnumMgmtObject object. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nn-vsmgmt-ivssenummgmtobject + [PInvokeData("vsmgmt.h", MSDNShortId = "NN:vsmgmt.IVssEnumMgmtObject")] + [ComImport, Guid("01954E6B-9254-4e6e-808C-C9E05D007696"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IVssEnumMgmtObject : ICOMEnum + { + /// The Next method returns the specified number of objects from the specified list of enumerated objects. + /// The number of elements to be read from the list of enumerated objects into the rgelt buffer. + /// + /// The address of a caller-allocated buffer that receives celtVSS_MGMT_OBJECT_PROP structures that contain the returned objects. + /// This parameter is required and cannot be NULL. + /// + /// The number of elements that were returned in the rgelt buffer. + /// If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssenummgmtobject-next HRESULT Next( [in] ULONG celt, [out] + // VSS_MGMT_OBJECT_PROP *rgelt, [out] ULONG *pceltFetched ); + [PreserveSig] + HRESULT Next(uint celt, [Out, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] VSS_MGMT_OBJECT_PROP[] rgelt, out uint pceltFetched); + + /// The Skip method skips the specified number of objects. + /// Number of elements to be skipped in the list of enumerated objects. + /// If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssenummgmtobject-skip HRESULT Skip( [in] ULONG celt ); + [PreserveSig] + HRESULT Skip(uint celt); + + /// The Reset method resets the enumerator so that IVssEnumMgmtObject starts at the first enumerated object. + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssenummgmtobject-reset HRESULT Reset(); + void Reset(); + + /// + /// The Clone method creates a copy of the specified list of enumerated elements by creating a copy of the IVssEnumMgmtObject + /// enumerator object. + /// + /// + /// Address of an IVssEnumMgmtObject interface pointer. Set the value of this parameter to NULL before calling this method. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssenummgmtobject-clone HRESULT Clone( [in, out] + // IVssEnumMgmtObject **ppenum ); + IVssEnumMgmtObject Clone(); + } + + /// + /// The IVssSnapshotMgmt interface provides a method that returns an interface to further configure a shadow copy provider. + /// + /// + /// + /// The IVssSnapshotMgmt interface can be invoked remotely using DCOM. The caller must be a member of the local administrators + /// group on the remote machine. + /// + /// Examples + /// + /// + ///GetProviderMgmtInterface(ProviderId, IID_IVssDifferentialSoftwareSnapshotMgmt, (IUnknown**)&pDiffMgmt); + /// if (FAILED(hr)) + /// { + /// pMgmt->Release(); + /// } + /// + /// // processing code + /// pDiffMgmt->Release(); + /// pMgmt->Release(); + ///}]]> + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nn-vsmgmt-ivsssnapshotmgmt + [PInvokeData("vsmgmt.h", MSDNShortId = "NN:vsmgmt.IVssSnapshotMgmt")] + [ComImport, Guid("FA7DF749-66E7-4986-A27F-E2F04AE53772"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown), CoClass(typeof(VssSnapshotMgmt))] + public interface IVssSnapshotMgmt + { + /// The GetProviderMgmtInterface method returns an interface to further configure the system provider. + /// + /// This must be the system provider. The VSS_ID for the system provider + /// {b5946137-7b9f-4925-af80-51abd60b20d5} + /// . + /// + /// + /// Must be IID_IVssDifferentialSoftwareSnapshotMgmt, which represents the IVssDifferentialSoftwareSnapshotMgmt interface. + /// + /// Address of an interface pointer that is filled in with the returned interface pointer. + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivsssnapshotmgmt-getprovidermgmtinterface HRESULT + // GetProviderMgmtInterface( [in] VSS_ID ProviderId, [in] REFIID InterfaceId, [out] IUnknown **ppItf ); + [return: MarshalAs(UnmanagedType.IUnknown)] + object GetProviderMgmtInterface(Guid ProviderId, in Guid InterfaceId); + + /// + /// Not supported. + /// The QueryVolumesSupportedForSnapshots method is reserved for system use. + /// + /// Reserved for system use. Do not use. + /// Reserved for system use. Do not use. + /// Reserved for system use. Do not use. + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivsssnapshotmgmt-queryvolumessupportedforsnapshots HRESULT + // QueryVolumesSupportedForSnapshots( [in] VSS_ID ProviderId, [in] LONG lContext, [out] IVssEnumMgmtObject **ppEnum ); + IVssEnumMgmtObject QueryVolumesSupportedForSnapshots(Guid ProviderId, int lContext); + + /// + /// Not supported. + /// The QuerySnapshotsByVolume method is reserved for system use. + /// + /// Reserved for system use. Do not use. + /// Reserved for system use. Do not use. + /// Reserved for system use. Do not use. + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivsssnapshotmgmt-querysnapshotsbyvolume HRESULT + // QuerySnapshotsByVolume( [in] VSS_PWSZ pwszVolumeName, [in] VSS_ID ProviderId, [out] IVssEnumObject **ppEnum ); + IVssEnumObject QuerySnapshotsByVolume([MarshalAs(UnmanagedType.LPWStr)] string pwszVolumeName, Guid ProviderId); + } + + /// The IVssSnapshotMgmt2 interface provides a method to retrieve the minimum size of the shadow copy storage area. + /// + /// To obtain an instance of the IVssSnapshotMgmt2 interface, call the QueryInterface method of the IVssSnapshotMgmt interface, + /// passing IID_IVssSnapshotMgmt2 as the riid parameter. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nn-vsmgmt-ivsssnapshotmgmt2 + [PInvokeData("vsmgmt.h", MSDNShortId = "NN:vsmgmt.IVssSnapshotMgmt2")] + [ComImport, Guid("0f61ec39-fe82-45f2-a3f0-768b5d427102"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown), CoClass(typeof(VssSnapshotMgmt))] + public interface IVssSnapshotMgmt2 + { + /// Returns the current minimum size of the shadow copy storage area. + /// A pointer to a variable that receives the minimum size, in bytes, of the shadow copy storage area. + /// + /// The shadow copy storage area minimum size is a per-computer setting that is specified by the MinDiffAreaFileSize registry + /// key. For more information, see the entry for MinDiffAreaFileSize in Registry Keys and Values for Backup and Restore. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivsssnapshotmgmt2-getmindiffareasize HRESULT + // GetMinDiffAreaSize( [out] LONGLONG *pllMinDiffAreaSize ); + long GetMinDiffAreaSize(); + } + + /// + /// The VSS_DIFF_AREA_PROP structure describes associations between volumes containing the original file data and volumes + /// containing the shadow copy storage area (also known as the diff area). + /// + /// + /// The m_llMaximumDiffSpace member is passed as a parameter to the IVssDifferentialSoftwareSnapshotMgmt::AddDiffArea, + /// IVssDifferentialSoftwareSnapshotMgmt::ChangeDiffAreaMaximumSize, and + /// IVssDifferentialSoftwareSnapshotMgmt2::ChangeDiffAreaMaximumSizeEx methods. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/VsMgmt/ns-vsmgmt-vss_diff_area_prop typedef struct _VSS_DIFF_AREA_PROP { VSS_PWSZ + // m_pwszVolumeName; VSS_PWSZ m_pwszDiffAreaVolumeName; LONGLONG m_llMaximumDiffSpace; LONGLONG m_llAllocatedDiffSpace; LONGLONG + // m_llUsedDiffSpace; } VSS_DIFF_AREA_PROP, *PVSS_DIFF_AREA_PROP; + [PInvokeData("vsmgmt.h", MSDNShortId = "NS:vsmgmt._VSS_DIFF_AREA_PROP")] + [StructLayout(LayoutKind.Sequential)] + public struct VSS_DIFF_AREA_PROP + { + /// The original volume name. + [MarshalAs(UnmanagedType.LPWStr)] + public string m_pwszVolumeName; + + /// The shadow copy storage area volume name. + [MarshalAs(UnmanagedType.LPWStr)] + public string m_pwszDiffAreaVolumeName; + + /// Maximum space used on the shadow copy storage area volume for this association. + public long m_llMaximumDiffSpace; + + /// Allocated space on the shadow copy storage area volume by this association. This must be less than or equal to m_llMaximumDiffSpace. + public long m_llAllocatedDiffSpace; + + /// Used space from the allocated area above. This must be less than or equal to m_llAllocatedDiffSpace. + public long m_llUsedDiffSpace; + } + + /// The VSS_DIFF_VOLUME_PROP structure describes a shadow copy storage area volume. + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/ns-vsmgmt-vss_diff_volume_prop typedef struct _VSS_DIFF_VOLUME_PROP { + // VSS_PWSZ m_pwszVolumeName; VSS_PWSZ m_pwszVolumeDisplayName; LONGLONG m_llVolumeFreeSpace; LONGLONG m_llVolumeTotalSpace; } + // VSS_DIFF_VOLUME_PROP, *PVSS_DIFF_VOLUME_PROP; + [PInvokeData("vsmgmt.h", MSDNShortId = "NS:vsmgmt._VSS_DIFF_VOLUME_PROP")] + [StructLayout(LayoutKind.Sequential)] + public struct VSS_DIFF_VOLUME_PROP + { + /// The shadow copy storage area volume name, in \\?\ Volume { GUID }\ format. + [MarshalAs(UnmanagedType.LPWStr)] + public string m_pwszVolumeName; + + /// + /// Points to a null-terminated Unicode string that can be displayed to a user, for example C :\, for the shadow copy storage + /// area volume. + /// + [MarshalAs(UnmanagedType.LPWStr)] + public string m_pwszVolumeDisplayName; + + /// Free space, in bytes, on the shadow copy storage area volume. + public long m_llVolumeFreeSpace; + + /// Total space, in bytes, on the shadow copy storage area volume. + public long m_llVolumeTotalSpace; + } + + /// + /// The VSS_MGMT_OBJECT_PROP structure defines the properties of a volume, shadow copy storage volume, or a shadow copy storage area. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/ns-vsmgmt-vss_mgmt_object_prop typedef struct _VSS_MGMT_OBJECT_PROP { + // VSS_MGMT_OBJECT_TYPE Type; VSS_MGMT_OBJECT_UNION Obj; } VSS_MGMT_OBJECT_PROP, *PVSS_MGMT_OBJECT_PROP; + [PInvokeData("vsmgmt.h", MSDNShortId = "NS:vsmgmt._VSS_MGMT_OBJECT_PROP")] + [StructLayout(LayoutKind.Sequential)] + public struct VSS_MGMT_OBJECT_PROP + { + /// Object type. For more information, see VSS_MGMT_OBJECT_TYPE. + public VSS_MGMT_OBJECT_TYPE Type; /// /// - /// The IVssEnumMgmtObject interface contains methods to iterate over and perform other operations on a list of enumerated objects. + /// Management object properties: a union of VSS_VOLUME_PROP, VSS_DIFF_VOLUME_PROP, and VSS_DIFF_AREA_PROP structures. (For more + /// information, see VSS_MGMT_OBJECT_UNION.) /// /// - /// The calling application is responsible for calling IUnknown::Release to release the resources held by the returned - /// IVssEnumMgmtObject when it is no longer needed. It may also need to call IUnknown::Release to release temporary - /// objects (such as strings) returned during enumeration. - /// - /// - /// The IVssDifferentialSoftwareSnapshotMgmt::QueryDiffAreasForSnapshot, - /// IVssDifferentialSoftwareSnapshotMgmt::QueryDiffAreasForVolume, IVssDifferentialSoftwareSnapshotMgmt::QueryDiffAreasOnVolume, and - /// IVssDifferentialSoftwareSnapshotMgmt::QueryVolumesSupportedForDiffAreas methods return an IVssEnumMgmtObject object. + /// It contains information for an object of the type specified by the Type member. Management objects can be volumes, shadow + /// copy storage volumes, or shadow copy storage areas. /// /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nn-vsmgmt-ivssenummgmtobject - [PInvokeData("vsmgmt.h", MSDNShortId = "NN:vsmgmt.IVssEnumMgmtObject")] - [ComImport, Guid("01954E6B-9254-4e6e-808C-C9E05D007696"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IVssEnumMgmtObject : ICOMEnum - { - /// The Next method returns the specified number of objects from the specified list of enumerated objects. - /// The number of elements to be read from the list of enumerated objects into the rgelt buffer. - /// - /// The address of a caller-allocated buffer that receives celtVSS_MGMT_OBJECT_PROP structures that contain the returned - /// objects. This parameter is required and cannot be NULL. - /// - /// The number of elements that were returned in the rgelt buffer. - /// If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssenummgmtobject-next HRESULT Next( [in] ULONG celt, - // [out] VSS_MGMT_OBJECT_PROP *rgelt, [out] ULONG *pceltFetched ); - [PreserveSig] - HRESULT Next(uint celt, [Out, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] VSS_MGMT_OBJECT_PROP[] rgelt, out uint pceltFetched); + public VSS_MGMT_OBJECT_UNION Obj; + } - /// The Skip method skips the specified number of objects. - /// Number of elements to be skipped in the list of enumerated objects. - /// If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssenummgmtobject-skip HRESULT Skip( [in] ULONG celt ); - [PreserveSig] - HRESULT Skip(uint celt); + /// + /// The VSS_MGMT_OBJECT_UNION specifies the union of object types that can be defined by the VSS_MGMT_OBJECT_PROP structure (section 2.2.3.6). + /// + [PInvokeData("vsmgmt.h", MSDNShortId = "NS:vsmgmt._VSS_MGMT_OBJECT_PROP")] + [StructLayout(LayoutKind.Explicit)] + public struct VSS_MGMT_OBJECT_UNION + { + /// The structure specifies an original volume object as a VSS_VOLUME_PROP structure (section 2.2.3.7). + [FieldOffset(0)] + public VSS_VOLUME_PROP Vol; - /// The Reset method resets the enumerator so that IVssEnumMgmtObject starts at the first enumerated object. - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssenummgmtobject-reset HRESULT Reset(); - void Reset(); + /// The structure specifies a shadow copy storage volume as a VSS_DIFF_VOLUME_PROP structure. + [FieldOffset(0)] + public VSS_DIFF_VOLUME_PROP DiffVol; - /// - /// The Clone method creates a copy of the specified list of enumerated elements by creating a copy of the - /// IVssEnumMgmtObject enumerator object. - /// - /// - /// Address of an IVssEnumMgmtObject interface pointer. Set the value of this parameter to NULL before calling this method. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivssenummgmtobject-clone HRESULT Clone( [in, out] - // IVssEnumMgmtObject **ppenum ); - IVssEnumMgmtObject Clone(); - } + /// The structure specifies a shadow copy storage object as a VSS_DIFF_AREA_PROP. + [FieldOffset(0)] + public VSS_DIFF_AREA_PROP DiffArea; + } + /// The VSS_VOLUME_PROP structure contains the properties of a shadow copy source volume. + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/ns-vsmgmt-vss_volume_prop typedef struct _VSS_VOLUME_PROP { VSS_PWSZ + // m_pwszVolumeName; VSS_PWSZ m_pwszVolumeDisplayName; } VSS_VOLUME_PROP, *PVSS_VOLUME_PROP; + [PInvokeData("vsmgmt.h", MSDNShortId = "NS:vsmgmt._VSS_VOLUME_PROP")] + [StructLayout(LayoutKind.Sequential)] + public struct VSS_VOLUME_PROP + { + /// The volume name, in \?\Volume{GUID}\ format. + [MarshalAs(UnmanagedType.LPWStr)] + public string m_pwszVolumeName; + + /// + /// A pointer to a null-terminated Unicode string that contains the shortest mount point that can be displayed to the user. The + /// mount point can be a drive letter, for example, C:, or a mounted folder, for example, C:\WriterData\Archive. + /// + [MarshalAs(UnmanagedType.LPWStr)] + public string m_pwszVolumeDisplayName; + } + + /// Contains information about a volume's shadow copy protection level. + // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/ns-vsmgmt-vss_volume_protection_info typedef struct + // _VSS_VOLUME_PROTECTION_INFO { VSS_PROTECTION_LEVEL m_protectionLevel; BOOL m_volumeIsOfflineForProtection; VSS_PROTECTION_FAULT + // m_protectionFault; LONG m_failureStatus; BOOL m_volumeHasUnusedDiffArea; DWORD m_reserved; } VSS_VOLUME_PROTECTION_INFO, *PVSS_VOLUME_PROTECTION_INFO; + [PInvokeData("vsmgmt.h", MSDNShortId = "NS:vsmgmt._VSS_VOLUME_PROTECTION_INFO")] + [StructLayout(LayoutKind.Sequential)] + public struct VSS_VOLUME_PROTECTION_INFO + { + /// A value from the VSS_PROTECTION_LEVEL enumeration that specifies the target protection level for the volume. + public VSS_PROTECTION_LEVEL m_protectionLevel; + + /// TRUE if the volume is offline due to a protection fault, or FALSE otherwise. + [MarshalAs(UnmanagedType.Bool)] + public bool m_volumeIsOfflineForProtection; + + /// + /// A value from the VSS_PROTECTION_FAULT enumeration that describes the shadow copy protection fault that caused the volume to go offline. + /// + public VSS_PROTECTION_FAULT m_protectionFault; + + /// The internal failure status code. + public int m_failureStatus; + + /// TRUE if the volume has unused shadow copy storage area files, or FALSE otherwise. + [MarshalAs(UnmanagedType.Bool)] + public bool m_volumeHasUnusedDiffArea; + + /// Reserved for system use. + public uint m_reserved; + } + + /// VSS extension methods. + public static partial class Extensions + { /// Enumerates the instances provided by an . /// The instance. /// A sequence of structures. public static IEnumerable Enumerate(this IVssEnumMgmtObject emo) => new IEnumFromCom(emo.Next, emo.Reset); - /// - /// The IVssSnapshotMgmt interface provides a method that returns an interface to further configure a shadow copy provider. - /// - /// - /// - /// The IVssSnapshotMgmt interface can be invoked remotely using DCOM. The caller must be a member of the local - /// administrators group on the remote machine. - /// - /// Examples - /// - /// GetProviderMgmtInterface(ProviderId, IID_IVssDifferentialSoftwareSnapshotMgmt, (IUnknown**)&pDiffMgmt); - /// if (FAILED(hr)) - /// { - /// pMgmt->Release(); - /// } - /// - /// // processing code - /// pDiffMgmt->Release(); - /// pMgmt->Release(); - /// }]]> - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nn-vsmgmt-ivsssnapshotmgmt - [PInvokeData("vsmgmt.h", MSDNShortId = "NN:vsmgmt.IVssSnapshotMgmt")] - [ComImport, Guid("FA7DF749-66E7-4986-A27F-E2F04AE53772"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown), CoClass(typeof(VssSnapshotMgmt))] - public interface IVssSnapshotMgmt - { - /// The GetProviderMgmtInterface method returns an interface to further configure the system provider. - /// - /// This must be the system provider. The VSS_ID for the system provider - /// {b5946137-7b9f-4925-af80-51abd60b20d5} - /// . - /// - /// - /// Must be IID_IVssDifferentialSoftwareSnapshotMgmt, which represents the IVssDifferentialSoftwareSnapshotMgmt interface. - /// - /// Address of an interface pointer that is filled in with the returned interface pointer. - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivsssnapshotmgmt-getprovidermgmtinterface HRESULT - // GetProviderMgmtInterface( [in] VSS_ID ProviderId, [in] REFIID InterfaceId, [out] IUnknown **ppItf ); - [return: MarshalAs(UnmanagedType.IUnknown)] - object GetProviderMgmtInterface(Guid ProviderId, in Guid InterfaceId); - - /// - /// Not supported. - /// The QueryVolumesSupportedForSnapshots method is reserved for system use. - /// - /// Reserved for system use. Do not use. - /// Reserved for system use. Do not use. - /// Reserved for system use. Do not use. - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivsssnapshotmgmt-queryvolumessupportedforsnapshots - // HRESULT QueryVolumesSupportedForSnapshots( [in] VSS_ID ProviderId, [in] LONG lContext, [out] IVssEnumMgmtObject **ppEnum ); - IVssEnumMgmtObject QueryVolumesSupportedForSnapshots(Guid ProviderId, int lContext); - - /// - /// Not supported. - /// The QuerySnapshotsByVolume method is reserved for system use. - /// - /// Reserved for system use. Do not use. - /// Reserved for system use. Do not use. - /// Reserved for system use. Do not use. - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivsssnapshotmgmt-querysnapshotsbyvolume HRESULT - // QuerySnapshotsByVolume( [in] VSS_PWSZ pwszVolumeName, [in] VSS_ID ProviderId, [out] IVssEnumObject **ppEnum ); - IVssEnumObject QuerySnapshotsByVolume([MarshalAs(UnmanagedType.LPWStr)] string pwszVolumeName, Guid ProviderId); - } - - /// - /// The IVssSnapshotMgmt2 interface provides a method to retrieve the minimum size of the shadow copy storage area. - /// - /// - /// To obtain an instance of the IVssSnapshotMgmt2 interface, call the QueryInterface method of the IVssSnapshotMgmt - /// interface, passing IID_IVssSnapshotMgmt2 as the riid parameter. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nn-vsmgmt-ivsssnapshotmgmt2 - [PInvokeData("vsmgmt.h", MSDNShortId = "NN:vsmgmt.IVssSnapshotMgmt2")] - [ComImport, Guid("0f61ec39-fe82-45f2-a3f0-768b5d427102"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown), CoClass(typeof(VssSnapshotMgmt))] - public interface IVssSnapshotMgmt2 - { - /// Returns the current minimum size of the shadow copy storage area. - /// A pointer to a variable that receives the minimum size, in bytes, of the shadow copy storage area. - /// - /// The shadow copy storage area minimum size is a per-computer setting that is specified by the MinDiffAreaFileSize - /// registry key. For more information, see the entry for MinDiffAreaFileSize in Registry Keys and Values for Backup and Restore. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/nf-vsmgmt-ivsssnapshotmgmt2-getmindiffareasize HRESULT - // GetMinDiffAreaSize( [out] LONGLONG *pllMinDiffAreaSize ); - long GetMinDiffAreaSize(); - } - /// The GetProviderMgmtInterface method returns an interface to further configure the system provider. /// The instance. /// @@ -911,168 +1051,10 @@ namespace Vanara.PInvoke /// /// An interface pointer that is filled in with the returned interface pointer. public static T GetProviderMgmtInterface(this IVssSnapshotMgmt sm, Guid ProviderId) where T : class => (T)sm.GetProviderMgmtInterface(ProviderId, typeof(T).GUID); - - /// - /// The VSS_DIFF_AREA_PROP structure describes associations between volumes containing the original file data and volumes - /// containing the shadow copy storage area (also known as the diff area). - /// - /// - /// The m_llMaximumDiffSpace member is passed as a parameter to the IVssDifferentialSoftwareSnapshotMgmt::AddDiffArea, - /// IVssDifferentialSoftwareSnapshotMgmt::ChangeDiffAreaMaximumSize, and - /// IVssDifferentialSoftwareSnapshotMgmt2::ChangeDiffAreaMaximumSizeEx methods. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/VsMgmt/ns-vsmgmt-vss_diff_area_prop typedef struct _VSS_DIFF_AREA_PROP { - // VSS_PWSZ m_pwszVolumeName; VSS_PWSZ m_pwszDiffAreaVolumeName; LONGLONG m_llMaximumDiffSpace; LONGLONG m_llAllocatedDiffSpace; - // LONGLONG m_llUsedDiffSpace; } VSS_DIFF_AREA_PROP, *PVSS_DIFF_AREA_PROP; - [PInvokeData("vsmgmt.h", MSDNShortId = "NS:vsmgmt._VSS_DIFF_AREA_PROP")] - [StructLayout(LayoutKind.Sequential)] - public struct VSS_DIFF_AREA_PROP - { - /// The original volume name. - [MarshalAs(UnmanagedType.LPWStr)] - public string m_pwszVolumeName; - - /// The shadow copy storage area volume name. - [MarshalAs(UnmanagedType.LPWStr)] - public string m_pwszDiffAreaVolumeName; - - /// Maximum space used on the shadow copy storage area volume for this association. - public long m_llMaximumDiffSpace; - - /// - /// Allocated space on the shadow copy storage area volume by this association. This must be less than or equal to m_llMaximumDiffSpace. - /// - public long m_llAllocatedDiffSpace; - - /// Used space from the allocated area above. This must be less than or equal to m_llAllocatedDiffSpace. - public long m_llUsedDiffSpace; - } - - /// The VSS_DIFF_VOLUME_PROP structure describes a shadow copy storage area volume. - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/ns-vsmgmt-vss_diff_volume_prop typedef struct _VSS_DIFF_VOLUME_PROP { - // VSS_PWSZ m_pwszVolumeName; VSS_PWSZ m_pwszVolumeDisplayName; LONGLONG m_llVolumeFreeSpace; LONGLONG m_llVolumeTotalSpace; } - // VSS_DIFF_VOLUME_PROP, *PVSS_DIFF_VOLUME_PROP; - [PInvokeData("vsmgmt.h", MSDNShortId = "NS:vsmgmt._VSS_DIFF_VOLUME_PROP")] - [StructLayout(LayoutKind.Sequential)] - public struct VSS_DIFF_VOLUME_PROP - { - /// The shadow copy storage area volume name, in \\?\ Volume { GUID }\ format. - [MarshalAs(UnmanagedType.LPWStr)] - public string m_pwszVolumeName; - - /// - /// Points to a null-terminated Unicode string that can be displayed to a user, for example C :\, for the shadow copy - /// storage area volume. - /// - [MarshalAs(UnmanagedType.LPWStr)] - public string m_pwszVolumeDisplayName; - - /// Free space, in bytes, on the shadow copy storage area volume. - public long m_llVolumeFreeSpace; - - /// Total space, in bytes, on the shadow copy storage area volume. - public long m_llVolumeTotalSpace; - } - - /// - /// The VSS_MGMT_OBJECT_PROP structure defines the properties of a volume, shadow copy storage volume, or a shadow copy - /// storage area. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/ns-vsmgmt-vss_mgmt_object_prop typedef struct _VSS_MGMT_OBJECT_PROP { - // VSS_MGMT_OBJECT_TYPE Type; VSS_MGMT_OBJECT_UNION Obj; } VSS_MGMT_OBJECT_PROP, *PVSS_MGMT_OBJECT_PROP; - [PInvokeData("vsmgmt.h", MSDNShortId = "NS:vsmgmt._VSS_MGMT_OBJECT_PROP")] - [StructLayout(LayoutKind.Sequential)] - public struct VSS_MGMT_OBJECT_PROP - { - /// Object type. For more information, see VSS_MGMT_OBJECT_TYPE. - public VSS_MGMT_OBJECT_TYPE Type; - - /// - /// - /// Management object properties: a union of VSS_VOLUME_PROP, VSS_DIFF_VOLUME_PROP, and VSS_DIFF_AREA_PROP structures. (For more - /// information, see VSS_MGMT_OBJECT_UNION.) - /// - /// - /// It contains information for an object of the type specified by the Type member. Management objects can be volumes, - /// shadow copy storage volumes, or shadow copy storage areas. - /// - /// - public VSS_MGMT_OBJECT_UNION Obj; - } - - /// - /// The VSS_MGMT_OBJECT_UNION specifies the union of object types that can be defined by the VSS_MGMT_OBJECT_PROP structure (section 2.2.3.6). - /// - [PInvokeData("vsmgmt.h", MSDNShortId = "NS:vsmgmt._VSS_MGMT_OBJECT_PROP")] - [StructLayout(LayoutKind.Explicit)] - public struct VSS_MGMT_OBJECT_UNION - { - /// The structure specifies an original volume object as a VSS_VOLUME_PROP structure (section 2.2.3.7). - [FieldOffset(0)] - public VSS_VOLUME_PROP Vol; - - /// The structure specifies a shadow copy storage volume as a VSS_DIFF_VOLUME_PROP structure. - [FieldOffset(0)] - public VSS_DIFF_VOLUME_PROP DiffVol; - - /// The structure specifies a shadow copy storage object as a VSS_DIFF_AREA_PROP. - [FieldOffset(0)] - public VSS_DIFF_AREA_PROP DiffArea; - } - - /// The VSS_VOLUME_PROP structure contains the properties of a shadow copy source volume. - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/ns-vsmgmt-vss_volume_prop typedef struct _VSS_VOLUME_PROP { VSS_PWSZ - // m_pwszVolumeName; VSS_PWSZ m_pwszVolumeDisplayName; } VSS_VOLUME_PROP, *PVSS_VOLUME_PROP; - [PInvokeData("vsmgmt.h", MSDNShortId = "NS:vsmgmt._VSS_VOLUME_PROP")] - [StructLayout(LayoutKind.Sequential)] - public struct VSS_VOLUME_PROP - { - /// The volume name, in \?\Volume{GUID}\ format. - [MarshalAs(UnmanagedType.LPWStr)] - public string m_pwszVolumeName; - - /// - /// A pointer to a null-terminated Unicode string that contains the shortest mount point that can be displayed to the user. The - /// mount point can be a drive letter, for example, C:, or a mounted folder, for example, C:\WriterData\Archive. - /// - [MarshalAs(UnmanagedType.LPWStr)] - public string m_pwszVolumeDisplayName; - } - - /// Contains information about a volume's shadow copy protection level. - // https://docs.microsoft.com/en-us/windows/win32/api/vsmgmt/ns-vsmgmt-vss_volume_protection_info typedef struct - // _VSS_VOLUME_PROTECTION_INFO { VSS_PROTECTION_LEVEL m_protectionLevel; BOOL m_volumeIsOfflineForProtection; VSS_PROTECTION_FAULT - // m_protectionFault; LONG m_failureStatus; BOOL m_volumeHasUnusedDiffArea; DWORD m_reserved; } VSS_VOLUME_PROTECTION_INFO, *PVSS_VOLUME_PROTECTION_INFO; - [PInvokeData("vsmgmt.h", MSDNShortId = "NS:vsmgmt._VSS_VOLUME_PROTECTION_INFO")] - [StructLayout(LayoutKind.Sequential)] - public struct VSS_VOLUME_PROTECTION_INFO - { - /// A value from the VSS_PROTECTION_LEVEL enumeration that specifies the target protection level for the volume. - public VSS_PROTECTION_LEVEL m_protectionLevel; - - /// TRUE if the volume is offline due to a protection fault, or FALSE otherwise. - [MarshalAs(UnmanagedType.Bool)] - public bool m_volumeIsOfflineForProtection; - - /// - /// A value from the VSS_PROTECTION_FAULT enumeration that describes the shadow copy protection fault that caused the volume to - /// go offline. - /// - public VSS_PROTECTION_FAULT m_protectionFault; - - /// The internal failure status code. - public int m_failureStatus; - - /// TRUE if the volume has unused shadow copy storage area files, or FALSE otherwise. - [MarshalAs(UnmanagedType.Bool)] - public bool m_volumeHasUnusedDiffArea; - - /// Reserved for system use. - public uint m_reserved; - } - - /// CLSID_VssSnapshotMgmt - [ComImport, Guid("0B5A2C52-3EB9-470a-96E2-6C6D4570E40F"), ClassInterface(ClassInterfaceType.None)] - public class VssSnapshotMgmt { } } + + /// CLSID_VssSnapshotMgmt + [ComImport, Guid("0B5A2C52-3EB9-470a-96E2-6C6D4570E40F"), ClassInterface(ClassInterfaceType.None)] + public class VssSnapshotMgmt + { } } \ No newline at end of file diff --git a/PInvoke/VssApi/vsprov.cs b/PInvoke/VssApi/vsprov.cs new file mode 100644 index 00000000..4b067ab7 --- /dev/null +++ b/PInvoke/VssApi/vsprov.cs @@ -0,0 +1,2197 @@ +using System; +using System.Runtime.InteropServices; + +namespace Vanara.PInvoke.VssApi +{ + /// Contains the methods used by VSS to manage shadow copy volumes. + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nn-vsprov-ivssfilesharesnapshotprovider + [PInvokeData("vsprov.h", MSDNShortId = "NN:vsprov.IVssFileShareSnapshotProvider")] + [ComImport, Guid("c8636060-7c2e-11df-8c4a-0800200c9a66"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IVssFileShareSnapshotProvider + { + /// Sets the context for the subsequent shadow copy-related operations. + /// + /// The context to be set. The context must be one of the supported values of _VSS_SNAPSHOT_CONTEXT or a supported combination of + /// _VSS_VOLUME_SNAPSHOT_ATTRIBUTES and _VSS_SNAPSHOT_CONTEXT values. + /// + /// + /// The following are the valid return codes for this method. + /// + /// + /// Value + /// Meaning + /// + /// + /// S_OK + /// The context was set successfully. + /// + /// + /// E_ACCESSDENIED + /// The caller does not have sufficient backup privileges or is not an administrator. + /// + /// + /// 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 context is frozen and cannot be changed. + /// + /// + /// + /// + /// The default context for VSS shadow copies is VSS_CTX_BACKUP. + /// + /// Windows XP: The only supported context is the default context, VSS_CTX_BACKUP. Therefore, calling SetContext under + /// Windows XP returns E_NOTIMPL. + /// + /// + /// For more information about how the context that is set by SetContext affects how a shadow copy is created and managed, see + /// Implementation Details for Creating Shadow Copies. + /// + /// For a complete discussion of the permitted shadow copy contexts, see _VSS_SNAPSHOT_CONTEXT and _VSS_VOLUME_SNAPSHOT_ATTRIBUTES. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivssfilesharesnapshotprovider-setcontext HRESULT SetContext( + // [in] LONG lContext ); + [PreserveSig] + HRESULT SetContext(VSS_SNAPSHOT_CONTEXT lContext); + + /// Gets the VSS_SNAPSHOT_PROP structure for a file share snapshot. + /// Shadow copy identifier. + /// + /// The address of a caller-allocated VSS_SNAPSHOT_PROP structure that receives the shadow copy properties. The provider is + /// responsible for setting the members of this structure. All members are required except m_pwszExposedName and + /// m_pwszExposedPath, which the provider can set to NULL. The provider allocates memory for all string members that + /// it sets in the structure. When the structure is no longer needed, the caller is responsible for freeing these strings by calling + /// the VssFreeSnapshotProperties function. + /// + /// + /// The following are the valid return codes for this method. + /// + /// + /// Value + /// Meaning + /// + /// + /// S_OK + /// The requested information was successfully returned. + /// + /// + /// E_ACCESSDENIED + /// The caller does not have sufficient backup privileges or is not an administrator. + /// + /// + /// E_INVALIDARG + /// One of the parameter values is not valid. + /// + /// + /// E_OUTOFMEMORY + /// The caller is out of memory or other system resources. + /// + /// + /// VSS_E_OBJECT_NOT_FOUND + /// The specified volume was not found. + /// + /// + /// VSS_E_PROVIDER_VETO + /// + /// Provider error. The provider logged the error in the event log. For more information, see Event and Error Handling Under VSS. + /// + /// + /// + /// 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. + /// + /// + /// + /// + /// + /// + /// The caller should set the contents of the VSS_SNAPSHOT_PROP structure to zero before calling the GetSnapshotProperties method. + /// + /// The provider is responsible for allocating and freeing the strings in the VSS_SNAPSHOT_PROP structure. + /// + /// The VSS coordinator calls this method during the PostSnapshot phase of snapshot creation in order to retrieve the snapshot + /// access path (UNC path for file share snapshots). The coordinator calls this method after PreFinalCommitSnapshots and before it + /// invokes PostSnapshot in the writers. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivssfilesharesnapshotprovider-getsnapshotproperties HRESULT + // GetSnapshotProperties( [in] VSS_ID SnapshotId, [out] VSS_SNAPSHOT_PROP *pProp ); + [PreserveSig] + HRESULT GetSnapshotProperties(Guid SnapshotId, out VSS_SNAPSHOT_PROP pProp); + + /// + /// Gets an enumeration of VSS_SNAPSHOT_PROP structures for all file share snapshots that are available to the application server. + /// + /// Reserved for system use. The value of this parameter must be GUID_NULL. + /// Reserved for system use. The value of this parameter must be VSS_OBJECT_NONE. + /// Reserved for system use. The value of this parameter must be VSS_OBJECT_SNAPSHOT. + /// + /// The address of an IVssEnumObject interface pointer, which is initialized on return. Callers must release the interface. This + /// parameter is required and cannot be null. + /// + /// + /// The following are the valid return codes for this method. + /// + /// + /// Value + /// Meaning + /// + /// + /// S_OK + /// The query operation was successful. + /// + /// + /// E_ACCESSDENIED + /// The caller does not have sufficient backup privileges or is not an administrator. + /// + /// + /// E_INVALIDARG + /// One of the parameter values is not valid. + /// + /// + /// E_OUTOFMEMORY + /// The caller is out of memory or other system resources. + /// + /// + /// VSS_E_PROVIDER_VETO + /// + /// Provider error. The provider logged the error in the event log. For more information, see Event and Error Handling Under VSS. + /// + /// + /// + /// + /// + /// This method is typically called in response to requester generated snapshot query operations. + /// + /// Calling the IVssEnumObject::Next method on the IVssEnumObject interface that is returned though the ppEnum parameter will + /// return VSS_OBJECT_PROP structures containing a VSS_SNAPSHOT_PROP structure for each shadow copy. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivssfilesharesnapshotprovider-query HRESULT Query( [in] + // VSS_ID QueriedObjectId, [in] VSS_OBJECT_TYPE eQueriedObjectType, [in] VSS_OBJECT_TYPE eReturnedObjectsType, [out] IVssEnumObject + // **ppEnum ); + [PreserveSig] + HRESULT Query(Guid QueriedObjectId, VSS_OBJECT_TYPE eQueriedObjectType, VSS_OBJECT_TYPE eReturnedObjectsType, out IVssEnumObject ppEnum); + + /// Deletes specific snapshots, or all snapshots in a specified snapshot set. + /// Identifier of the shadow copy or shadow copy set to be deleted. + /// Type of the object to be deleted. The value of this parameter is VSS_OBJECT_SNAPSHOT or VSS_OBJECT_SNAPSHOT_SET. + /// + /// If the value of this parameter is TRUE, the provider will do everything possible to delete the shadow copy or shadow + /// copies in a shadow copy set. If it is FALSE, no additional effort will be made. + /// + /// Pointer to a variable that receives the number of shadow copies that were deleted. + /// + /// If an error occurs, this parameter receives a pointer to the identifier of the first shadow copy that could not be deleted. + /// Otherwise, it points to GUID_NULL. + /// + /// + /// The following are the valid return codes for this method. + /// + /// + /// Value + /// Meaning + /// + /// + /// S_OK + /// The shadow copies were successfully deleted. + /// + /// + /// E_ACCESSDENIED + /// The caller does not have sufficient backup privileges or is not an administrator. + /// + /// + /// E_INVALIDARG + /// One of the parameter values is not valid. + /// + /// + /// E_OUTOFMEMORY + /// The caller is out of memory or other system resources. + /// + /// + /// VSS_E_OBJECT_NOT_FOUND + /// The specified shadow copies were not found. + /// + /// + /// VSS_E_PROVIDER_VETO + /// + /// Provider error. The provider logged the error in the event log. For more information, see Event and Error Handling Under VSS. + /// + /// + /// + /// + /// + /// The VSS coordinator calls this method as part of the snapshot auto-release process. The method is also called in response to + /// requester driven delete operations. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivssfilesharesnapshotprovider-deletesnapshots HRESULT + // DeleteSnapshots( [in] VSS_ID SourceObjectId, [in] VSS_OBJECT_TYPE eSourceObjectType, [in] BOOL bForceDelete, [out] LONG + // *plDeletedSnapshots, [out] VSS_ID *pNondeletedSnapshotID ); + [PreserveSig] + HRESULT DeleteSnapshots(Guid SourceObjectId, VSS_OBJECT_TYPE eSourceObjectType, [MarshalAs(UnmanagedType.Bool)] bool bForceDelete, out int plDeletedSnapshots, out Guid pNondeletedSnapshotID); + + /// VSS calls this method for each shadow copy that is added to the shadow copy set. + /// Shadow copy set identifier. + /// Identifier of the shadow copy to be created. + /// The file share path. + /// + /// The context for the shadow copy set. This context consists of a bitmask of _VSS_VOLUME_SNAPSHOT_ATTRIBUTES values. + /// + /// The provider ID. + /// + /// The following are the valid return codes for this method. + /// + /// + /// Value + /// Meaning + /// + /// + /// S_OK + /// The shadow copy was successfully created. + /// + /// + /// E_ACCESSDENIED + /// The caller does not have sufficient backup privileges or is not an administrator. + /// + /// + /// E_INVALIDARG + /// One of the parameter values is not valid. + /// + /// + /// E_OUTOFMEMORY + /// The caller is out of memory or other system resources. + /// + /// + /// VSS_E_OBJECT_NOT_FOUND + /// The specified volume was not found. + /// + /// + /// VSS_E_PROVIDER_VETO + /// + /// Provider error. The provider logged the error in the event log. For more information, see Event and Error Handling Under VSS. + /// + /// + /// + /// VSS_E_UNSUPPORTED_CONTEXT + /// The specified context is not supported. + /// + /// + /// VSS_E_VOLUME_NOT_SUPPORTED_BY_PROVIDER + /// The provider does not support the specified volume. + /// + /// + /// 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. + /// + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivssfilesharesnapshotprovider-beginpreparesnapshot HRESULT + // BeginPrepareSnapshot( [in] VSS_ID SnapshotSetId, [in] VSS_ID SnapshotId, [in] VSS_PWSZ pwszSharePath, [in] LONG lNewContext, [in] + // VSS_ID ProviderId ); + [PreserveSig] + HRESULT BeginPrepareSnapshot(Guid SnapshotSetId, Guid SnapshotId, [MarshalAs(UnmanagedType.LPWStr)] string pwszSharePath, + VSS_VOLUME_SNAPSHOT_ATTRIBUTES lNewContext, Guid ProviderId); + + /// Determines whether the given Universal Naming Convention (UNC) path is supported by this provider. + /// The path to the file share. + /// + /// This parameter receives TRUE if shadow copies are supported on the specified volume, otherwise FALSE. + /// + /// + /// The following are the valid return codes for this method. + /// + /// + /// Value + /// Meaning + /// + /// + /// S_OK + /// The requested information was successfully returned. + /// + /// + /// E_ACCESSDENIED + /// The caller does not have sufficient backup privileges or is not an administrator. + /// + /// + /// E_INVALIDARG + /// One of the parameter values is not valid. + /// + /// + /// VSS_E_NESTED_VOLUME_LIMIT + /// + /// The specified volume is nested too deeply to participate in the VSS operation. Windows Server 2008, Windows Vista, Windows + /// Server 2003 and Windows XP: This return code is not supported. + /// + /// + /// + /// E_OUTOFMEMORY + /// The caller is out of memory or other system resources. + /// + /// + /// VSS_E_OBJECT_NOT_FOUND + /// The specified volume was not found. + /// + /// + /// VSS_E_PROVIDER_VETO + /// + /// Provider error. The provider logged the error in the event log. For more information, see Event and Error Handling Under VSS. + /// + /// + /// + /// 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. + /// + /// + /// + /// + /// + /// The VSS coordinator calls this method as part of AddToSnapshotSet to determine which provider to use for snapshot creation. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivssfilesharesnapshotprovider-ispathsupported HRESULT + // IsPathSupported( [in] VSS_PWSZ pwszSharePath, [out] BOOL *pbSupportedByThisProvider ); + [PreserveSig] + HRESULT IsPathSupported([MarshalAs(UnmanagedType.LPWStr)] string pwszSharePath, [MarshalAs(UnmanagedType.Bool)] out bool pbSupportedByThisProvider); + + /// Determines whether the given Universal Naming Convention (UNC) path currently has any snapshots. + /// The path to the file share. + /// + /// This parameter receives TRUE if the volume has a shadow copy, or FALSE if the volume does not have a shadow copy. + /// + /// + /// A bitmask of VSS_SNAPSHOT_COMPATIBILITY values that indicate whether certain volume control or file I/O operations are disabled + /// for the given volume, if the volume has a shadow copy. + /// + /// + /// The following are the valid return codes for this method. + /// + /// + /// Value + /// Meaning + /// + /// + /// S_OK + /// The requested information was successfully returned. + /// + /// + /// E_ACCESSDENIED + /// The caller does not have sufficient backup privileges or is not an administrator. + /// + /// + /// E_INVALIDARG + /// One of the parameter values is not valid. + /// + /// + /// E_OUTOFMEMORY + /// The caller is out of memory or other system resources. + /// + /// + /// VSS_E_OBJECT_NOT_FOUND + /// The specified volume was not found. + /// + /// + /// VSS_E_PROVIDER_VETO + /// + /// Provider error. The provider logged the error in the event log. For more information, see Event and Error Handling Under VSS. + /// + /// + /// + /// 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. + /// + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivssfilesharesnapshotprovider-ispathsnapshotted HRESULT + // IsPathSnapshotted( [in] VSS_PWSZ pwszSharePath, [out] BOOL *pbSnapshotsPresent, [out] LONG *plSnapshotCompatibility ); + [PreserveSig] + HRESULT IsPathSnapshotted([MarshalAs(UnmanagedType.LPWStr)] string pwszSharePath, [MarshalAs(UnmanagedType.Bool)] out bool pbSnapshotsPresent, + out VSS_SNAPSHOT_COMPATIBILITY plSnapshotCompatibility); + + /// Requests the provider to set a property value for the specified snapshot. + /// Shadow copy identifier. This parameter is required and cannot be GUID_NULL. + /// A VSS_SNAPSHOT_PROPERTY_ID value that specifies the property to be set for the shadow copy. + /// + /// The value to be set for the property. See the VSS_SNAPSHOT_PROP structure for valid data types and descriptions of the + /// properties that can be set for a shadow copy. + /// + /// + /// The following are the valid return codes for this method. + /// + /// + /// Value + /// Meaning + /// + /// + /// S_OK + /// The property was set successfully. + /// + /// + /// E_ACCESSDENIED + /// The caller does not have sufficient backup privileges or is not an administrator. + /// + /// + /// E_INVALIDARG + /// One of the parameter values is not valid. + /// + /// + /// E_OUTOFMEMORY + /// The caller is out of memory or other system resources. + /// + /// + /// VSS_E_OBJECT_NOT_FOUND + /// The specified shadow copy was not found. + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivssfilesharesnapshotprovider-setsnapshotproperty HRESULT + // SetSnapshotProperty( [in] VSS_ID SnapshotId, [in] VSS_SNAPSHOT_PROPERTY_ID eSnapshotPropertyId, [in] VARIANT vProperty ); + [PreserveSig] + HRESULT SetSnapshotProperty(Guid SnapshotId, VSS_SNAPSHOT_PROPERTY_ID eSnapshotPropertyId, object vProperty); + } + + /// + /// + /// The IVssHardwareSnapshotProvider interface contains the methods used by VSS to map volumes to LUNs, discover LUNs created + /// during the shadow copy process, and transport LUNs on a SAN. All hardware providers must support this interface. + /// + /// Note Hardware providers are only supported on Windows Server operating systems. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nn-vsprov-ivsshardwaresnapshotprovider + [PInvokeData("vsprov.h", MSDNShortId = "NN:vsprov.IVssHardwareSnapshotProvider")] + [ComImport, Guid("9593A157-44E9-4344-BBEB-44FBF9B06B10"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IVssHardwareSnapshotProvider + { + /// + /// + /// The AreLunsSupported method determines whether the hardware provider supports shadow copy creation for all LUNs that + /// contribute to the volume. VSS calls the AreLunsSupported method for each volume that is added to the shadow copy set. + /// Before calling this method, VSS determines the LUNs that contribute to the volume. + /// + /// For a specific volume, each LUN can contribute only once. A specific LUN may contribute to multiple volumes. + /// Note Hardware providers are only supported on Windows Server operating systems. + /// + /// Count of LUNs contributing to this shadow copy volume. + /// + /// Shadow copy context for the current shadow copy set as enumerated by a bitmask of flags from the _VSS_VOLUME_SNAPSHOT_ATTRIBUTES + /// enumeration. If the VSS_VOLSNAP_ATTR_TRANSPORTABLE flag is set, the shadow copy set is transportable. + /// + /// List of devices corresponding to the LUNs to be shadow copied. + /// + /// Array of lLunCount VDS_LUN_INFORMATION structures, one for each LUN contributing to this shadow copy volume. + /// + /// + /// Pointer to a BOOL value. If all devices are supported for shadow copy, the provider should store a TRUE value at + /// the location pointed to by pbIsSupported. + /// + /// + /// This method can return one of these values. + /// + /// + /// Return code/value + /// Description + /// + /// + /// S_OK 0x00000000L + /// The operation was successfully completed. + /// + /// + /// E_OUTOFMEMORY 0x8007000EL + /// Out of memory or other system resources. + /// + /// + /// E_INVALIDARG 0x80070057L + /// One of the parameter values is not valid. + /// + /// + /// VSS_E_PROVIDER_VETO 0x80042306L + /// + /// An unexpected provider error occurred. The provider must report an event in the application event log providing the user with + /// information on how to resolve the problem. + /// + /// + /// + /// + /// + /// + /// If the hardware subsystem supports the SCSI Inquiry Data and Vital Product Data page 80 (device serial number) and page 83 + /// (device identity) guidelines, the provider should not need to modify the structures in the pLunInformation array. + /// + /// + /// In any case, the AreLunsSupported method should not modify the value of the m_rgInterconnects member of any + /// VDS_LUN_INFORMATION structure in the pLunInformation array. + /// + /// + /// If the provider supports hardware shadow copy creation for all of the LUNs in the pLunInformation array, it should return + /// TRUE in the BOOL value that the pbIsSupported parameter points to. If the provider does not support + /// hardware shadow copies for one or more LUNs, it must set this BOOL value to FALSE. + /// + /// + /// The provider must never agree to create shadow copies if it cannot, even if the problem is only temporary. If a transient + /// condition, such as low resources, makes it impossible for the provider to create a shadow copy using one or more LUNs when + /// AreLunsSupported is called, the provider must set the BOOL value to FALSE. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivsshardwaresnapshotprovider-arelunssupported HRESULT + // AreLunsSupported( [in] LONG lLunCount, [in] LONG lContext, [in] VSS_PWSZ *rgwszDevices, [in, out] VDS_LUN_INFORMATION + // *pLunInformation, [out] BOOL *pbIsSupported ); + [PreserveSig] + HRESULT AreLunsSupported(int lLunCount, VSS_VOLUME_SNAPSHOT_ATTRIBUTES lContext, + [In, MarshalAs(UnmanagedType.LPArray, ArraySubType = UnmanagedType.LPWStr, SizeParamIndex = 0)] string[] rgwszDevices, + [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] VDS_LUN_INFORMATION[] pLunInformation, + [MarshalAs(UnmanagedType.Bool)] out bool pbIsSupported); + + /// + /// + /// The FillInLunInfo method prompts the hardware provider to indicate whether it supports the corresponding disk device and + /// correct any omissions in the VDS_LUN_INFORMATION structure. VSS calls the FillInLunInfo method after the + /// IVssHardwareSnapshotProvider::LocateLuns method or before the IVssHardwareSnapshotProvider::OnLunEmpty method to obtain the + /// VDS_LUN_INFORMATION structure associated with a shadow copy LUN. VSS will compare the VDS_LUN_INFORMATION structure + /// received in the IVssHardwareSnapshotProvider::GetTargetLuns method to identify shadow copy LUNs. If the structures do not match, + /// the requester will receive VSS_S_SOME_SNAPSHOTS_NOT_IMPORTED, which indicates a mismatch. + /// + /// Note Hardware providers are only supported on Windows Server operating systems. + /// + /// Device corresponding to the shadow copy LUN. + /// The VDS_LUN_INFORMATION structure for the shadow copy LUN. + /// + /// The provider must return TRUE in the location pointed to by the pbIsSupported parameter if the device is supported. + /// + /// + /// VSS ignores this method's return value. + /// Windows Server 2003: VSS does not ignore the return value, which can be one of the following values. + /// + /// + /// Return code/value + /// Description + /// + /// + /// S_OK 0x00000000L + /// The operation was successfully completed. + /// + /// + /// E_OUTOFMEMORY 0x8007000EL + /// Out of memory or other system resources. + /// + /// + /// E_INVALIDARG 0x80070057L + /// One of the parameter values is not valid. + /// + /// + /// VSS_E_PROVIDER_VETO 0x80042306L + /// + /// An unexpected provider error has occurred. The provider must report an event in the application event log providing the user + /// with information on how to resolve the problem. + /// + /// + /// + /// + /// + /// + /// VSS calls the FillInLunInfo method for each VDS_LUN_INFORMATION structure that the provider previously initialized in its + /// GetTargetLuns method. VSS also calls the FillInLunInfo method for each new disk device that arrives in the system during + /// the import process. + /// + /// + /// The provider can correct any omissions in the VDS_LUN_INFORMATION structure received in the pLunInfo parameter. However, + /// the provider should not modify the value of the m_rgInterconnects member of this structure. + /// + /// + /// The members of the VDS_LUN_INFORMATION structure correspond to the SCSI Inquiry Data and Vital Product Data page 80 (device + /// serial number) information, with the following exceptions: + /// + /// + /// + /// The m_version member must be set to VER_VDS_LUN_INFORMATION. + /// + /// + /// + /// The m_BusType member is ignored in comparisons during import. This value depends on the PnP storage stack on the + /// corresponding disk device. Usually this is VDSBusTypeScsi. + /// + /// + /// + /// The m_diskSignature member is ignored in comparisons during import. The provider must set this member to GUID_NULL. + /// + /// + /// + /// The members of the VDS_STORAGE_DEVICE_ID_DESCRIPTOR structure (in the m_deviceIdDescriptor member of the + /// VDS_LUN_INFORMATION structure) correspond to the page 83 information. In this structure, each VDS_STORAGE_IDENTIFIER structure + /// corresponds to the STORAGE_IDENTIFIER structure for a device identifier (that is, a storage identifier with an association type + /// of zero). For more information about the STORAGE_IDENTIFIER structure, see the Windows Driver Kit (WDK) documentation. + /// + /// + /// If the FillInLunInfo method is called for a LUN that is unknown to the provider, the provider should not return an error. + /// Instead, it should return FALSE in the BOOL value that the pbIsSupported parameter points to and return + /// success. If the provider recognizes the LUN, it should set the BOOL value to TRUE. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivsshardwaresnapshotprovider-fillinluninfo HRESULT + // FillInLunInfo( [in] VSS_PWSZ wszDeviceName, [in, out] VDS_LUN_INFORMATION *pLunInfo, [out] BOOL *pbIsSupported ); + [PreserveSig] + HRESULT FillInLunInfo([MarshalAs(UnmanagedType.LPWStr)] string wszDeviceName, ref VDS_LUN_INFORMATION pLunInfo, + [MarshalAs(UnmanagedType.Bool)] out bool pbIsSupported); + + /// + /// The BeginPrepareSnapshot method is called for each shadow copy that is added to the shadow copy set. + /// Note Hardware providers are only supported on Windows Server operating systems. + /// + /// Shadow copy set identifier. + /// Identifier of the shadow copy to be created. + /// Shadow copy context for current shadow copy set as enumerated by _VSS_VOLUME_SNAPSHOT_ATTRIBUTES. + /// Count of LUNs contributing to this shadow copy volume. + /// + /// Pointer to array of lLunCount pointers to strings, each string containing the name of a LUN to be shadow copied. + /// + /// + /// Pointer to array of lLunCount VDS_LUN_INFORMATION structures, one for each LUN contributing to this shadow copy volume. + /// + /// + /// This method can return one of these values. + /// + /// + /// Return code/value + /// Description + /// + /// + /// S_OK 0x00000000L + /// The operation was successfully completed. + /// + /// + /// E_OUTOFMEMORY 0x8007000EL + /// Out of memory or other system resources. + /// + /// + /// E_INVALIDARG 0x80070057L + /// One of the parameter values is not valid. + /// + /// + /// VSS_E_MAXIMUM_NUMBER_OF_VOLUMES_REACHED 0x80042312L + /// The provider has reached the maximum number of volumes it can support. + /// + /// + /// VSS_E_NESTED_VOLUME_LIMIT + /// + /// The specified volume is nested too deeply to participate in the VSS operation. Windows Server 2008, Windows Vista, Windows + /// Server 2003 and Windows XP: This return code is not supported. + /// + /// + /// + /// VSS_E_PROVIDER_VETO 0x80042306L + /// + /// An unexpected provider error occurred. The provider must report an event in the application event log providing the user with + /// information on how to resolve the problem. + /// + /// + /// + /// VSS_E_VOLUME_NOT_SUPPORTED_BY_PROVIDER 0x8004230EL + /// The provider does not support this volume. + /// + /// + /// VSS_E_UNSUPPORTED_CONTEXT 0x8004231BL + /// The context specified by lContext is not supported. + /// + /// + /// + /// + /// This method cannot be called for a virtual hard disk (VHD) that is nested inside another VHD. + /// Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: VHDs are not supported. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivsshardwaresnapshotprovider-beginpreparesnapshot HRESULT + // BeginPrepareSnapshot( [in] VSS_ID SnapshotSetId, [in] VSS_ID SnapshotId, [in] LONG lContext, [in] LONG lLunCount, [in] VSS_PWSZ + // *rgDeviceNames, [in, out] VDS_LUN_INFORMATION *rgLunInformation ); + [PreserveSig] + HRESULT BeginPrepareSnapshot(Guid SnapshotSetId, Guid SnapshotId, VSS_VOLUME_SNAPSHOT_ATTRIBUTES lContext, int lLunCount, + [In, MarshalAs(UnmanagedType.LPArray, ArraySubType = UnmanagedType.LPWStr, SizeParamIndex = 3)] string[] rgDeviceNames, + [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 3)] VDS_LUN_INFORMATION[] rgLunInformation); + + /// + /// + /// The GetTargetLuns method prompts the hardware provider to initialize the VDS_LUN_INFORMATION structures for the newly + /// created shadow copy LUNs. The GetTargetLuns method is called after the IVssProviderCreateSnapshotSet::PostCommitSnapshots + /// method. Identifying information for each newly created LUN is returned to VSS through VDS_LUN_INFORMATION structures. + /// + /// Note Hardware providers are only supported on Windows Server operating systems. + /// + /// Count of LUNs that contribute to the original volume. + /// + /// Pointer to an array of lLunCount pointers to strings. Each string contains the name of an original LUN to be shadow copied. + /// + /// + /// Pointer to an array of lLunCount VDS_LUN_INFORMATION structures, one for each LUN that contributes to the original volume. + /// + /// + /// Pointer to an array of lLunCount VDS_LUN_INFORMATION structures, one for each new shadow copy LUN created during shadow + /// copy processing. There should be a one-to-one correspondence between the elements of the rgSourceLuns and + /// rgDestinationLuns arrays. + /// + /// + /// This method can return one of these values. + /// + /// + /// Return code/value + /// Description + /// + /// + /// S_OK 0x00000000L + /// The operation was successfully completed. + /// + /// + /// E_OUTOFMEMORY 0x8007000EL + /// Out of memory or other system resources. + /// + /// + /// E_INVALIDARG 0x80070057L + /// One of the parameter values is not valid. + /// + /// + /// VSS_E_PROVIDER_VETO 0x80042306L + /// + /// An unexpected provider error occurred. The provider must report an event in the application event log providing the user with + /// information on how to resolve the problem. + /// + /// + /// + /// + /// + /// + /// In the rgDestinationLuns parameter, VSS supplies an empty VDS_LUN_INFORMATION structure for each newly created shadow + /// copy LUN. The shadow copy LUNs are not surfaced or visible to the system. The provider should initialize the members of the + /// VDS_LUN_INFORMATION structure with the appropriate SCSI Inquiry Data and Vital Product Data page 80 (device serial + /// number) and page 83 (device identity) information. The structure should contain correct member values such that the shadow copy + /// LUNs can be located by Windows from the original computer or any other computer connected to the SAN. + /// + /// The members of the VDS_LUN_INFORMATION structure correspond to the page 80 information, with the following exceptions: + /// + /// + /// The m_version member must be set to VER_VDS_LUN_INFORMATION. + /// + /// + /// + /// The m_BusType member is ignored in comparisons during import. This value depends on the PnP storage stack on the + /// corresponding disk device. Usually this is VDSBusTypeScsi. + /// + /// + /// + /// The m_diskSignature member is ignored in comparisons during import. The provider must set this member to GUID_NULL. + /// + /// + /// + /// The members of the VDS_STORAGE_DEVICE_ID_DESCRIPTOR structure (in the m_deviceIdDescriptor member of the + /// VDS_LUN_INFORMATION structure) correspond to the page 83 information. In this structure, each VDS_STORAGE_IDENTIFIER structure + /// corresponds to the STORAGE_IDENTIFIER structure for a device identifier (that is, a storage identifier with an association type + /// of zero). For more information about the STORAGE_IDENTIFIER structure, see the Windows Driver Kit (WDK) documentation. + /// + /// + /// The VDS_LUN_INFORMATION structures returned here must be the same as the structures provided in the + /// IVssHardwareSnapshotProvider::FillInLunInfo method during import so that VSS can use this information to identify the newly + /// arriving shadow copy LUNs at import. These same structures will be passed to the provider in the + /// IVssHardwareSnapshotProvider::LocateLuns method. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivsshardwaresnapshotprovider-gettargetluns HRESULT + // GetTargetLuns( [in] LONG lLunCount, [in] VSS_PWSZ *rgDeviceNames, [in] VDS_LUN_INFORMATION *rgSourceLuns, [in, out] + // VDS_LUN_INFORMATION *rgDestinationLuns ); + [PreserveSig] + HRESULT GetTargetLuns(int lLunCount, + [In, MarshalAs(UnmanagedType.LPArray, ArraySubType = UnmanagedType.LPWStr, SizeParamIndex = 0)] string[] rgDeviceNames, + [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] VDS_LUN_INFORMATION[] rgSourceLuns, + [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] VDS_LUN_INFORMATION[] rgDestinationLuns); + + /// + /// + /// The LocateLuns method prompts the hardware provider to make the shadow copy LUNs visible to the computer. The + /// LocateLuns method is called by VSS when a hardware shadow copy set is imported to a computer. The provider is responsible + /// for any unmasking (or "surfacing") at the hardware level. + /// + /// Note Hardware providers are only supported on Windows Server operating systems. + /// + /// Number of LUNs that contribute to this shadow copy set. + /// + /// Pointer to an array of iLunCount VDS_LUN_INFORMATION structures, one for each LUN that is part of the shadow copy set to + /// be imported. + /// + /// + /// This method can return one of these values. + /// + /// + /// Return code/value + /// Description + /// + /// + /// S_OK 0x00000000L + /// The operation was successfully completed. + /// + /// + /// E_OUTOFMEMORY 0x8007000EL + /// Out of memory or other system resources. + /// + /// + /// E_INVALIDARG 0x80070057L + /// One of the parameter values is not valid. + /// + /// + /// VSS_E_PROVIDER_VETO 0x80042306L + /// + /// An unexpected provider error occurred. The provider must report an event in the application event log providing the user with + /// information on how to resolve the problem. + /// + /// + /// + /// + /// + /// + /// In the rgSourceLuns parameter, VSS supplies the same array of VDS_LUN_INFORMATION structures that the provider previously + /// initialized in its IVssHardwareSnapshotProvider::GetTargetLuns method. For each VDS_LUN_INFORMATION structure in the + /// array, the provider should unmask (or "surface") the corresponding shadow copy LUN to the computer. + /// + /// + /// Immediately after this method returns, VSS will perform a rescan and enumeration to detect any arrived devices. This causes any + /// exposed LUNs to be discovered by the PnP manager. In parallel with listening for disk arrivals, VSS will also listen for hidden + /// volume arrivals. VSS will stop listening after all volumes that contribute to a shadow copy set appear in the system or a + /// time-out occurs. If some disk or volume devices fail to appear in this window, the requester will be told that only some of the + /// shadow copies were imported by VSS returning VSS_S_SOME_SNAPSHOTS_NOT_IMPORTED to the requester. The requester will also + /// receive the same error from VSS if the VDS_LUN_INFORMATION structures received from the GetTargetLuns and + /// IVssHardwareSnapshotProvider::FillInLunInfo methods do not match. + /// + /// This method cannot be used to map shadow copy LUNs as read-only. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivsshardwaresnapshotprovider-locateluns HRESULT LocateLuns( + // [in] LONG lLunCount, [in] VDS_LUN_INFORMATION *rgSourceLuns ); + [PreserveSig] + HRESULT LocateLuns(int lLunCount, [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] VDS_LUN_INFORMATION[] rgSourceLuns); + + /// + /// + /// The OnLunEmpty method is called whenever VSS determines that a shadow copy LUN contains no interesting data. All shadow + /// copies have been deleted (which also causes deletion of the LUN.) The LUN resources may be reclaimed by the provider and reused + /// for another purpose. VSS will dismount any affected volumes. A provider should not issue a rescan during OnLunEmpty. VSS + /// will handle this cleanup. + /// + /// Note Hardware providers are only supported on Windows Server operating systems. + /// + /// Device corresponding to the LUN that contains the shadow copy to be deleted. + /// + /// Pointer to a VDS_LUN_INFORMATION structure containing information about the LUN containing the shadow copy to be deleted. + /// + /// + /// This method can return one of these values. + /// + /// + /// Return code/value + /// Description + /// + /// + /// S_OK 0x00000000L + /// The operation was successfully completed. + /// + /// + /// E_OUTOFMEMORY 0x8007000EL + /// Out of memory or other system resources. + /// + /// + /// E_INVALIDARG 0x80070057L + /// One of the parameter values is not valid. + /// + /// + /// VSS_E_PROVIDER_VETO 0x80042306L + /// + /// An unexpected provider error occurred. The provider must report an event in the application event log providing the user with + /// information on how to resolve the problem. + /// + /// + /// + /// + /// + /// + /// Hardware providers should delete a shadow copy and reclaim the LUN if and only if OnLunEmpty is being called. A hardware + /// shadow copy may be used as the backup media itself, therefore the LUNs should be treated with the same care the storage array + /// treats LUNs used for regular disks. Reclaiming LUNs outside of processing for OnLunEmpty should be limited to emergency + /// or an administrator performing explicit action manually. + /// + /// + /// In the case of persistent shadow copies, the requester deletes the shadow copy when it is no longer needed. In the case of + /// nonpersistent auto-release shadow copies, the VSS service deletes the shadow copy when the requester calls IUnknown::Release on + /// the IVssBackupComponents object. In the case of nonpersistent non-auto-release shadow copies, the VSS service deletes the shadow + /// copy when the computer is restarted. In all cases, the VSS service calls the provider's OnLunEmpty method as needed for + /// each shadow copy LUN. + /// + /// + /// Note that OnLunEmpty is called on a best effort basis. VSS invokes the method only when the LUN is guaranteed to be + /// empty. There may be many cases where the LUN is empty but VSS is unable to detect this due to errors or external circumstances. + /// In this case, the user should use storage management software to clear this state. + /// + /// Some examples: + /// + /// + /// + /// When a shadow copy LUN is moved to a different host but not actually transported or imported through VSS, then that LUN appears + /// as any other LUN, and volumes can be simply deleted without any notification of VSS. + /// + /// + /// + /// A crash or unexpected reboot in the middle of a shadow copy creation. + /// + /// + /// A canceled import. + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivsshardwaresnapshotprovider-onlunempty HRESULT OnLunEmpty( + // [in] VSS_PWSZ wszDeviceName, [in] VDS_LUN_INFORMATION *pInformation ); + [PreserveSig] + HRESULT OnLunEmpty([MarshalAs(UnmanagedType.LPWStr)] string wszDeviceName, in VDS_LUN_INFORMATION pInformation); + } + + /// + /// + /// Provides an additional method used by VSS to notify hardware providers of LUN state changes. All hardware providers must support + /// this interface. + /// + /// Note Hardware providers are only supported on Windows Server operating systems. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nn-vsprov-ivsshardwaresnapshotproviderex + [PInvokeData("vsprov.h", MSDNShortId = "NN:vsprov.IVssHardwareSnapshotProviderEx")] + [ComImport, Guid("7F5BA925-CDB1-4d11-A71F-339EB7E709FD"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IVssHardwareSnapshotProviderEx : IVssHardwareSnapshotProvider + { + /// + /// Not supported. + /// This method is reserved for future use. + /// + /// This parameter is reserved for future use. + /// None + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivsshardwaresnapshotproviderex-getprovidercapabilities + // HRESULT GetProviderCapabilities( ULONGLONG *pllOriginalCapabilityMask ); + [PreserveSig] + HRESULT GetProviderCapabilities(out ulong pllOriginalCapabilityMask); + + /// + /// The VSS service calls this method to notify hardware providers of a LUN state change. + /// Note Hardware providers are only supported on Windows Server operating systems. + /// + /// + /// A pointer to an array of dwCount VDS_LUN_INFORMATION structures, one for each LUN that contributes to the shadow copy volume. + /// + /// + /// A pointer to an array of dwCount VDS_LUN_INFORMATION structures, one for each LUN that contributes to the original volume. + /// + /// + /// Number of elements in the pSnapshotLuns array. This is also the number of elements in the pOriginalLuns array. + /// + /// + /// + /// A bitmask of _VSS_HARDWARE_OPTIONS flags that provide information about the state change that the shadow copy LUNs have + /// undergone. The following table describes how each flag is used in this parameter. + /// + /// + /// + /// Value + /// Meaning + /// + /// + /// VSS_ONLUNSTATECHANGE_NOTIFY_READ_WRITE 0x00000100 + /// The shadow copy LUN will be converted permanently to read-write. + /// + /// + /// VSS_ONLUNSTATECHANGE_NOTIFY_LUN_PRE_RECOVERY 0x00000200 + /// The shadow copy LUNs will be converted temporarily to read-write and are about to undergo TxF recovery or VSS auto-recovery. + /// + /// + /// VSS_ONLUNSTATECHANGE_NOTIFY_LUN_POST_RECOVERY 0x00000400 + /// The shadow copy LUNs have just undergone TxF recovery or VSS auto-recovery and have been converted back to read-only. + /// + /// + /// VSS_ONLUNSTATECHANGE_DO_MASK_LUNS 0x00000800 + /// The shadow copy LUNs must be masked from the current machine but not deleted. + /// + /// + /// + /// + /// This method can return one of these values. + /// + /// + /// Return code/value + /// Description + /// + /// + /// S_OK 0x00000000L + /// The operation was successfully completed. + /// + /// + /// E_OUTOFMEMORY 0x8007000EL + /// Out of memory or other system resources. + /// + /// + /// E_INVALIDARG 0x80070057L + /// One of the parameter values is not valid. + /// + /// + /// VSS_E_PROVIDER_VETO 0x80042306L + /// + /// An unexpected provider error occurred. If this is returned, the error must be described in an entry in the application event + /// log, giving the user information on how to resolve the problem. + /// + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivsshardwaresnapshotproviderex-onlunstatechange HRESULT + // OnLunStateChange( [in] VDS_LUN_INFORMATION *pSnapshotLuns, [in] VDS_LUN_INFORMATION *pOriginalLuns, [in] DWORD dwCount, [in] + // DWORD dwFlags ); + [PreserveSig] + HRESULT OnLunStateChange([In, Optional, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 2)] VDS_LUN_INFORMATION[] pSnapshotLuns, + [In, Optional, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 2)] VDS_LUN_INFORMATION[] pOriginalLuns, + uint dwCount, VSS_HARDWARE_OPTIONS dwFlags); + + /// The VSS service calls this method to notify hardware providers that a LUN resynchronization is needed. + /// + /// A pointer to an array of dwCount VDS_LUN_INFORMATION structures, one for each LUN that contributes to the shadow copy volume. + /// + /// + /// A pointer to an array of dwCount VDS_LUN_INFORMATION structures, one for each LUN that contributes to the destination + /// volume where the contents of the shadow copy volume are to be copied. + /// + /// + /// The number of elements in the pSourceLuns array. This is also the number of elements in the pTargetLuns array. + /// + /// + /// A pointer to a location that will receive an IVssAsync interface pointer that can be used to retrieve the status of the + /// resynchronization operation. When the operation is complete, the caller must release the interface pointer by calling the + /// IUnknown::Release method. + /// + /// + /// This method can return one of these values. + /// + /// + /// Return code/value + /// Description + /// + /// + /// S_OK 0x00000000L + /// The operation was successfully completed. + /// + /// + /// E_OUTOFMEMORY 0x8007000EL + /// Out of memory or other system resources. + /// + /// + /// VSS_E_PROVIDER_VETO 0x80042306L + /// + /// An unexpected provider error occurred. If this error code is returned, the error must be described in an entry in the + /// application event log, giving the user information on how to resolve the problem. + /// + /// + /// + /// VSS_E_INSUFFICIENT_STORAGE 0x8004231FL + /// The provider cannot perform the operation because there is not enough disk space. + /// + /// + /// + /// + /// + /// The destination LUNs can be the LUNs that contribute to the original production volume from which the shadow copy was created, + /// or they can be new or existing LUNs that are used to replace an original volume that is removed from production. + /// + /// + /// The provider must perform the resynchronization by copying data at the LUN array level, not at the host level. This means that + /// the provider cannot implement LUN resynchronization by simply copying the contents of the source LUN to the destination LUN. The + /// I/O that is required to perform the LUN resynchronization must be performed in the hardware, through the disk devices of the + /// resynchronized LUNs, and not through the host computer. This I/O should be completely transparent to the host computer. + /// + /// When the resynchronization is complete, the LUNs are fully functional and are available for I/O operations. + /// The underlying disk hardware must support unique page 83 device identifiers. + /// + /// If the destination LUN is larger than the source LUN, the provider must resize the destination LUN if necessary to ensure that + /// it matches the source LUN after resynchronization. + /// + /// + /// This method cannot be called in WinPE, and it cannot be called in Safe mode. Before calling this method, the caller must use the + /// IVssBackupComponents::InitializeForRestore method to prepare for the resynchronization. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivsshardwaresnapshotproviderex-resyncluns HRESULT ResyncLuns( + // [in] VDS_LUN_INFORMATION *pSourceLuns, [in] VDS_LUN_INFORMATION *pTargetLuns, [in] DWORD dwCount, [out] IVssAsync **ppAsync ); + [PreserveSig] + HRESULT ResyncLuns([In, Optional, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 2)] VDS_LUN_INFORMATION[] pSourceLuns, + [In, Optional, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 2)] VDS_LUN_INFORMATION[] pTargetLuns, uint dwCount, + out IVssAsync ppAsync); + + /// + /// Not supported. + /// This method is reserved for future use. + /// + /// This parameter is reserved for future use. + /// This parameter is reserved for future use. + /// This parameter is reserved for future use. + /// If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivsshardwaresnapshotproviderex-onreuseluns HRESULT + // OnReuseLuns( VDS_LUN_INFORMATION *pSnapshotLuns, VDS_LUN_INFORMATION *pOriginalLuns, DWORD dwCount ); + [PreserveSig] + HRESULT OnReuseLuns([In, Optional, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 2)] VDS_LUN_INFORMATION[] pSnapshotLuns, + [In, Optional, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 2)] VDS_LUN_INFORMATION[] pOriginalLuns, + uint dwCount); + } + + /// The IVssProviderCreateSnapshotSet interface contains the methods used during shadow copy creation. + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nn-vsprov-ivssprovidercreatesnapshotset + [PInvokeData("vsprov.h", MSDNShortId = "NN:vsprov.IVssProviderCreateSnapshotSet")] + [ComImport, Guid("5F894E5B-1E39-4778-8E23-9ABAD9F0E08C"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IVssProviderCreateSnapshotSet + { + /// + /// The EndPrepareSnapshots method is called once for the complete shadow copy set, after the last + /// IVssHardwareSnapshotProvider::BeginPrepareSnapshot call. This method is intended as a point where the provider can wait for any + /// shadow copy preparation work to complete. Because EndPrepareSnapshots may take a long time to complete, a provider should + /// be prepared to accept an AbortSnapshots method call at any time and immediately end the preparation work. + /// + /// The VSS_ID of the shadow copy set. + /// + /// + /// + /// Return code/value + /// Description + /// + /// + /// S_OK 0x00000000L + /// The operation was successfully completed. + /// + /// + /// E_OUTOFMEMORY 0x8007000EL + /// Out of memory or other system resources. + /// + /// + /// E_INVALIDARG 0x80070057L + /// One of the parameter values is not valid. + /// + /// + /// VSS_E_INSUFFICIENT_STORAGE 0x8004231FL + /// + /// There is not enough disk storage to create a shadow copy. Insufficient disk space can also generate VSS_E_PROVIDER_VETO + /// or VSS_E_OBJECT_NOT_FOUND error return values. + /// + /// + /// + /// VSS_E_OBJECT_NOT_FOUND 0x80042308L + /// The SnapshotSetId parameter refers to an object that was not found. + /// + /// + /// VSS_E_PROVIDER_VETO 0x80042306L + /// + /// An unexpected provider error occurred. If this is returned, the error must be described in an entry in the application event + /// log, giving the user information on how to resolve the problem. + /// + /// + /// + /// If any other value is returned, VSS will write an event to the event log and convert the error to VSS_E_UNEXPECTED_PROVIDER_ERROR. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivssprovidercreatesnapshotset-endpreparesnapshots HRESULT + // EndPrepareSnapshots( [in] VSS_ID SnapshotSetId ); + [PreserveSig] + HRESULT EndPrepareSnapshots(Guid SnapshotSetId); + + /// + /// The PreCommitSnapshots method ensures the provider is ready to quickly commit the prepared LUNs. This happens immediately + /// before the flush-and-hold writes, but while applications are in a frozen state. During this call the provider should prepare all + /// shadow copies in the shadow copy set indicated by SnapshotSetId for committing by the CommitSnapshots method call that + /// will follow. While the provider is processing this method, the applications have been frozen, so the time spent in this method + /// should be minimized. + /// + /// The VSS_ID that identifies the shadow copy set. + /// + /// + /// + /// Return code/value + /// Description + /// + /// + /// S_OK 0x00000000L + /// The operation was successfully completed. + /// + /// + /// E_OUTOFMEMORY 0x8007000EL + /// Out of memory or other system resources. + /// + /// + /// E_INVALIDARG 0x80070057L + /// One of the parameter values is not valid. + /// + /// + /// VSS_E_OBJECT_NOT_FOUND 0x80042308L + /// The SnapshotSetId parameter refers to an object that was not found. + /// + /// + /// VSS_E_PROVIDER_VETO 0x80042306L + /// + /// An unexpected provider error occurred. If this is returned, the error must be described in an entry in the application event + /// log, giving the user information on how to resolve the problem. + /// + /// + /// + /// If any other value is returned, VSS will write an event to the event log and convert the error to VSS_E_UNEXPECTED_PROVIDER_ERROR. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivssprovidercreatesnapshotset-precommitsnapshots HRESULT + // PreCommitSnapshots( [in] VSS_ID SnapshotSetId ); + [PreserveSig] + HRESULT PreCommitSnapshots(Guid SnapshotSetId); + + /// The CommitSnapshots method quickly commits all LUNs in this provider. + /// The VSS_ID that identifies the shadow copy set. + /// + /// + /// + /// Return code/value + /// Description + /// + /// + /// S_OK 0x00000000L + /// The operation was successfully completed. + /// + /// + /// E_OUTOFMEMORY 0x8007000EL + /// Out of memory or other system resources. + /// + /// + /// E_INVALIDARG 0x80070057L + /// One of the parameter values is not valid. + /// + /// + /// VSS_E_OBJECT_NOT_FOUND 0x80042308L + /// The SnapshotSetId parameter refers to an object that was not found. + /// + /// + /// VSS_E_PROVIDER_VETO 0x80042306L + /// An unexpected provider error occurred. The provider must log the details of this error in the application event log. + /// + /// + /// If any other value is returned, VSS will write an event to the event log and convert the error to VSS_E_UNEXPECTED_PROVIDER_ERROR. + /// + /// + /// + /// This method is called at the defined time at which the shadow copies should be taken. For each prepared LUN in this shadow copy + /// set, the provider will perform the work required to persist the point-in-time LUN contents. While this method is executing, both + /// applications and the I/O subsystem are largely quiescent. The provider must minimize the amount of time spent in this method. As + /// a general rule, this method should take less than one second to complete. This method is called during the Flush and Hold + /// window, and VSS Kernel Support will cancel the Flush and Hold if the release is not received within 10 seconds, which would + /// cause VSS to fail the shadow copy creation process. If each provider takes more than a second or two to complete this call, + /// there is a high probability that the entire shadow copy creation will fail. + /// + /// + /// Because the I/O system is quiescent, the provider must take care to not initiate any I/O as it could deadlock the system - for + /// example debug or tracing I/O by this method or any calls made from this method. Memory mapped files and paging I/O will not be + /// frozen at this time. + /// + /// + /// Note that the I/O system is quiescent only while this method is executing. Immediately after the last provider's + /// CommitSnapshots method returns, the VSS service releases all pending writes on the source LUNs. If the provider performs + /// any synchronization of the source and shadow copy LUNs, this synchronization must be completed before the provider's + /// CommitSnapshots method returns; it cannot be performed asynchronously. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivssprovidercreatesnapshotset-commitsnapshots HRESULT + // CommitSnapshots( [in] VSS_ID SnapshotSetId ); + [PreserveSig] + HRESULT CommitSnapshots(Guid SnapshotSetId); + + /// + /// The PostCommitSnapshots method is called after all providers involved in the shadow copy set have succeeded with + /// CommitSnapshots. The lock on the I/O system has been lifted, but the applications have not yet been unfrozen. This is an + /// opportunity for the provider to perform additional cleanup work after the shadow copy commit. + /// + /// The VSS_ID that identifies the shadow copy set. + /// Count of shadow copies in the shadow copy set. + /// + /// + /// + /// Return code/value + /// Description + /// + /// + /// S_OK 0x00000000L + /// The operation was successfully completed. + /// + /// + /// E_OUTOFMEMORY 0x8007000EL + /// Out of memory or other system resources. + /// + /// + /// E_INVALIDARG 0x80070057L + /// One of the parameter values is not valid. + /// + /// + /// VSS_E_OBJECT_NOT_FOUND 0x80042308L + /// The SnapshotSetId parameter refers to an object that was not found. + /// + /// + /// VSS_E_PROVIDER_VETO 0x80042306L + /// + /// An unexpected provider error occurred. If this is returned, the error must be described in an entry in the application event + /// log, giving the user information on how to resolve the problem. + /// + /// + /// + /// If any other value is returned, VSS will write an event to the event log and convert the error to VSS_E_UNEXPECTED_PROVIDER_ERROR. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivssprovidercreatesnapshotset-postcommitsnapshots HRESULT + // PostCommitSnapshots( [in] VSS_ID SnapshotSetId, [in] LONG lSnapshotsCount ); + [PreserveSig] + HRESULT PostCommitSnapshots(Guid SnapshotSetId, int lSnapshotsCount); + + /// + /// The PreFinalCommitSnapshots method enables providers to support auto-recover shadow copies. If the shadow copy has the + /// VSS_VOLSNAP_ATTR_AUTORECOVER flag set in the context, the volume can receive a large number of writes during the + /// auto-recovery operation. + /// + /// The VSS_ID that identifies the shadow copy set. + /// + /// + /// + /// Return code/value + /// Description + /// + /// + /// S_OK 0x00000000L + /// The operation was successfully completed. + /// + /// + /// E_OUTOFMEMORY 0x8007000EL + /// Out of memory or other system resources. + /// + /// + /// E_INVALIDARG 0x80070057L + /// One of the parameter values is not valid. + /// + /// + /// VSS_E_PROVIDER_VETO 0x80042306L + /// + /// An unexpected provider error occurred. If this is returned, the error must be described in an entry in the application event + /// log, giving the user information on how to resolve the problem. + /// + /// + /// + /// If any other value is returned, VSS will write an event to the event log and convert the error to VSS_E_UNEXPECTED_PROVIDER_ERROR. + /// + /// + /// + /// This method was added to enable binary compatibility when the auto-recover feature was introduced in Windows Server 2003 with + /// Service Pack 1 (SP1). + /// + /// + /// Note For Windows Server 2003, it is recommended that hardware providers implement this method using the following example: + /// + /// + /// HRESULT PreFinalCommitSnapshots( VSS_ID /* SnapshotSetId */ ) { return S_OK; } + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivssprovidercreatesnapshotset-prefinalcommitsnapshots HRESULT + // PreFinalCommitSnapshots( [in] VSS_ID SnapshotSetId ); + [PreserveSig] + HRESULT PreFinalCommitSnapshots(Guid SnapshotSetId); + + /// + /// The PostFinalCommitSnapshots method supports auto-recover shadow copies. VSS calls this method to notify the provider + /// that the volume will now be read-only until a requester calls IVssBackupComponents::BreakSnapshotSet. + /// + /// The VSS_ID that identifies the shadow copy set. + /// + /// + /// + /// Return code/value + /// Description + /// + /// + /// S_OK 0x00000000L + /// The operation was successfully completed. + /// + /// + /// E_OUTOFMEMORY 0x8007000EL + /// Out of memory or other system resources. + /// + /// + /// E_INVALIDARG 0x80070057L + /// One of the parameter values is not valid. + /// + /// + /// VSS_E_PROVIDER_VETO 0x80042306L + /// + /// An unexpected provider error occurred. If this is returned, the error must be described in an entry in the application event + /// log, giving the user information on how to resolve the problem. + /// + /// + /// + /// If any other value is returned, VSS will write an event to the event log and convert the error to VSS_E_UNEXPECTED_PROVIDER_ERROR. + /// + /// + /// + /// This method was added in Windows Server 2003 to enable binary compatibility when the auto-recover feature was introduced in + /// Windows Server 2003 with Service Pack 1 (SP1). + /// + /// + /// Note For Windows Server 2003, it is recommended that hardware providers implement this method using the following example: + /// + /// + /// HRESULT PostFinalCommitSnapshots( VSS_ID /* SnapshotSetId */ ) { return S_OK; } + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivssprovidercreatesnapshotset-postfinalcommitsnapshots + // HRESULT PostFinalCommitSnapshots( [in] VSS_ID SnapshotSetId ); + [PreserveSig] + HRESULT PostFinalCommitSnapshots(Guid SnapshotSetId); + + /// + /// The AbortSnapshots method aborts prepared shadow copies in this provider. This includes all non-committed shadow copies + /// and pre-committed ones. + /// + /// The VSS_ID that identifies the shadow copy set. + /// + /// This method can return one of these values. + /// + /// + /// Return code/value + /// Description + /// + /// + /// S_OK 0x00000000L + /// The operation was successfully completed. + /// + /// + /// E_OUTOFMEMORY 0x8007000EL + /// Out of memory or other system resources. + /// + /// + /// E_INVALIDARG 0x80070057L + /// One of the parameter values is not valid. + /// + /// + /// VSS_E_OBJECT_NOT_FOUND 0x80042308L + /// The SnapshotSetId parameter refers to an object that was not found. + /// + /// + /// VSS_E_PROVIDER_VETO 0x80042306L + /// + /// An unexpected provider error occurred. The provider must log a message in the application event log providing the user with + /// information on how to resolve the problem. + /// + /// + /// + /// + /// + /// VSS will only call AbortSnapshots after the requester has called IVssBackupComponents::DoSnapshotSet, even if the shadow + /// copy fails or is aborted before this point. This means that a provider will not receive an AbortSnapshots call until + /// after EndPrepareSnapshots has been called. If a shadow copy is aborted or fails before this point, the provider is not given any + /// indication until a new shadow copy is started. For this reason, the provider must be prepared to handle an out-of-sequence + /// IVssHardwareSnapshotProvider::BeginPrepareSnapshot call at any point. This out-of-sequence call represents the start of a new + /// shadow copy creation sequence and will have a new shadow copy set ID. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivssprovidercreatesnapshotset-abortsnapshots HRESULT + // AbortSnapshots( [in] VSS_ID SnapshotSetId ); + [PreserveSig] + HRESULT AbortSnapshots(Guid SnapshotSetId); + } + + /// The IVssProviderNotifications interface manages providers registered with VSS. + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nn-vsprov-ivssprovidernotifications + [PInvokeData("vsprov.h", MSDNShortId = "NN:vsprov.IVssProviderNotifications")] + [ComImport, Guid("E561901F-03A5-4afe-86D0-72BAEECE7004"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IVssProviderNotifications + { + /// The OnLoad method notifies a provider that it was loaded. + /// This parameter is reserved. + /// + /// This method can return one of these values. + /// + /// + /// Return code/value + /// Description + /// + /// + /// S_OK 0x00000000L + /// The operation was successfully completed. + /// + /// + /// E_OUTOFMEMORY 0x8007000EL + /// Out of memory or other system resources. + /// + /// + /// E_INVALIDARG 0x80070057L + /// One of the parameter values is not valid. + /// + /// + /// VSS_E_PROVIDER_VETO 0x80042306L + /// + /// An unexpected provider error occurred. If this is returned, the error must be described in an entry in the application event + /// log, giving the user information on how to resolve the problem. + /// + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivssprovidernotifications-onload HRESULT OnLoad( [in] + // IUnknown *pCallback ); + [PreserveSig] + HRESULT OnLoad([In, Optional, MarshalAs(UnmanagedType.IUnknown)] object pCallback); + + /// The OnUnload method notifies the provider to prepare to be unloaded. + /// If TRUE, the provider must prepare to be released. + /// + /// This method can return one of these values. + /// + /// + /// Return code/value + /// Description + /// + /// + /// S_OK 0x00000000L + /// There are no pending operations and the provider is ready to be released. + /// + /// + /// S_FALSE 0x00000001L + /// The provider should not be unloaded. This value can only be returned if bForceUnload is FALSE. + /// + /// + /// + /// If bForceUnload is TRUE, the return value must be S_OK. + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivssprovidernotifications-onunload HRESULT OnUnload( [in] + // BOOL bForceUnload ); + [PreserveSig] + HRESULT OnUnload([MarshalAs(UnmanagedType.Bool)] bool bForceUnload); + } + + /// Contains the methods used by VSS to manage shadow copy volumes. All software providers must support this interface. + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nn-vsprov-ivsssoftwaresnapshotprovider + [PInvokeData("vsprov.h", MSDNShortId = "NN:vsprov.IVssSoftwareSnapshotProvider")] + [ComImport, Guid("609e123e-2c5a-44d3-8f01-0b1d9a47d1ff"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IVssSoftwareSnapshotProvider + { + /// Sets the context for subsequent shadow copy-related operations. + /// + /// The context to be set. The context must be one of the supported values of _VSS_SNAPSHOT_CONTEXT or a supported combination of + /// _VSS_VOLUME_SNAPSHOT_ATTRIBUTES and _VSS_SNAPSHOT_CONTEXT values. + /// + /// + /// The following are the valid return codes for this method. + /// + /// + /// Value + /// Meaning + /// + /// + /// S_OK + /// The context was set successfully. + /// + /// + /// E_ACCESSDENIED + /// The caller does not have sufficient backup privileges or is not an administrator. + /// + /// + /// 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 context is frozen and cannot be changed. + /// + /// + /// + /// + /// The default context for VSS shadow copies is VSS_CTX_BACKUP. + /// + /// Windows XP: The only supported context is the default context, VSS_CTX_BACKUP. Therefore, calling SetContext under + /// Windows XP returns E_NOTIMPL. + /// + /// + /// For more information about how the context that is set by SetContext affects how a shadow copy is created and managed, + /// see Implementation Details for Creating Shadow Copies. + /// + /// For a complete discussion of the permitted shadow copy contexts, see _VSS_SNAPSHOT_CONTEXT and _VSS_VOLUME_SNAPSHOT_ATTRIBUTES. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivsssoftwaresnapshotprovider-setcontext HRESULT SetContext( + // [in] LONG lContext ); + [PreserveSig] + HRESULT SetContext(VSS_SNAPSHOT_CONTEXT lContext); + + /// Gets the properties of the specified shadow copy. + /// Shadow copy identifier. + /// + /// The address of a caller-allocated VSS_SNAPSHOT_PROP structure that receives the shadow copy properties. The provider is + /// responsible for setting the members of this structure. All members are required except m_pwszExposedName and + /// m_pwszExposedPath, which the provider can set to NULL. The provider allocates memory for all string members that + /// it sets in the structure. When the structure is no longer needed, the caller is responsible for freeing these strings by calling + /// the VssFreeSnapshotProperties function. + /// + /// + /// The following are the valid return codes for this method. + /// + /// + /// Value + /// Meaning + /// + /// + /// S_OK + /// The requested information was successfully returned. + /// + /// + /// E_ACCESSDENIED + /// The caller does not have sufficient backup privileges or is not an administrator. + /// + /// + /// E_INVALIDARG + /// One of the parameter values is not valid. + /// + /// + /// E_OUTOFMEMORY + /// The caller is out of memory or other system resources. + /// + /// + /// VSS_E_OBJECT_NOT_FOUND + /// The specified volume was not found. + /// + /// + /// VSS_E_PROVIDER_VETO + /// + /// Provider error. The provider logged the error in the event log. For more information, see Event and Error Handling Under VSS. + /// + /// + /// + /// 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. + /// + /// + /// + /// + /// + /// + /// The caller should set the contents of the VSS_SNAPSHOT_PROP structure to zero before calling the GetSnapshotProperties method. + /// + /// The provider is responsible for allocating and freeing the strings in the VSS_SNAPSHOT_PROP structure. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivsssoftwaresnapshotprovider-getsnapshotproperties HRESULT + // GetSnapshotProperties( [in] VSS_ID SnapshotId, [out] VSS_SNAPSHOT_PROP *pProp ); + [PreserveSig] + HRESULT GetSnapshotProperties(Guid SnapshotId, out VSS_SNAPSHOT_PROP pProp); + + /// Queries the provider for information about the shadow copies that the provider has completed. + /// Reserved for system use. The value of this parameter must be GUID_NULL. + /// Reserved for system use. The value of this parameter must be VSS_OBJECT_NONE. + /// Reserved for system use. The value of this parameter must be VSS_OBJECT_SNAPSHOT. + /// + /// The address of an IVssEnumObject interface pointer, which is initialized on return. Callers must release the interface. This + /// parameter is required and cannot be null. + /// + /// + /// The following are the valid return codes for this method. + /// + /// + /// Value + /// Meaning + /// + /// + /// S_OK + /// The query operation was successful. + /// + /// + /// E_ACCESSDENIED + /// The caller does not have sufficient backup privileges or is not an administrator. + /// + /// + /// E_INVALIDARG + /// One of the parameter values is not valid. + /// + /// + /// E_OUTOFMEMORY + /// The caller is out of memory or other system resources. + /// + /// + /// VSS_E_PROVIDER_VETO + /// + /// Provider error. The provider logged the error in the event log. For more information, see Event and Error Handling Under VSS. + /// + /// + /// + /// + /// + /// Calling the IVssEnumObject::Next method on the IVssEnumObject interface that is returned though the ppEnum parameter will + /// return VSS_OBJECT_PROP structures containing a VSS_SNAPSHOT_PROP structure for each shadow copy. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivsssoftwaresnapshotprovider-query HRESULT Query( [in] VSS_ID + // QueriedObjectId, [in] VSS_OBJECT_TYPE eQueriedObjectType, [in] VSS_OBJECT_TYPE eReturnedObjectsType, [out] IVssEnumObject + // **ppEnum ); + [PreserveSig] + HRESULT Query(Guid QueriedObjectId, VSS_OBJECT_TYPE eQueriedObjectType, VSS_OBJECT_TYPE eReturnedObjectsType, out IVssEnumObject ppEnum); + + /// Deletes one or more shadow copies or a shadow copy set. + /// Identifier of the shadow copy or shadow copy set to be deleted. + /// Type of the object to be deleted. The value of this parameter is VSS_OBJECT_SNAPSHOT or VSS_OBJECT_SNAPSHOT_SET. + /// + /// If the value of this parameter is TRUE, the provider will do everything possible to delete the shadow copy or shadow + /// copies in a shadow copy set. If it is FALSE, no additional effort will be made. + /// + /// Pointer to a variable that receives the number of shadow copies that were deleted. + /// + /// If an error occurs, this parameter receives a pointer to the identifier of the first shadow copy that could not be deleted. + /// Otherwise, it points to GUID_NULL. + /// + /// + /// The following are the valid return codes for this method. + /// + /// + /// Value + /// Meaning + /// + /// + /// S_OK + /// The shadow copies were successfully deleted. + /// + /// + /// E_ACCESSDENIED + /// The caller does not have sufficient backup privileges or is not an administrator. + /// + /// + /// E_INVALIDARG + /// One of the parameter values is not valid. + /// + /// + /// E_OUTOFMEMORY + /// The caller is out of memory or other system resources. + /// + /// + /// VSS_E_OBJECT_NOT_FOUND + /// The specified shadow copies were not found. + /// + /// + /// VSS_E_PROVIDER_VETO + /// + /// Provider error. The provider logged the error in the event log. For more information, see Event and Error Handling Under VSS. + /// + /// + /// + /// + /// + /// Multiple shadow copies in a shadow copy set are deleted sequentially. If an error occurs during one of these individual + /// deletions, DeleteSnapshots will return immediately; no attempt will be made to delete any remaining shadow copies. The + /// VSS_ID of the undeleted shadow copy is returned in pNondeletedSnapshotID. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivsssoftwaresnapshotprovider-deletesnapshots HRESULT + // DeleteSnapshots( [in] VSS_ID SourceObjectId, [in] VSS_OBJECT_TYPE eSourceObjectType, [in] BOOL bForceDelete, [out] LONG + // *plDeletedSnapshots, [out] VSS_ID *pNondeletedSnapshotID ); + [PreserveSig] + HRESULT DeleteSnapshots(Guid SourceObjectId, VSS_OBJECT_TYPE eSourceObjectType, [MarshalAs(UnmanagedType.Bool)] bool bForceDelete, + out int plDeletedSnapshots, out Guid pNondeletedSnapshotID); + + /// VSS calls this method for each shadow copy that is added to the shadow copy set. + /// Shadow copy set identifier. + /// Identifier of the shadow copy to be created. + /// + /// + /// Null-terminated wide character string containing the volume name. The name must be in one of the following formats and must + /// include a trailing backslash (\): + /// + /// + /// + /// The path of a mounted folder, for example, Y:\MountX\ + /// + /// + /// A drive letter, for example, D:\ + /// + /// + /// A volume GUID path of the form \\?\ Volume{ GUID}\ (where GUID identifies the volume) + /// + /// + /// + /// + /// The context for the shadow copy set. This context consists of a bitmask of _VSS_VOLUME_SNAPSHOT_ATTRIBUTES values. + /// + /// + /// The following are the valid return codes for this method. + /// + /// + /// Value + /// Meaning + /// + /// + /// S_OK + /// The shadow copy was successfully created. + /// + /// + /// E_ACCESSDENIED + /// The caller does not have sufficient backup privileges or is not an administrator. + /// + /// + /// E_INVALIDARG + /// One of the parameter values is not valid. + /// + /// + /// E_OUTOFMEMORY + /// The caller is out of memory or other system resources. + /// + /// + /// VSS_E_OBJECT_NOT_FOUND + /// The specified volume was not found. + /// + /// + /// VSS_E_PROVIDER_VETO + /// + /// Provider error. The provider logged the error in the event log. For more information, see Event and Error Handling Under VSS. + /// + /// + /// + /// VSS_E_UNSUPPORTED_CONTEXT + /// The specified context is not supported. + /// + /// + /// VSS_E_VOLUME_NOT_SUPPORTED_BY_PROVIDER + /// The provider does not support the specified volume. + /// + /// + /// 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. + /// + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivsssoftwaresnapshotprovider-beginpreparesnapshot HRESULT + // BeginPrepareSnapshot( [in] VSS_ID SnapshotSetId, [in] VSS_ID SnapshotId, [in] VSS_PWSZ pwszVolumeName, [in] LONG lNewContext ); + [PreserveSig] + HRESULT BeginPrepareSnapshot(Guid SnapshotSetId, Guid SnapshotId, [MarshalAs(UnmanagedType.LPWStr)] string pwszVolumeName, + VSS_VOLUME_SNAPSHOT_ATTRIBUTES lNewContext); + + /// Determines whether the provider supports shadow copies on the specified volume. + /// + /// + /// Null-terminated wide character string containing the volume name. The name must be in one of the following formats and must + /// include a trailing backslash (\): + /// + /// + /// + /// The path of a mounted folder, for example, Y:\MountX\ + /// + /// + /// A drive letter, for example, D:\ + /// + /// + /// A volume GUID path of the form \\?\ Volume{ GUID}\ (where GUID identifies the volume) + /// + /// + /// + /// + /// This parameter receives TRUE if shadow copies are supported on the specified volume, otherwise FALSE. + /// + /// + /// The following are the valid return codes for this method. + /// + /// + /// Value + /// Meaning + /// + /// + /// S_OK + /// The requested information was successfully returned. + /// + /// + /// E_ACCESSDENIED + /// The caller does not have sufficient backup privileges or is not an administrator. + /// + /// + /// E_INVALIDARG + /// One of the parameter values is not valid. + /// + /// + /// VSS_E_NESTED_VOLUME_LIMIT + /// + /// The specified volume is nested too deeply to participate in the VSS operation. Windows Server 2008, Windows Vista, Windows + /// Server 2003 and Windows XP: This return code is not supported. + /// + /// + /// + /// E_OUTOFMEMORY + /// The caller is out of memory or other system resources. + /// + /// + /// VSS_E_OBJECT_NOT_FOUND + /// The specified volume was not found. + /// + /// + /// VSS_E_PROVIDER_VETO + /// + /// Provider error. The provider logged the error in the event log. For more information, see Event and Error Handling Under VSS. + /// + /// + /// + /// 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. + /// + /// + /// + /// + /// + /// + /// The IsVolumeSupported method will return TRUE if it is possible to create shadow copies on the given volume, even + /// if the current configuration does not allow the creation of shadow copies on that volume at the present time. + /// + /// + /// For example, if the maximum number of shadow copies has been reached on a given volume (and therefore no more shadow copies can + /// be created on that volume), the method will still indicate that the volume can be shadow copied. + /// + /// This method cannot be called for a virtual hard disk (VHD) that is nested inside another VHD. + /// Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: VHDs are not supported. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivsssoftwaresnapshotprovider-isvolumesupported HRESULT + // IsVolumeSupported( [in] VSS_PWSZ pwszVolumeName, [out] BOOL *pbSupportedByThisProvider ); + [PreserveSig] + HRESULT IsVolumeSupported([MarshalAs(UnmanagedType.LPWStr)] string pwszVolumeName, [MarshalAs(UnmanagedType.Bool)] out bool pbSupportedByThisProvider); + + /// Determines whether any shadow copies exist for the specified volume. + /// + /// + /// Null-terminated wide character string containing the volume name. The name must be in one of the following formats and must + /// include a trailing backslash (\): + /// + /// + /// + /// The path of a mounted folder, for example, Y:\MountX\ + /// + /// + /// A drive letter, for example, D:\ + /// + /// + /// A volume GUID path of the form \\?\ Volume{ GUID}\ (where GUID identifies the volume) + /// + /// + /// + /// + /// This parameter receives TRUE if the volume has a shadow copy, or FALSE if the volume does not have a shadow copy. + /// + /// + /// A bitmask of VSS_SNAPSHOT_COMPATIBILITY values that indicate whether certain volume control or file I/O operations are disabled + /// for the given volume, if the volume has a shadow copy. + /// + /// + /// The following are the valid return codes for this method. + /// + /// + /// Value + /// Meaning + /// + /// + /// S_OK + /// The requested information was successfully returned. + /// + /// + /// E_ACCESSDENIED + /// The caller does not have sufficient backup privileges or is not an administrator. + /// + /// + /// E_INVALIDARG + /// One of the parameter values is not valid. + /// + /// + /// E_OUTOFMEMORY + /// The caller is out of memory or other system resources. + /// + /// + /// VSS_E_OBJECT_NOT_FOUND + /// The specified volume was not found. + /// + /// + /// VSS_E_PROVIDER_VETO + /// + /// Provider error. The provider logged the error in the event log. For more information, see Event and Error Handling Under VSS. + /// + /// + /// + /// 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. + /// + /// + /// + /// + /// + /// If no volume control or file I/O operations are disabled for the selected volume, then the shadow copy capability of the + /// selected volume returned by plSnapshotCapability will be zero. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivsssoftwaresnapshotprovider-isvolumesnapshotted HRESULT + // IsVolumeSnapshotted( [in] VSS_PWSZ pwszVolumeName, [out] BOOL *pbSnapshotsPresent, [out] LONG *plSnapshotCompatibility ); + [PreserveSig] + HRESULT IsVolumeSnapshotted([MarshalAs(UnmanagedType.LPWStr)] string pwszVolumeName, [MarshalAs(UnmanagedType.Bool)] out bool pbSnapshotsPresent, + out VSS_SNAPSHOT_COMPATIBILITY plSnapshotCompatibility); + + /// Sets a property for a shadow copy. + /// Shadow copy identifier. This parameter is required and cannot be GUID_NULL. + /// A VSS_SNAPSHOT_PROPERTY_ID value that specifies the property to be set for the shadow copy. + /// + /// The value to be set for the property. See the VSS_SNAPSHOT_PROP structure for valid data types and descriptions of the + /// properties that can be set for a shadow copy. + /// + /// + /// The following are the valid return codes for this method. + /// + /// + /// Value + /// Meaning + /// + /// + /// S_OK + /// The property was set successfully. + /// + /// + /// E_ACCESSDENIED + /// The caller does not have sufficient backup privileges or is not an administrator. + /// + /// + /// E_INVALIDARG + /// One of the parameter values is not valid. + /// + /// + /// E_OUTOFMEMORY + /// The caller is out of memory or other system resources. + /// + /// + /// VSS_E_OBJECT_NOT_FOUND + /// The specified shadow copy was not found. + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivsssoftwaresnapshotprovider-setsnapshotproperty HRESULT + // SetSnapshotProperty( [in] VSS_ID SnapshotId, [in] VSS_SNAPSHOT_PROPERTY_ID eSnapshotPropertyId, [in] VARIANT vProperty ); + [PreserveSig] + HRESULT SetSnapshotProperty(Guid SnapshotId, VSS_SNAPSHOT_PROPERTY_ID eSnapshotPropertyId, object vProperty); + + /// + /// Reverts a volume to a previous shadow copy. Only shadow copies created with persistent contexts (VSS_CTX_APP_ROLLBACK, + /// VSS_CTX_CLIENT_ACCESSIBLE, VSS_CTX_CLIENT_ACCESSIBLE_WRITERS, or VSS_CTX_NAS_ROLLBACK) are supported. + /// + /// Shadow copy identifier of the shadow copy to revert. + /// + /// The following are the valid return codes for this method. + /// + /// + /// Value + /// Meaning + /// + /// + /// S_OK + /// The revert operation was successful. + /// + /// + /// E_ACCESSDENIED + /// The caller does not have sufficient backup privileges or is not an administrator. + /// + /// + /// E_INVALIDARG + /// One of the parameter values is not valid. + /// + /// + /// E_OUTOFMEMORY + /// The caller is out of memory or other system resources. + /// + /// + /// VSS_E_REVERT_IN_PROGRESS + /// The volume already has a revert operation in process. + /// + /// + /// + /// + /// This operation cannot be canceled, or undone once completed. If the computer is rebooted during the revert operation, the revert + /// process will continue when the system is restarted. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivsssoftwaresnapshotprovider-reverttosnapshot HRESULT + // RevertToSnapshot( [in] VSS_ID SnapshotId ); + [PreserveSig] + HRESULT RevertToSnapshot(Guid SnapshotId); + + /// Returns an IVssAsync interface pointer that can be used to determine the status of the revert operation. + /// + /// + /// Null-terminated wide character string containing the volume name. The name must be in one of the following formats and must + /// include a trailing backslash (\): + /// + /// + /// + /// The path of a mounted folder, for example, Y:\MountX\ + /// + /// + /// A drive letter, for example, D:\ + /// + /// + /// A volume GUID path of the form \\?\ Volume{ GUID}\ (where GUID identifies the volume) + /// + /// + /// + /// + /// Pointer to a location that will receive an IVssAsync interface pointer that can be used to retrieve the status of the revert + /// operation. When the operation is complete, the caller must release the interface pointer by calling the IUnknown::Release method. + /// + /// + /// The following are the valid return codes for this method. + /// + /// + /// Value + /// Meaning + /// + /// + /// S_OK + /// The status of the revert operation was successfully queried. + /// + /// + /// E_ACCESSDENIED + /// The caller does not have sufficient backup privileges or is not an administrator. + /// + /// + /// E_INVALIDARG + /// One of the parameter values is not valid. + /// + /// + /// E_OUTOFMEMORY + /// The caller is out of memory or other system resources. + /// + /// + /// VSS_E_OBJECT_NOT_FOUND + /// The pwszVolume parameter does not specify a valid volume. + /// + /// + /// VSS_E_VOLUME_NOT_SUPPORTED + /// The revert operation is not supported on this volume. + /// + /// + /// + /// + /// The revert operation will continue even if the computer is rebooted, and cannot be canceled or undone, except by restoring a + /// backup that was created using another method. The IVssAsync::QueryStatus method cannot return VSS_S_ASYNC_CANCELLED, because the + /// revert operation cannot be canceled after it has started. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vsprov/nf-vsprov-ivsssoftwaresnapshotprovider-queryrevertstatus HRESULT + // QueryRevertStatus( [in] VSS_PWSZ pwszVolume, [out] IVssAsync **ppAsync ); + [PreserveSig] + HRESULT QueryRevertStatus([MarshalAs(UnmanagedType.LPWStr)] string pwszVolume, out IVssAsync ppAsync); + } +} \ No newline at end of file diff --git a/PInvoke/VssApi/vss.cs b/PInvoke/VssApi/vss.cs index c03bd6ba..a7247d75 100644 --- a/PInvoke/VssApi/vss.cs +++ b/PInvoke/VssApi/vss.cs @@ -1,1986 +1,2083 @@ using System; using System.Runtime.InteropServices; using Vanara.Collections; +using Vanara.InteropServices; using FILETIME = System.Runtime.InteropServices.ComTypes.FILETIME; -namespace Vanara.PInvoke +namespace Vanara.PInvoke.VssApi { - /// Functions, structures and constants from vssapi.dll. - public static partial class VssApi + /// + /// + /// The VSS_APPLICATION_LEVEL enumeration indicates the application level, the point in the course of the creation of a shadow + /// copy that a writer is notified of a freeze. + /// + /// + /// VSS first sends a Freeze event to writers initialized with VSS_APP_FRONT_END (called front-end level applications), then to + /// writers initialized with VSS_APP_BACK_END (called back-end level applications), and finally to writers initialized with + /// VSS_APP_SYSTEM (called system-level applications). + /// + /// + /// + /// + /// VSS_APPLICATION_LEVEL is provided to allow application developers to control at what point a writer will receive a Freeze + /// event. This may be important if one writer uses or depends on another writer. + /// + /// + /// For instance, if an application X is storing data using application Y as an intermediate layer (for example, if Y implements a + /// database used by X), we would describe X as a front-end application, and Y as a back-end application. + /// + /// + /// In this example, when freezing applications that participate in a shadow copy, you would want X (the front-end application) to + /// suspend its writes to the database prior to freezing Y (the back-end application), the database service itself. + /// + /// The application level of a writer is set by CVssWriter::Initialize and retrieved by CVssWriter::GetCurrentLevel. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vss/ne-vss-vss_application_level typedef enum _VSS_APPLICATION_LEVEL { + // VSS_APP_UNKNOWN, VSS_APP_SYSTEM, VSS_APP_BACK_END, VSS_APP_FRONT_END, VSS_APP_SYSTEM_RM, VSS_APP_AUTO } VSS_APPLICATION_LEVEL, *PVSS_APPLICATION_LEVEL; + [PInvokeData("vss.h", MSDNShortId = "NE:vss._VSS_APPLICATION_LEVEL")] + public enum VSS_APPLICATION_LEVEL { - private const string Lib_VssApi = "vssapi.dll"; + /// + /// The level at which this writer's freeze state will occur is not known. This indicates an application + /// error. + /// + VSS_APP_UNKNOWN, + + /// This writer freeze state will occur at the system application level. + VSS_APP_SYSTEM, + + /// This writer freeze state will occur at the back-end application level. + VSS_APP_BACK_END, + + /// This writer freeze state will occur at the front-end application level. + VSS_APP_FRONT_END, + + /// + VSS_APP_SYSTEM_RM, + + /// + /// This writer freeze state will be determined automatically. This enumeration value is reserved for future + /// use. + /// + VSS_APP_AUTO = -1, + } + + /// + /// The VSS_BACKUP_SCHEMA enumeration is used by a writer to indicate the types of backup operations it can participate in. The + /// supported kinds of backup are expressed as a bit mask (or bitwise OR) of VSS_BACKUP_SCHEMA values. + /// + /// + /// Writer set their backup schemas with calls to IVssCreateWriterMetadata::SetBackupSchema. + /// Requesters use IVssExamineWriterMetadata::GetBackupSchema to determine the backup schema that a writer supports. + /// + /// For a specific kind of backup operation to be supported, the writer must support the corresponding schema, and the requester must + /// set the corresponding backup type. + /// + /// + /// For example, to involve a writer in an incremental backup operation, the requester must set the backup type to + /// VSS_BT_INCREMENTAL, and the writer should have a backup schema that includes VSS_BS_INCREMENTAL. + /// + /// + /// A writer that does not support the backup schema corresponding to a requester's backup type should treat the backup operation that + /// is being performed as if it were a default (full) backup. If the desired backup type is not supported by the writer's backup schema, + /// the requester can either perform a full backup for this writer or exclude the writer from the backup operation. A requester can + /// exclude a writer by selecting none of the writer's components (see Working with Selectability and Logical Paths), or by disabling + /// the writer (see IVssBackupComponents::DisableWriterClasses or IVssBackupComponents::DisableWriterInstances). + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vss/ne-vss-vss_backup_schema typedef enum _VSS_BACKUP_SCHEMA { VSS_BS_UNDEFINED, + // VSS_BS_DIFFERENTIAL, VSS_BS_INCREMENTAL, VSS_BS_EXCLUSIVE_INCREMENTAL_DIFFERENTIAL, VSS_BS_LOG, VSS_BS_COPY, VSS_BS_TIMESTAMPED, + // VSS_BS_LAST_MODIFY, VSS_BS_LSN, VSS_BS_WRITER_SUPPORTS_NEW_TARGET, VSS_BS_WRITER_SUPPORTS_RESTORE_WITH_MOVE, + // VSS_BS_INDEPENDENT_SYSTEM_STATE, VSS_BS_ROLLFORWARD_RESTORE, VSS_BS_RESTORE_RENAME, VSS_BS_AUTHORITATIVE_RESTORE, + // VSS_BS_WRITER_SUPPORTS_PARALLEL_RESTORES } VSS_BACKUP_SCHEMA, *PVSS_BACKUP_SCHEMA; + [PInvokeData("vss.h", MSDNShortId = "NE:vss._VSS_BACKUP_SCHEMA")] + [Flags] + public enum VSS_BACKUP_SCHEMA + { + /// + /// The writer supports a simple full backup and restoration of entire files (as defined by a + /// VSS_BACKUP_TYPE + /// value of + /// VSS_BT_FULL + /// ). This backup scheme can be used as the basis of an incremental or + /// differential backup. This is the default value. + /// + VSS_BS_UNDEFINED = 0, + + /// + /// The writer supports differential backups (corresponding to the + /// VSS_BACKUP_TYPE + /// value + /// VSS_BT_DIFFERENTIAL + /// ). Files created or changed since the last full backup are saved. + /// Files are not marked as having been backed up. + /// This setting does not preclude mixing of incremental and differential backups. + /// This value is not supported for express writers. + /// + VSS_BS_DIFFERENTIAL = 0x0001, + + /// + /// The writer supports incremental backups (corresponding to the + /// VSS_BACKUP_TYPE + /// value + /// VSS_BT_INCREMENTAL + /// ). Files created or changed since the last full or incremental + /// backup are saved. Files are marked as having been backed up. + /// This setting does not preclude mixing of incremental and differential backups. + /// This value is not supported for express writers. + /// + VSS_BS_INCREMENTAL = 0x0002, + + /// + /// The writer supports both differential and incremental backup schemas, but only exclusively: for example, + /// you cannot follow a differential backup with an incremental one. A writer cannot support this schema if it does + /// not support both incremental and differential schemas ( + /// VSS_BS_DIFFERENTIAL + /// + VSS_BS_EXCLUSIVE_INCREMENTAL_DIFFERENTIAL = 0x0004, + + /// + /// The writer supports backups that involve only the log files it manages (corresponding to a + /// VSS_BACKUP_TYPE + /// value of + /// VSS_BT_LOG + /// ). This schema requires a writer to have added at least one file to at + /// least one component using the + /// IVssCreateWriterMetadata::AddDataBaseLogFiles + /// method. Requesters retrieve log file information using the + /// IVssWMComponent::GetDatabaseLogFile + /// method. + /// + VSS_BS_LOG = 0x0008, + + /// + /// Similar to the default backup schema ( + /// VSS_BT_UNDEFINED + /// ), the writer supports + /// copy backup operations (corresponding to + /// VSS_BT_COPY + /// ) where file access information + /// (such as information as to when a file was last backed up) will not be updated either in the writer's own state + /// information or in the file system information. This type of backup cannot be used as the basis of an incremental + /// or differential backup. + /// + VSS_BS_COPY = 0x0010, + + /// + /// A writer supports using the VSS time-stamp mechanism when evaluating if a file should be included in + /// differential or incremental operations (corresponding to + /// VSS_BT_DIFFERENTIAL + /// and + /// VSS_BT_INCREMENTAL + /// , respectively) using the + /// IVssComponent::GetBackupStamp + /// , + /// IVssComponent::GetPreviousBackupStamp + /// , + /// IVssComponent::SetBackupStamp + /// , and + /// IVssBackupComponents::SetPreviousBackupStamp + /// methods. + /// A writer cannot support this schema if it does not support either differential or incremental backup schemas + /// ( + /// VSS_BS_DIFFERENTIAL + /// or + /// VSS_BS_INCREMENTAL + /// ). + /// This value is not supported for express writers. + /// + VSS_BS_TIMESTAMPED = 0x0020, + + /// + /// When implementing incremental or differential backups with differenced files, a writer can provide last + /// modification time information for files (using + /// IVssComponent::AddDifferencedFilesByLastModifyTime + /// ). + /// A requester then can use + /// IVssComponent::GetDifferencedFile + /// to + /// obtain candidate files and information about their last modification data. The requester can use this + /// information (along with any records about previous backup operations it maintains) to decide if a file should be + /// included in incremental and differential backups. + /// This scheme does not apply to partial file implementations of incremental and differential backup + /// operations. + /// A writer cannot support this schema if it does not support either incremental or differential backup schemas + /// ( + /// VSS_BS_DIFFERENTIAL + /// or + /// VSS_BS_INCREMENTAL + /// ). + /// This value is not supported for express writers. + /// + VSS_BS_LAST_MODIFY = 0x0040, + + /// Reserved for system use. + VSS_BS_LSN = 0x0080, + + /// + /// The writer supports a requester changing the target for file restoration using + /// IVssBackupComponents::AddNewTarget + /// . + /// (See + /// Non-Default Backup And Restore Locations + /// for more information.) + /// This value is not supported for express writers. + /// + VSS_BS_WRITER_SUPPORTS_NEW_TARGET = 0x0100, /// /// - /// The VSS_APPLICATION_LEVEL enumeration indicates the application level, the point in the course of the creation of a - /// shadow copy that a writer is notified of a freeze. + /// The writer supports running multiple writer instances with the same class ID, and it supports a requester moving a component to + /// a different writer instance at restore time using + /// + /// IVssBackupComponentsEx::SetSelectedForRestoreEx + /// . + /// This value is not supported for express writers. + /// Windows Server 2003: + /// This value is not supported until Windows Server 2003 with SP1. + /// + VSS_BS_WRITER_SUPPORTS_RESTORE_WITH_MOVE = 0x0200, + + /// + /// + /// The writer supports backing up data that is part of the system state, but that can also be backed up independently of the system state. + /// + /// Windows Server 2003: + /// This value is not supported until Windows Vista. + /// + VSS_BS_INDEPENDENT_SYSTEM_STATE = 0x0400, + + /// + /// The writer supports a requester setting a roll-forward restore point using + /// IVssBackupComponentsEx2::SetRollForward + /// . + /// This value is not supported for express writers. + /// Windows Server 2003: + /// This value is not supported until Windows Vista. + /// + VSS_BS_ROLLFORWARD_RESTORE = 0x1000, + + /// + /// The writer supports a requester setting a restore name using + /// IVssBackupComponentsEx2::SetRestoreName + /// . + /// This value is not supported for express writers. + /// Windows Server 2003: + /// This value is not supported until Windows Vista. + /// + VSS_BS_RESTORE_RENAME = 0x2000, + + /// + /// The writer supports a requester setting authoritative restore using + /// IVssBackupComponentsEx2::SetAuthoritativeRestore + /// . + /// This value is not supported for express writers. + /// Windows Server 2003: + /// This value is not supported until Windows Vista. + /// + VSS_BS_AUTHORITATIVE_RESTORE = 0x4000, + + /// + /// The writer supports multiple unsynchronized restore events. + /// This value is not supported for express writers. + /// Windows Vista and Windows Server 2003: + /// This value is not supported until Windows Server 2008. + /// + VSS_BS_WRITER_SUPPORTS_PARALLEL_RESTORES = 0x8000, + } + + /// The VSS_BACKUP_TYPE enumeration indicates the type of backup to be performed using VSS writer/requester coordination. + /// + /// An implementation of a backup type defined by a VSS_BACKUP_TYPE value must be done using the VSS API. + /// + /// This is particularly true in the case of incremental ( VSS_BT_INCREMENTAL) and differential ( VSS_BT_DIFFERENTIAL) + /// backups. In these cases, requesters and writers work together using the file backup specification masks (VSS_FILE_SPEC_BACKUP_TYPE), + /// and designations of files as being part of partial and differenced file operations to select which files must be backed up. + /// + /// + /// A requester may also use other more traditional techniques to implement an incremental or differential restore, but it must not + /// override the information provided through the VSS interfaces. + /// + /// + /// If a requester, when processing a given backup type, encounters a writer that does not support that backup type, the requester + /// performs backup or restore operations for that particular writer's data as if the backup type was VSS_BT_FULL. + /// + /// Requesters set the backup type with a call to IVssBackupComponents::SetBackupState. + /// Writers use CVssWriter::GetBackupType to determine the backup type. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vss/ne-vss-vss_backup_type typedef enum _VSS_BACKUP_TYPE { VSS_BT_UNDEFINED, + // VSS_BT_FULL, VSS_BT_INCREMENTAL, VSS_BT_DIFFERENTIAL, VSS_BT_LOG, VSS_BT_COPY, VSS_BT_OTHER } VSS_BACKUP_TYPE, *PVSS_BACKUP_TYPE; + [PInvokeData("vss.h", MSDNShortId = "NE:vss._VSS_BACKUP_TYPE")] + public enum VSS_BACKUP_TYPE + { + /// + /// The backup type is not known. + /// This value indicates an application error. + /// + VSS_BT_UNDEFINED = 0, + + /// + /// Full backup: all files, regardless of whether they have been marked as backed up or not, are saved. This is + /// the default backup type and schema, and all writers support it. + /// Each file's backup history will be updated to reflect that it was backed up. + /// + VSS_BT_FULL, + + /// + /// Incremental backup: files created or changed since the last full or incremental backup are saved. Files are + /// marked as having been backed up. + /// A requester can implement this sort of backup on a particular writer only if it supports the + /// VSS_BS_INCREMENTAL + /// schema. + /// If a requester's backup type is + /// VSS_BT_INCREMENTAL + /// and a particular writer's + /// backup schema does not support that sort of backup, the requester will always perform a full + /// ( + /// VSS_BT_FULL + /// ) backup on that writer's data. + /// + VSS_BT_INCREMENTAL, + + /// + /// Differential backup: files created or changed since the last full backup are saved. Files are not marked as + /// having been backed up. + /// A requester can implement this sort of backup on a particular writer only if it supports the + /// VSS_BS_DIFFERENTIAL + /// schema. + /// If a requester's backup type is + /// VSS_BT_DIFFERENTIAL + /// and a particular writer's + /// backup schema does not support that sort of backup, the requester will always perform a full + /// ( + /// VSS_BT_FULL + /// ) backup on that writer's data. + /// + VSS_BT_DIFFERENTIAL, + + /// + /// The log file of a writer is to participate in backup or restore operations. + /// A requester can implement this sort of backup on a particular writer only if it supports the + /// VSS_BS_LOG + /// schema. + /// If a requester's backup type is + /// VSS_BT_LOG + /// and a particular writer's backup + /// schema does not support that sort of backup, the requester will always perform a full + /// ( + /// VSS_BT_FULL + /// ) backup on that writer's data. + /// + VSS_BT_LOG, + + /// + /// Files on disk will be copied to a backup medium regardless of the state of each file's backup history, and + /// the backup history will not be updated. + /// A requester can implement this sort of backup on a particular writer only if it supports the + /// VSS_BS_COPY + /// schema. + /// If a requester's backup type is + /// VSS_BT_COPY + /// and a particular writer's backup + /// schema does not support that sort of backup, the requester will always perform a full + /// ( + /// VSS_BT_FULL + /// ) backup on that writer's data. + /// + VSS_BT_COPY, + + /// Backup type that is not full, copy, log, incremental, or differential. + VSS_BT_OTHER, + } + + /// + /// + /// The VSS_FILE_SPEC_BACKUP_TYPE enumeration is used by writers to indicate their support of certain backup operations—such as + /// incremental or differential backup—on the basis of file sets (a specified file or files). + /// + /// + /// File sets stored in the Writer Metadata Document are tagged with a bit mask (or bitwise OR) of VSS_FILE_SPEC_BACKUP_TYPE + /// values indicating the following: + /// + /// + /// + /// Whether the writer and the requester have to evaluate a given file set for participation in the specified type of backup operations + /// + /// + /// Whether backing up the specified file will require a shadow copy + /// + /// + /// + /// + /// + /// When a writer sets a backup-required value of the VSS_FILE_SPEC_BACKUP_TYPE enumeration, it is indicating that the requester + /// perform the backup in such a way that, when the backup is restored, the current version of the file set is restored. Typically, this + /// means that the file set is copied as part of the backup. + /// + /// + /// This setting can be overridden if a file is added to the Backup Components Document as a differenced file (using + /// IVssComponent::AddDifferencedFilesByLastModifyTime) or as a partial file (using IVssComponent::AddPartialFile). + /// + /// + /// If a file is added as a differenced file, the writer establishes criteria by which the requester should decide whether or not to + /// actually copy a file to a backup medium. A writer typically adds differenced files to the Backup Components Document for inclusion + /// in a backup PostSnapshot event (see CVssWriter::OnPostSnapshot). See Incremental and Differential Backups for details. + /// + /// + /// When a writer sets a shadow copy-required value of the VSS_FILE_SPEC_BACKUP_TYPE enumeration, it indicates that the file set + /// should be backed up from a shadow-copied volume. File sets not tagged with a shadow copy-required value can be backed up from the + /// original volume. + /// + /// Writers set VSS_FILE_SPEC_BACKUP_TYPE values while handling an Identify event (see CVssWriter::OnIdentify). + /// + /// A bit mask (or bitwise OR) of VSS_FILE_SPEC_BACKUP_TYPE values can be applied to a file set when adding it to a component + /// using the IVssCreateWriterMetadata::AddFilesToFileGroup, IVssCreateWriterMetadata::AddDatabaseFiles, or + /// IVssCreateWriterMetadata::AddDatabaseLogFiles method. + /// + /// + /// If no explicit file specification backup type is supplied during the addition of a file specification to a component, the + /// specification is tagged with the default VSS_FILE_SPEC_BACKUP_TYPE value: (VSS_FSBT_ALL_BACKUP_REQUIRED | VSS_FSBT_ALL_SNAPSHOT_REQUIRED). + /// + /// + /// Requesters or writers can recover a file set's file specification backup type by using the IVssWMFiledesc::GetBackupTypeMask method. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vss/ne-vss-vss_file_spec_backup_type typedef enum _VSS_FILE_SPEC_BACKUP_TYPE { + // VSS_FSBT_FULL_BACKUP_REQUIRED, VSS_FSBT_DIFFERENTIAL_BACKUP_REQUIRED, VSS_FSBT_INCREMENTAL_BACKUP_REQUIRED, + // VSS_FSBT_LOG_BACKUP_REQUIRED, VSS_FSBT_FULL_SNAPSHOT_REQUIRED, VSS_FSBT_DIFFERENTIAL_SNAPSHOT_REQUIRED, + // VSS_FSBT_INCREMENTAL_SNAPSHOT_REQUIRED, VSS_FSBT_LOG_SNAPSHOT_REQUIRED, VSS_FSBT_CREATED_DURING_BACKUP, VSS_FSBT_ALL_BACKUP_REQUIRED, + // VSS_FSBT_ALL_SNAPSHOT_REQUIRED } VSS_FILE_SPEC_BACKUP_TYPE, *PVSS_FILE_SPEC_BACKUP_TYPE; + [PInvokeData("vss.h", MSDNShortId = "NE:vss._VSS_FILE_SPEC_BACKUP_TYPE")] + [Flags] + public enum VSS_FILE_SPEC_BACKUP_TYPE + { + /// + /// A file set tagged with this value must be involved in all types of backup operations. + /// A writer tags a file set with this value to indicate to the requester that it expects a copy of the current + /// version of the file set to be available following the restore of any backup operation with a + /// VSS_BACKUP_TYPE + /// of + /// VSS_BT_FULL + /// . + /// + VSS_FSBT_FULL_BACKUP_REQUIRED = 0x001, + + /// + /// A writer tags a file set with this value to indicate to the requester that it expects a copy of the current + /// version of the file set to be available following the restore of any backup operation with a + /// VSS_BACKUP_TYPE + /// of + /// VSS_BT_DIFFERENTIAL + /// . + /// This value is not supported for express writers. + /// + VSS_FSBT_DIFFERENTIAL_BACKUP_REQUIRED = 0x002, + + /// + /// A writer tags a file set with this value to indicate to the requester that it expects a copy of the current + /// version of the file set to be available following the restore of any backup operation with a + /// VSS_BACKUP_TYPE + /// of + /// VSS_BT_INCREMENTAL + /// . + /// This value is not supported for express writers. + /// + VSS_FSBT_INCREMENTAL_BACKUP_REQUIRED = 0x004, + + /// + /// A writer tags a file set with this value to indicate to the requester that it expects a copy of the current + /// version of the file set to be available following the restore of any backup operation with a + /// VSS_BACKUP_TYPE + /// of + /// VSS_BT_LOG + /// . + /// This value is not supported for express writers. + /// + VSS_FSBT_LOG_BACKUP_REQUIRED = 0x008, + + /// + /// A file set tagged with this value must be backed up from a shadow copy of a volume (and never from the + /// original volume) when participating in a backup operation with a + /// VSS_BACKUP_TYPE + /// of + /// VSS_BT_FULL + /// . + /// + VSS_FSBT_FULL_SNAPSHOT_REQUIRED = 0x100, + + /// + /// A file set tagged with this value must be backed up from a shadow copy of a volume (and never from the + /// original volume) when participating in a backup operation with a + /// VSS_BACKUP_TYPE + /// of + /// VSS_BT_DIFFERENTIAL + /// . + /// + VSS_FSBT_DIFFERENTIAL_SNAPSHOT_REQUIRED = 0x200, + + /// + /// A file set tagged with this value must be backed up from a shadow copy of a volume (and never from the + /// original volume) when participating in a backup operation with a + /// VSS_BACKUP_TYPE + /// of + /// VSS_BT_INCREMENTAL + /// . + /// + VSS_FSBT_INCREMENTAL_SNAPSHOT_REQUIRED = 0x400, + + /// + /// A file set tagged with this value must be backed up from a shadow copy of a volume (and never from the + /// original volume) when participating in a backup operation with a + /// VSS_BACKUP_TYPE + /// of + /// VSS_BT_LOG + /// ). + /// + VSS_FSBT_LOG_SNAPSHOT_REQUIRED = 0x800, + + /// + /// A writer tags a file set with this value to indicate to the requester that they expect the file to be created during the + /// snapshot sequence. + /// + VSS_FSBT_CREATED_DURING_BACKUP = 0x10000, + + /// + /// The default file backup specification type. A file set tagged with this value must always participate in + /// backup and restore operations. + /// + VSS_FSBT_ALL_BACKUP_REQUIRED = 0xF, + + /// + /// The shadow copy requirement for backup. A file set tagged with this value must always be backed up from a + /// shadow copy of a volume (and never from the original volume) when participating in a backup operation. + /// + VSS_FSBT_ALL_SNAPSHOT_REQUIRED = 0xF00, + } + + /// Defines shadow copy LUN flags. + // https://docs.microsoft.com/en-us/windows/win32/api/vss/ne-vss-vss_hardware_options typedef enum _VSS_HARDWARE_OPTIONS { + // VSS_BREAKEX_FLAG_MASK_LUNS, VSS_BREAKEX_FLAG_MAKE_READ_WRITE, VSS_BREAKEX_FLAG_REVERT_IDENTITY_ALL, + // VSS_BREAKEX_FLAG_REVERT_IDENTITY_NONE, VSS_ONLUNSTATECHANGE_NOTIFY_READ_WRITE, VSS_ONLUNSTATECHANGE_NOTIFY_LUN_PRE_RECOVERY, + // VSS_ONLUNSTATECHANGE_NOTIFY_LUN_POST_RECOVERY, VSS_ONLUNSTATECHANGE_DO_MASK_LUNS } VSS_HARDWARE_OPTIONS, *PVSS_HARDWARE_OPTIONS; + [PInvokeData("vss.h", MSDNShortId = "NE:vss._VSS_HARDWARE_OPTIONS")] + [Flags] + public enum VSS_HARDWARE_OPTIONS + { + /// The shadow copy LUN will be masked from the host. + VSS_BREAKEX_FLAG_MASK_LUNS = 0x001, + + /// The shadow copy LUN will be exposed to the host as a read-write volume. + VSS_BREAKEX_FLAG_MAKE_READ_WRITE = 0x002, + + /// + /// The disk identifiers of all of the shadow copy LUNs will be reverted to that of the original LUNs. However, if any of the + /// original LUNs are present on the system, the operation will fail and none of the identifiers will be reverted. + /// + VSS_BREAKEX_FLAG_REVERT_IDENTITY_ALL = 0x004, + + /// None of the disk identifiers of the shadow copy LUNs will be reverted. + VSS_BREAKEX_FLAG_REVERT_IDENTITY_NONE = 0x008, + + /// + /// + /// The shadow copy LUNs will be converted permanently to read-write. This flag is set only as a notification for the provider; no + /// provider action is required. For more information, see the + /// + /// IVssHardwareSnapshotProviderEx::OnLunStateChange + /// method. + /// + VSS_ONLUNSTATECHANGE_NOTIFY_READ_WRITE = 0x100, + + /// + /// + /// The shadow copy LUNs will be converted temporarily to read-write and are about to undergo TxF recovery or VSS auto-recovery. + /// This flag is set only as a notification for the provider; no provider action is required. For more information, see the + /// + /// IVssHardwareSnapshotProviderEx::OnLunStateChange + /// method. + /// + VSS_ONLUNSTATECHANGE_NOTIFY_LUN_PRE_RECOVERY = 0x200, + + /// + /// + /// The shadow copy LUNs have just undergone TxF recovery or VSS auto-recovery and have been converted back to read-only. This flag + /// is set only as a notification for the provider; no provider action is required. For more information, see the + /// + /// IVssHardwareSnapshotProviderEx::OnLunStateChange + /// method. + /// + VSS_ONLUNSTATECHANGE_NOTIFY_LUN_POST_RECOVERY = 0x400, + + /// + /// The provider must mask shadow copy LUNs from this computer. For more information, see the + /// IVssHardwareSnapshotProviderEx::OnLunStateChange + /// method. + /// + VSS_ONLUNSTATECHANGE_DO_MASK_LUNS = 0x800, + } + + /// + /// The VSS_OBJECT_TYPE enumeration is used by requesters to identify an object as a shadow copy set, shadow copy, or provider. + /// + /// + /// + /// VSS_OBJECT_TYPE is used when calling IVssBackupComponents::Query to specify the types of objects about which to obtain + /// information. An input of VSS_OBJECT_NONE will return information about all objects. + /// + /// + /// In addition, VSS_OBJECT_TYPE is used as an input to IVssBackupComponents::DeleteSnapshots. However, DeleteSnapshots + /// accepts only VSS_OBJECT_TYPE values of VSS_OBJECT_SNAPSHOT_SET or VSS_OBJECT_SNAPSHOT. + /// + /// The Type member of VSS_OBJECT_PROP is a member of the VSS_OBJECT_TYPE enumeration. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vss/ne-vss-vss_object_type typedef enum _VSS_OBJECT_TYPE { VSS_OBJECT_UNKNOWN, + // VSS_OBJECT_NONE, VSS_OBJECT_SNAPSHOT_SET, VSS_OBJECT_SNAPSHOT, VSS_OBJECT_PROVIDER, VSS_OBJECT_TYPE_COUNT } VSS_OBJECT_TYPE, *PVSS_OBJECT_TYPE; + [PInvokeData("vss.h", MSDNShortId = "NE:vss._VSS_OBJECT_TYPE")] + public enum VSS_OBJECT_TYPE + { + /// + /// The object type is not known. + /// This indicates an application error. + /// + VSS_OBJECT_UNKNOWN = 0, + + /// + /// The interpretation of this value depends on whether it is used as an input to a VSS method or returned as + /// an output from a VSS method. + /// When used as an input to a VSS method, it indicates that the method is not restricted to any particular + /// object type, but should act on all appropriate objects. In this sense, + /// VSS_OBJECT_NONE + /// can be thought of as a wildcard input. + /// When returned as an output, the object type is not known and means that there has been an application + /// error. + /// + VSS_OBJECT_NONE, + + /// Shadow copy set. + VSS_OBJECT_SNAPSHOT_SET, + + /// Shadow copy. + VSS_OBJECT_SNAPSHOT, + + /// Shadow copy provider. + VSS_OBJECT_PROVIDER, + + /// Reserved value. + VSS_OBJECT_TYPE_COUNT, + } + + /// + /// Not supported. + /// This enumeration is reserved for future use. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vss/ne-vss-vss_provider_capabilities typedef enum _VSS_PROVIDER_CAPABILITIES { + // VSS_PRV_CAPABILITY_LEGACY, VSS_PRV_CAPABILITY_COMPLIANT, VSS_PRV_CAPABILITY_LUN_REPOINT, VSS_PRV_CAPABILITY_LUN_RESYNC, + // VSS_PRV_CAPABILITY_OFFLINE_CREATION, VSS_PRV_CAPABILITY_MULTIPLE_IMPORT, VSS_PRV_CAPABILITY_RECYCLING, VSS_PRV_CAPABILITY_PLEX, + // VSS_PRV_CAPABILITY_DIFFERENTIAL, VSS_PRV_CAPABILITY_CLUSTERED } VSS_PROVIDER_CAPABILITIES, *PVSS_PROVIDER_CAPABILITIES; + [PInvokeData("vss.h", MSDNShortId = "NE:vss._VSS_PROVIDER_CAPABILITIES")] + [Flags] + public enum VSS_PROVIDER_CAPABILITIES : ulong + { + /// + VSS_PRV_CAPABILITY_LEGACY = 0x001, + + /// + VSS_PRV_CAPABILITY_COMPLIANT = 0x002, + + /// + VSS_PRV_CAPABILITY_LUN_REPOINT = 0x004, + + /// + VSS_PRV_CAPABILITY_LUN_RESYNC = 0x008, + + /// + VSS_PRV_CAPABILITY_OFFLINE_CREATION = 0x010, + + /// + VSS_PRV_CAPABILITY_MULTIPLE_IMPORT = 0x020, + + /// + VSS_PRV_CAPABILITY_RECYCLING = 0x040, + + /// + VSS_PRV_CAPABILITY_PLEX = 0x080, + + /// + VSS_PRV_CAPABILITY_DIFFERENTIAL = 0x100, + + /// + VSS_PRV_CAPABILITY_CLUSTERED = 0x200, + } + + /// The VSS_PROVIDER_TYPE enumeration specifies the provider type. + // https://docs.microsoft.com/en-us/windows/win32/api/vss/ne-vss-vss_provider_type typedef enum _VSS_PROVIDER_TYPE { VSS_PROV_UNKNOWN, + // VSS_PROV_SYSTEM, VSS_PROV_SOFTWARE, VSS_PROV_HARDWARE, VSS_PROV_FILESHARE } VSS_PROVIDER_TYPE, *PVSS_PROVIDER_TYPE; + [PInvokeData("vss.h", MSDNShortId = "NE:vss._VSS_PROVIDER_TYPE")] + public enum VSS_PROVIDER_TYPE + { + /// + /// The provider type is unknown. + /// This indicates an error in the application or the VSS service, or that no provider is available. + /// + VSS_PROV_UNKNOWN = 0, + + /// The default provider that ships with Windows. + VSS_PROV_SYSTEM, + + /// A software provider. + VSS_PROV_SOFTWARE, + + /// A hardware provider. + VSS_PROV_HARDWARE, + + /// + /// A file share provider. + /// Windows 7, Windows Server 2008 R2, Windows Vista, Windows Server 2008, Windows XP and Windows Server 2003: + /// This enumeration value is not supported until Windows 8 and Windows Server 2012. + /// + VSS_PROV_FILESHARE, + } + + /// Used by a requester to specify how a resynchronization operation is to be performed. + // https://docs.microsoft.com/en-us/windows/win32/api/vss/ne-vss-vss_recovery_options typedef enum _VSS_RECOVERY_OPTIONS { + // VSS_RECOVERY_REVERT_IDENTITY_ALL, VSS_RECOVERY_NO_VOLUME_CHECK } VSS_RECOVERY_OPTIONS, *PVSS_RECOVERY_OPTIONS; + [PInvokeData("vss.h", MSDNShortId = "NE:vss._VSS_RECOVERY_OPTIONS")] + [Flags] + public enum VSS_RECOVERY_OPTIONS + { + /// + /// After the resynchronization operation is complete, the signature of each target LUN should be identical to that of the original + /// LUN that was used to create the shadow copy. + /// + VSS_RECOVERY_REVERT_IDENTITY_ALL = 0x100, + + /// Volume safety checks should not be performed. + VSS_RECOVERY_NO_VOLUME_CHECK = 0x200, + } + + /// + /// The VSS_RESTORE_TYPE enumeration is used by a requester to indicate the type of restore operation it is about to perform. + /// + /// + /// A requester can optionally set the type of a restore operation using IVssBackupComponents::SetRestoreState. + /// A writer can retrieve the type of a restore operation by calling CVssWriter::GetRestoreType. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vss/ne-vss-vss_restore_type typedef enum _VSS_RESTORE_TYPE { VSS_RTYPE_UNDEFINED, + // VSS_RTYPE_BY_COPY, VSS_RTYPE_IMPORT, VSS_RTYPE_OTHER } VSS_RESTORE_TYPE, *PVSS_RESTORE_TYPE; + [PInvokeData("vss.h", MSDNShortId = "NE:vss._VSS_RESTORE_TYPE")] + public enum VSS_RESTORE_TYPE + { + /// + /// No restore type is defined. + /// This is the default restore type. However, writers should treat this restore type as if it were VSS_RTYPE_BY_COPY. + /// This indicates an error on the part of the requester. + /// + VSS_RTYPE_UNDEFINED = 0, + + /// + /// A requester restores backed-up data to the original volume from a backup + /// medium. + /// + VSS_RTYPE_BY_COPY, + + /// + /// A requester does not copy data from a backup medium, but imports a transportable shadow copy and uses this + /// imported volume for operations such as data mining. + /// Windows Server 2003, Standard Edition and Windows Server 2003, Web Edition: + /// This value is not supported. All editions of Windows Server 2003 with SP1 support this value. + /// + VSS_RTYPE_IMPORT, + + /// A restore type not currently enumerated. This value indicates an application error. + VSS_RTYPE_OTHER, + } + + /// + /// The VSS_ROLLFORWARD_TYPE enumeration is used by a requester to indicate the type of roll-forward operation it is about to perform. + /// + /// + /// A requester sets the roll-forward operation type and specifies the restore point for partial roll-forward operations using IVssBackupComponentsEx2::SetRollForward. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vss/ne-vss-vss_rollforward_type typedef enum _VSS_ROLLFORWARD_TYPE { + // VSS_RF_UNDEFINED, VSS_RF_NONE, VSS_RF_ALL, VSS_RF_PARTIAL } VSS_ROLLFORWARD_TYPE, *PVSS_ROLLFORWARD_TYPE; + [PInvokeData("vss.h", MSDNShortId = "NE:vss._VSS_ROLLFORWARD_TYPE")] + public enum VSS_ROLLFORWARD_TYPE + { + /// + /// No roll-forward type is defined. + /// This indicates an error on the part of the requester. + /// + VSS_RF_UNDEFINED = 0, + + /// The roll-forward operation should not roll forward through logs. + VSS_RF_NONE, + + /// The roll-forward operation should roll forward through all logs. + VSS_RF_ALL, + + /// The roll-forward operation should roll forward through logs up to a specified restore point. + VSS_RF_PARTIAL, + } + + /// + /// The VSS_SNAPSHOT_COMPATIBILITY enumeration indicates which volume control or file I/O operations are disabled for the volume + /// that has been shadow copied. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vss/ne-vss-vss_snapshot_compatibility typedef enum _VSS_SNAPSHOT_COMPATIBILITY { + // VSS_SC_DISABLE_DEFRAG, VSS_SC_DISABLE_CONTENTINDEX } VSS_SNAPSHOT_COMPATIBILITY; + [PInvokeData("vss.h", MSDNShortId = "NE:vss._VSS_SNAPSHOT_COMPATIBILITY")] + [Flags] + public enum VSS_SNAPSHOT_COMPATIBILITY + { + /// + /// The provider managing the shadow copies for a specified volume does not support defragmentation operations + /// on that volume. + /// + VSS_SC_DISABLE_DEFRAG = 0x01, + + /// + /// The provider managing the shadow copies for a specified volume does not support content index operations on + /// that volume. + /// + VSS_SC_DISABLE_CONTENTINDEX = 0x02, + } + + /// + /// The _VSS_SNAPSHOT_CONTEXT enumeration enables a requester using IVssBackupComponents::SetContext to specify how a shadow copy + /// is to be created, queried, or deleted and the degree of writer involvement. + /// + /// + /// The data type to be used with values of _VSS_SNAPSHOT_CONTEXT is LONG. + /// The default context for VSS shadow copies is VSS_CTX_BACKUP. + /// + /// Windows XP: The only supported context is the default, VSS_CTX_BACKUP. Calling IVssBackupComponents::SetContext will + /// return E_NOTIMPL. + /// + /// For details on how to use VSS shadow copies contexts, see Implementation Details for Creating Shadow Copies. + /// + /// Shadow copy behavior can be further controlled by using a bitwise OR to combine a supported _VSS_VOLUME_SNAPSHOT_ATTRIBUTES with + /// valid _VSS_SNAPSHOT_CONTEXT values as an argument to the IVssBackupComponents::SetContext method. + /// + /// + /// Currently, the only supported modifications are the bitwise OR of a _VSS_SNAPSHOT_CONTEXT value with the + /// VSS_VOLSNAP_ATTR_TRANSPORTABLE and either the VSS_VOLSNAP_ATTR_DIFFERENTIAL or the VSS_VOLSNAP_ATTR_PLEX value + /// of the _VSS_VOLUME_SNAPSHOT_ATTRIBUTES enumeration. + /// + /// However, these values cannot be used to modify VSS_CTX_CLIENT_ACCESSIBLE context. + /// + /// The use of VSS_VOLSNAP_ATTR_TRANSPORTABLE is limited to systems running Windows Server 2008 Enterprise, Windows Server 2008 + /// Datacenter, Windows Server 2003, Enterprise Edition, or Windows Server 2003, Datacenter Edition. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vss/ne-vss-vss_snapshot_context typedef enum _VSS_SNAPSHOT_CONTEXT { + // VSS_CTX_BACKUP, VSS_CTX_FILE_SHARE_BACKUP, VSS_CTX_NAS_ROLLBACK, VSS_CTX_APP_ROLLBACK, VSS_CTX_CLIENT_ACCESSIBLE, + // VSS_CTX_CLIENT_ACCESSIBLE_WRITERS, VSS_CTX_ALL } VSS_SNAPSHOT_CONTEXT, *PVSS_SNAPSHOT_CONTEXT; + [PInvokeData("vss.h", MSDNShortId = "NE:vss._VSS_SNAPSHOT_CONTEXT")] + [Flags] + public enum VSS_SNAPSHOT_CONTEXT : uint + { + /// + /// The standard backup context. Specifies an auto-release, nonpersistent shadow copy in which writers are + /// involved in the creation. + /// + VSS_CTX_BACKUP = 0, + + /// Specifies an auto-release, nonpersistent shadow copy created without writer involvement. + VSS_CTX_FILE_SHARE_BACKUP = VSS_VOLUME_SNAPSHOT_ATTRIBUTES.VSS_VOLSNAP_ATTR_NO_WRITERS, + + /// + /// Specifies a persistent, non-auto-release shadow copy without writer involvement. This context should be + /// used when there is no need for writer involvement to ensure that files are in a consistent state at the time + /// of the shadow copy. + /// Lightweight automated file rollback mechanisms or persistent shadow copies of file shares or data volumes + /// that are not expected to contain any system-related files or databases might run under this context. For + /// example, a requester could use this context for creating a shadow copy of a NAS volume hosting documents and + /// simple user shares. Those types of data do not need writer involvement to create a consistent shadow copy. + /// + VSS_CTX_NAS_ROLLBACK = VSS_VOLUME_SNAPSHOT_ATTRIBUTES.VSS_VOLSNAP_ATTR_PERSISTENT | VSS_VOLUME_SNAPSHOT_ATTRIBUTES.VSS_VOLSNAP_ATTR_NO_AUTO_RELEASE | VSS_VOLUME_SNAPSHOT_ATTRIBUTES.VSS_VOLSNAP_ATTR_NO_WRITERS, + + /// + /// Specifies a persistent, non-auto-release shadow copy with writer involvement. This context is designed + /// to be used when writers are needed to ensure that files are in a well-defined state prior to shadow copy. + /// Automated file rollback mechanisms of system volumes and shadow copies to be used in data mining or restore + /// operations might run under this context. This context is similar to + /// VSS_CTX_BACKUP + /// but allows a requester more control over the persistence of the shadow copy. + /// + VSS_CTX_APP_ROLLBACK = VSS_VOLUME_SNAPSHOT_ATTRIBUTES.VSS_VOLSNAP_ATTR_PERSISTENT | VSS_VOLUME_SNAPSHOT_ATTRIBUTES.VSS_VOLSNAP_ATTR_NO_AUTO_RELEASE, + + /// + /// Specifies a read-only, + /// client-accessible shadow copy + /// + /// that supports Shadow Copies for Shared Folders and is created without writer involvement. Only the system provider (the default + /// provider available on the system) can create this type of shadow copy. + /// + /// Most requesters will want to use the + /// VSS_CTX_NAS_ROLLBACK + /// context for persistent, non-auto-release shadow copies without writer involvement. + /// + VSS_CTX_CLIENT_ACCESSIBLE = VSS_VOLUME_SNAPSHOT_ATTRIBUTES.VSS_VOLSNAP_ATTR_PERSISTENT | VSS_VOLUME_SNAPSHOT_ATTRIBUTES.VSS_VOLSNAP_ATTR_NO_AUTO_RELEASE | VSS_VOLUME_SNAPSHOT_ATTRIBUTES.VSS_VOLSNAP_ATTR_CLIENT_ACCESSIBLE | VSS_VOLUME_SNAPSHOT_ATTRIBUTES.VSS_VOLSNAP_ATTR_NO_WRITERS, + + /// + /// Specifies a read-only, + /// client-accessible shadow copy + /// + /// that is created with writer involvement. Only the system provider (the default provider available on the system) can create this + /// type of shadow copy. + /// + /// Most requesters will want to use the + /// VSS_CTX_APP_ROLLBACK + /// context for persistent, non-auto-release shadow copies with writer involvement. + /// Windows Server 2003 and Windows XP: + /// This context is not supported by Windows Server 2003 and Windows XP. + /// + VSS_CTX_CLIENT_ACCESSIBLE_WRITERS = VSS_VOLUME_SNAPSHOT_ATTRIBUTES.VSS_VOLSNAP_ATTR_PERSISTENT | VSS_VOLUME_SNAPSHOT_ATTRIBUTES.VSS_VOLSNAP_ATTR_NO_AUTO_RELEASE | VSS_VOLUME_SNAPSHOT_ATTRIBUTES.VSS_VOLSNAP_ATTR_CLIENT_ACCESSIBLE, + + /// + /// All types of currently live shadow copies are available for administrative operations, such as shadow copy + /// queries (see + /// IVssBackupComponents::Query + /// ). + /// VSS_CTX_ALL + /// is a valid context for all VSS interfaces except + /// IVssBackupComponents::StartSnapshotSet + /// and + /// IVssBackupComponents::DoSnapshotSet + /// . + /// + VSS_CTX_ALL = 0xffffffff, + } + + /// Specifies the property to be set for a shadow copy. + // https://docs.microsoft.com/en-us/windows/win32/api/vss/ne-vss-vss_snapshot_property_id + // typedef enum _VSS_SNAPSHOT_PROPERTY_ID { VSS_SPROPID_UNKNOWN, VSS_SPROPID_SNAPSHOT_ID, VSS_SPROPID_SNAPSHOT_SET_ID, VSS_SPROPID_SNAPSHOTS_COUNT, VSS_SPROPID_SNAPSHOT_DEVICE, VSS_SPROPID_ORIGINAL_VOLUME, VSS_SPROPID_ORIGINATING_MACHINE, VSS_SPROPID_SERVICE_MACHINE, VSS_SPROPID_EXPOSED_NAME, VSS_SPROPID_EXPOSED_PATH, VSS_SPROPID_PROVIDER_ID, VSS_SPROPID_SNAPSHOT_ATTRIBUTES, VSS_SPROPID_CREATION_TIMESTAMP, VSS_SPROPID_STATUS } VSS_SNAPSHOT_PROPERTY_ID, *PVSS_SNAPSHOT_PROPERTY_ID; + [PInvokeData("vss.h", MSDNShortId = "NE:vss._VSS_SNAPSHOT_PROPERTY_ID")] + public enum VSS_SNAPSHOT_PROPERTY_ID + { + /// + /// The property is not known. + /// This value indicates an application error. + /// + VSS_SPROPID_UNKNOWN, + /// + /// The shadow copy identifier. For more information, see the + /// m_SnapshotId + /// member of the + /// VSS_SNAPSHOT_PROP + /// structure. + /// + VSS_SPROPID_SNAPSHOT_ID, + /// + /// The shadow copy set identifier. For more information, see the + /// m_SnapshotSetId + /// member of the + /// VSS_SNAPSHOT_PROP + /// structure. + /// + VSS_SPROPID_SNAPSHOT_SET_ID, + /// + /// The number of volumes included with the shadow copy in the shadow copy set when it was created. For more + /// information, see the + /// m_lSnapshotsCount + /// member of the + /// VSS_SNAPSHOT_PROP + /// structure. + /// + VSS_SPROPID_SNAPSHOTS_COUNT, + /// + /// Null-terminated wide character string that specifies the name of the device object for the shadow copy of the + /// volume. For more information, see the + /// m_pwszSnapshotDeviceObject + /// member of the + /// VSS_SNAPSHOT_PROP + /// structure. + /// + VSS_SPROPID_SNAPSHOT_DEVICE, + /// + /// A null-terminated wide character string that specifies the name of the original volume. For more information, see the + /// m_pwszOriginalVolumeName + /// member of the + /// VSS_SNAPSHOT_PROP + /// structure. + /// + VSS_SPROPID_ORIGINAL_VOLUME, + /// + /// A null-terminated wide character string that specifies the name of the machine that contains the original + /// volume. For more information, see the + /// m_pwszOriginatingMachine + /// member of the + /// VSS_SNAPSHOT_PROP + /// structure. + /// + VSS_SPROPID_ORIGINATING_MACHINE, + /// + /// A null-terminated wide character string that specifies the name of the machine that is running the Volume Shadow Copy + /// Service that created the shadow copy. For more information, see the + /// m_pwszServiceMachine + /// member of the + /// VSS_SNAPSHOT_PROP + /// structure. + /// + VSS_SPROPID_SERVICE_MACHINE, + /// + /// A null-terminated wide character string that specifies the name of the shadow copy when it is exposed. For more information, see the + /// m_pwszExposedName + /// member of the + /// VSS_SNAPSHOT_PROP + /// structure. + /// + VSS_SPROPID_EXPOSED_NAME, + /// + /// A null-terminated wide character string that specifies the portion of the volume that is made available + /// when the shadow copy is exposed as a file share. For more information, see the + /// m_pwszExposedPath + /// member of the + /// VSS_SNAPSHOT_PROP + /// structure. + /// + VSS_SPROPID_EXPOSED_PATH, + /// + /// The provider identifier. For more information, see the + /// m_ProviderId + /// member of the + /// VSS_SNAPSHOT_PROP + /// structure. + /// + VSS_SPROPID_PROVIDER_ID, + /// + /// A bitmask of + /// _VSS_VOLUME_SNAPSHOT_ATTRIBUTES + /// values that specify the properties of the shadow copy. For more information, see the + /// m_lSnapshotAttributes + /// member of the + /// VSS_SNAPSHOT_PROP + /// structure. + /// + VSS_SPROPID_SNAPSHOT_ATTRIBUTES, + /// + /// A time stamp that specifies when the shadow copy was created. For more information, see the + /// m_tsCreationTimestamp + /// member of the + /// VSS_SNAPSHOT_PROP + /// structure. + /// + VSS_SPROPID_CREATION_TIMESTAMP, + /// + /// The status of the current shadow copy creation operation. For more information, see the + /// m_eStatus + /// member of the + /// VSS_SNAPSHOT_PROP + /// structure. + /// + VSS_SPROPID_STATUS, + } + + /// The VSS_SNAPSHOT_STATE enumeration is returned by a provider to specify the state of a given shadow copy operation. + /// + /// + /// The shadow copy state is contained in the m_eStatus member of a VSS_SNAPSHOT_PROP object, which can be obtained for a single + /// shadow copy by calling IVssBackupComponents::GetSnapshotProperties. + /// + /// + /// Because IVssBackupComponents::GetSnapshotProperties fails during shadow copy creation with VSS_E_OBJECT_NOT_FOUND, a + /// requester cannot obtain any VSS_SNAPSHOT_STATE value other than VSS_SS_CREATED. + /// + /// + /// Calls to IVssBackupComponents::Query can also be used to obtain the shadow copy state. IVssBackupComponents::Query is used to + /// return lists of shadow copies, which may be iterated over by means of the IVssEnumObject interface to obtain VSS_SNAPSHOT_PROP + /// objects for each shadow copy that have completed on a given system. This means that, like + /// IVssBackupComponents::GetSnapshotProperties, the IVssBackupComponents::Query method can return only a shadow copy state of VSS_SS_CREATED. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vss/ne-vss-vss_snapshot_state typedef enum _VSS_SNAPSHOT_STATE { VSS_SS_UNKNOWN, + // VSS_SS_PREPARING, VSS_SS_PROCESSING_PREPARE, VSS_SS_PREPARED, VSS_SS_PROCESSING_PRECOMMIT, VSS_SS_PRECOMMITTED, + // VSS_SS_PROCESSING_COMMIT, VSS_SS_COMMITTED, VSS_SS_PROCESSING_POSTCOMMIT, VSS_SS_PROCESSING_PREFINALCOMMIT, VSS_SS_PREFINALCOMMITTED, + // VSS_SS_PROCESSING_POSTFINALCOMMIT, VSS_SS_CREATED, VSS_SS_ABORTED, VSS_SS_DELETED, VSS_SS_POSTCOMMITTED, VSS_SS_COUNT } + // VSS_SNAPSHOT_STATE, *PVSS_SNAPSHOT_STATE; + [PInvokeData("vss.h", MSDNShortId = "NE:vss._VSS_SNAPSHOT_STATE")] + public enum VSS_SNAPSHOT_STATE + { + /// + /// Reserved for system use. + /// Unknown shadow copy state. + /// + VSS_SS_UNKNOWN = 0, + + /// + /// Reserved for system use. + /// Shadow copy is being prepared. + /// + VSS_SS_PREPARING, + + /// + /// Reserved for system use. + /// Processing of the shadow copy preparation is in progress. + /// + VSS_SS_PROCESSING_PREPARE, + + /// + /// Reserved for system use. + /// Shadow copy has been prepared. + /// + VSS_SS_PREPARED, + + /// + /// Reserved for system use. + /// Processing of the shadow copy precommit is in process. + /// + VSS_SS_PROCESSING_PRECOMMIT, + + /// + /// Reserved for system use. + /// Shadow copy is precommitted. + /// + VSS_SS_PRECOMMITTED, + + /// + /// Reserved for system use. + /// Processing of the shadow copy commit is in process. + /// + VSS_SS_PROCESSING_COMMIT, + + /// + /// Reserved for system use. + /// Shadow copy is committed. + /// + VSS_SS_COMMITTED, + + /// + /// Reserved for system use. + /// Processing of the shadow copy postcommit is in process. + /// + VSS_SS_PROCESSING_POSTCOMMIT, + + /// + /// Reserved for system use. + /// Processing of the shadow copy file commit operation is underway. + /// + VSS_SS_PROCESSING_PREFINALCOMMIT, + + /// + /// Reserved for system use. + /// Processing of the shadow copy file commit operation is done. + /// + VSS_SS_PREFINALCOMMITTED, + + /// + /// Reserved for system use. + /// Processing of the shadow copy following the final commit and prior to shadow copy create is underway. + /// + VSS_SS_PROCESSING_POSTFINALCOMMIT, + + /// Shadow copy is created. + VSS_SS_CREATED, + + /// + /// Reserved for system use. + /// Shadow copy creation is aborted. + /// + VSS_SS_ABORTED, + + /// + /// Reserved for system use. + /// Shadow copy has been deleted. + /// + VSS_SS_DELETED, + + /// + VSS_SS_POSTCOMMITTED, + + /// Reserved value. + VSS_SS_COUNT, + } + + /// + /// Allows additional attributes to be specified for a shadow copy. The context of a shadow copy (as set by the + /// IVssBackupComponents::SetContext method) may be modified by a bitmask that contains a valid combination of + /// _VSS_VOLUME_SNAPSHOT_ATTRIBUTES and _VSS_SNAPSHOT_CONTEXT enumeration values. + /// + /// + /// The default context for VSS shadow copies is VSS_CTX_BACKUP. + /// + /// A requester sets the context for a shadow copy about to be created by passing the member of the _VSS_SNAPSHOT_CONTEXT enumeration to + /// the IVssBackupComponents::SetContext method. + /// + /// + /// Requesters can modify this context by using a bitwise OR of the _VSS_SNAPSHOT_CONTEXT value with a supported value from the + /// _VSS_VOLUME_SNAPSHOT_ATTRIBUTES enumeration as an argument to IVssBackupComponents::SetContext. + /// + /// + /// Unless specifically requested to support a given mechanism, providers are free to use any type of mechanism to implement a shadow + /// copy. Therefore, in the case where a shadow copy method is not specified, the provider is free to choose a differential mechanism ( + /// VSS_VOLSNAP_ATTR_DIFFERENTIAL), a PLEX mechanism ( VSS_VOLSNAP_ATTR_PLEX), or any other mechanism to support the + /// shadow copy. + /// + /// + /// While a provider can support both mechanisms, they are mutually exclusive for a given shadow copy. Requesters should not use both + /// VSS_VOLSNAP_ATTR_DIFFERENTIAL and VSS_VOLSNAP_ATTR_PLEX to modify a specific shadow copy context. + /// + /// + /// Currently, VSS_VOLSNAP_ATTR_DIFFERENTIAL, VSS_VOLSNAP_ATTR_PLEX, and VSS_VOLSNAP_ATTR_TRANSPORTABLE are the + /// only values of the _VSS_VOLUME_SNAPSHOT_ATTRIBUTES enumeration that can be used to modify any context. + /// + /// In addition, it cannot be used to modify a VSS_CTX_CLIENT_ACCESSIBLE context. + /// + /// A requester can obtain information about a specific shadow copy (identified by VSS_ID) by unpacking the VSS_SNAPSHOT_PROP structure + /// from the VSS_OBJECT_PROP structure returned by a call to IVssBackupComponents::GetSnapshotProperties. + /// + /// + /// A requester can also obtain a VSS_SNAPSHOT_PROP structure for each of multiple shadow copies by calling IVssBackupComponents::Query + /// and using IVssEnumObject to iterate the returns. + /// + /// + /// The shadow copies' context and attributes are found as a bit mask contained in the m_lSnapshotAttributes member of the + /// VSS_SNAPSHOT_PROP structure. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vss/ne-vss-vss_volume_snapshot_attributes typedef enum + // _VSS_VOLUME_SNAPSHOT_ATTRIBUTES { VSS_VOLSNAP_ATTR_PERSISTENT, VSS_VOLSNAP_ATTR_NO_AUTORECOVERY, VSS_VOLSNAP_ATTR_CLIENT_ACCESSIBLE, + // VSS_VOLSNAP_ATTR_NO_AUTO_RELEASE, VSS_VOLSNAP_ATTR_NO_WRITERS, VSS_VOLSNAP_ATTR_TRANSPORTABLE, VSS_VOLSNAP_ATTR_NOT_SURFACED, + // VSS_VOLSNAP_ATTR_NOT_TRANSACTED, VSS_VOLSNAP_ATTR_HARDWARE_ASSISTED, VSS_VOLSNAP_ATTR_DIFFERENTIAL, VSS_VOLSNAP_ATTR_PLEX, + // VSS_VOLSNAP_ATTR_IMPORTED, VSS_VOLSNAP_ATTR_EXPOSED_LOCALLY, VSS_VOLSNAP_ATTR_EXPOSED_REMOTELY, VSS_VOLSNAP_ATTR_AUTORECOVER, + // VSS_VOLSNAP_ATTR_ROLLBACK_RECOVERY, VSS_VOLSNAP_ATTR_DELAYED_POSTSNAPSHOT, VSS_VOLSNAP_ATTR_TXF_RECOVERY, VSS_VOLSNAP_ATTR_FILE_SHARE + // } VSS_VOLUME_SNAPSHOT_ATTRIBUTES, *PVSS_VOLUME_SNAPSHOT_ATTRIBUTES; + [PInvokeData("vss.h", MSDNShortId = "NE:vss._VSS_VOLUME_SNAPSHOT_ATTRIBUTES")] + [Flags] + public enum VSS_VOLUME_SNAPSHOT_ATTRIBUTES : uint + { + /// + /// The shadow copy is persistent across reboots. + /// This attribute is automatically set for + /// _VSS_SNAPSHOT_CONTEXT + /// contexts of + /// VSS_CTX_APP_ROLLBACK + /// , + /// VSS_CTX_CLIENT_ACCESSIBLE + /// , + /// VSS_CTX_CLIENT_ACCESSIBLE_WRITERS + /// , and + /// VSS_CTX_NAS_ROLLBACK + /// . + /// This attribute should not be used explicitly by requesters when setting the context of a shadow copy. + /// + VSS_VOLSNAP_ATTR_PERSISTENT = 0x01, + + /// + /// Auto-recovery + /// is disabled for the shadow copy. + /// + /// A requester can modify a shadow copy context with a bitwise OR of this attribute. By doing this, the requester instructs VSS to + /// make the shadow copy read-only immediately after it is created, without allowing writers or other applications to update + /// components in the shadow copy. /// /// - /// VSS first sends a Freeze event to writers initialized with VSS_APP_FRONT_END (called front-end level applications), then - /// to writers initialized with VSS_APP_BACK_END (called back-end level applications), and finally to writers initialized - /// with VSS_APP_SYSTEM (called system-level applications). + /// Disabling auto-recovery can cause the shadow copy to be in an inconsistent state if any of its components are involved in + /// transactional database operations, such as transactional read and write operations managed by Transactional NTFS (TxF). This is + /// because disabling auto-recovery prevents incomplete transactions from being rolled back. + /// + /// + /// Disabling auto-recovery also prevents writers from excluding files from the shadow copy. When auto-recovery is disabled, a + /// writer can still call the + /// + /// IVssCreateWriterMetadataEx::AddExcludeFilesFromSnapshot + /// method, but the writer's + /// CVssWriter::OnPostSnapshot + /// method cannot delete the files from the shadow copy. + /// Windows Server 2003 and Windows XP: + /// This value is not supported until Windows Vista. + /// + VSS_VOLSNAP_ATTR_NO_AUTORECOVERY = 0x02, + + /// + /// The specified shadow copy is a + /// client-accessible shadow copy + /// that supports Shadow Copies for Shared Folders, and should not be exposed. + /// This attribute is automatically set for + /// VSS_CTX_CLIENT_ACCESSIBLE + /// and + /// VSS_CTX_CLIENT_ACCESSIBLE_WRITERS + /// . + /// This attribute should not be used explicitly by requesters when setting the context of a shadow copy. + /// + VSS_VOLSNAP_ATTR_CLIENT_ACCESSIBLE = 0x04, + + /// + /// The shadow copy is not automatically deleted when the shadow copy requester process ends. The shadow copy + /// can be deleted only by a call to + /// IVssBackupComponents::DeleteSnapshots + /// . + /// This attribute is automatically set for + /// _VSS_SNAPSHOT_CONTEXT + /// contexts of + /// VSS_CTX_APP_ROLLBACK + /// , + /// VSS_CTX_CLIENT_ACCESSIBLE + /// , + /// VSS_CTX_CLIENT_ACCESSIBLE_WRITERS + /// , and + /// VSS_CTX_NAS_ROLLBACK + /// . + /// This attribute should not be used explicitly by requesters when setting the context of a shadow copy. + /// + VSS_VOLSNAP_ATTR_NO_AUTO_RELEASE = 0x08, + + /// + /// No writers are involved in creating the shadow copy. + /// This attribute is automatically set for + /// _VSS_SNAPSHOT_CONTEXT + /// contexts of + /// VSS_CTX_NAS_ROLLBACK + /// , + /// VSS_CTX_FILE_SHARE_BACKUP + /// , and + /// VSS_CTX_CLIENT_ACCESSIBLE + /// . + /// This attribute should not be used explicitly by requesters when setting the context of a shadow copy. + /// + VSS_VOLSNAP_ATTR_NO_WRITERS = 0x10, + + /// + /// The shadow copy is to be transported and therefore should not be surfaced locally. + /// This attribute can be used explicitly by requesters when setting the context of a shadow copy, if the + /// provider for shadow copy supports transportable shadow copies. + /// Windows Server 2003, Standard Edition, Windows Server 2003, Web Edition and Windows XP: + /// This attribute is not supported. All editions of Windows Server 2003 with SP1 support this attribute. + /// See + /// Importing Transportable Shadow Copied Volumes + /// for more information. + /// + VSS_VOLSNAP_ATTR_TRANSPORTABLE = 0x20, + + /// + /// The shadow copy is not currently exposed. + /// Unless the shadow copy is explicitly exposed or mounted, this attribute is set for all shadow copies. + /// This attribute should not be used explicitly by requesters when setting the context of a shadow copy. + /// + VSS_VOLSNAP_ATTR_NOT_SURFACED = 0x40, + + /// + /// The shadow copy is not transacted. + /// + /// A requester can modify a shadow copy context with a bitwise OR of this attribute. By doing this, the requester instructs VSS to + /// disable built-in integration between VSS and transaction and resource managers. + /// + /// + /// Setting this attribute guarantees that the requester will not receive VSS_E_TRANSACTION_FREEZE_TIMEOUT errors. However, it may + /// cause unwanted consequences, such as the loss of transactional integrity or even data loss. + /// + /// Windows Server 2003 and Windows XP: + /// This value is not supported until Windows Vista. + /// + VSS_VOLSNAP_ATTR_NOT_TRANSACTED = 0x80, + + /// + /// Indicates that a given provider is a hardware provider. + /// This attribute is automatically set for hardware providers. + /// This enumeration value cannot be used to manually set the context (using the + /// IVssBackupComponents::SetContext + /// method) of a shadow copy by a bit mask (or bitwise OR) of this enumeration value and a valid shadow copy + /// context value from + /// _VSS_SNAPSHOT_CONTEXT + /// . + /// + VSS_VOLSNAP_ATTR_HARDWARE_ASSISTED = 0x10000, + + /// + /// Indicates that a given provider uses differential data or a copy-on-write mechanism to implement shadow copies. + /// A requester can modify a shadow copy context with a bitwise OR of this attribute. By doing this, the + /// requester instructs providers to create a shadow copy using a differential implementation. If no shadow copy + /// provider installed on the system supports the requested attributes, a VSS_E_VOLUME_NOT_SUPPORTED error will be + /// returned to + /// IVssBackupComponents::AddToSnapshotSet + /// . + /// + VSS_VOLSNAP_ATTR_DIFFERENTIAL = 0x20000, + + /// + /// Indicates that a given provider uses a PLEX or mirrored split mechanism to implement shadow copies. + /// A requester can modify a shadow copy context with a bitwise OR of this attribute. By doing this, the + /// requester instructs the providers to create a shadow copy using a PLEX implementation. If no shadow copy + /// provider installed on the system supports the requested attributes, a VSS_E_VOLUME_NOT_SUPPORTED error will be + /// returned to + /// IVssBackupComponents::AddToSnapshotSet + /// . + /// + VSS_VOLSNAP_ATTR_PLEX = 0x40000, + + /// + /// The shadow copy of the volume was imported onto this machine using the + /// IVssBackupComponents::ImportSnapshots + /// method rather than created using the + /// IVssBackupComponents::DoSnapshotSet + /// method. + /// This attribute is automatically set if a shadow copy is imported. + /// This attribute should not be used explicitly by requesters when setting the context of a shadow copy. + /// + VSS_VOLSNAP_ATTR_IMPORTED = 0x80000, + + /// + /// The shadow copy is locally exposed. If this bit flag and the VSS_VOLSNAP_ATTR_EXPOSED_REMOTELY bit flag are + /// not set, the shadow copy is hidden. + /// The attribute is automatically added to a shadow copy context upon calling the + /// IVssBackupComponents::ExposeSnapshot + /// method to expose a shadow copy locally. + /// This attribute should not be used explicitly by requesters when setting the context of a shadow copy. + /// + VSS_VOLSNAP_ATTR_EXPOSED_LOCALLY = 0x100000, + + /// + /// The shadow copy is remotely exposed. If this bit flag and the VSS_VOLSNAP_ATTR_EXPOSED_LOCALLY bit flag are + /// not set, the shadow copy is hidden. + /// The attribute is automatically added to a shadow copy context upon calling the + /// IVssBackupComponents::ExposeSnapshot + /// method to expose a shadow copy locally. + /// This attribute should not be used explicitly by requesters when setting the context of a shadow copy. + /// + VSS_VOLSNAP_ATTR_EXPOSED_REMOTELY = 0x200000, + + /// + /// Indicates that the writer will need to + /// auto-recover + /// the component in + /// CVssWriter::OnPostSnapshot + /// . + /// This attribute should not be used explicitly by requesters when setting the context of a shadow copy. + /// + VSS_VOLSNAP_ATTR_AUTORECOVER = 0x400000, + + /// + /// Indicates that the writer will need to + /// auto-recover + /// the component in + /// CVssWriter::OnPostSnapshot + /// if the shadow copy is being used for rollback (for data mining, for example). + /// + /// A requester would set this flag in the shadow copy context to indicate that the shadow copy is being created for a non-backup + /// purpose such as data mining. /// /// - /// - /// - /// VSS_APPLICATION_LEVEL is provided to allow application developers to control at what point a writer will receive a Freeze - /// event. This may be important if one writer uses or depends on another writer. - /// - /// - /// For instance, if an application X is storing data using application Y as an intermediate layer (for example, if Y implements a - /// database used by X), we would describe X as a front-end application, and Y as a back-end application. - /// - /// - /// In this example, when freezing applications that participate in a shadow copy, you would want X (the front-end application) to - /// suspend its writes to the database prior to freezing Y (the back-end application), the database service itself. - /// - /// The application level of a writer is set by CVssWriter::Initialize and retrieved by CVssWriter::GetCurrentLevel. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vss/ne-vss-vss_application_level typedef enum _VSS_APPLICATION_LEVEL { - // VSS_APP_UNKNOWN, VSS_APP_SYSTEM, VSS_APP_BACK_END, VSS_APP_FRONT_END, VSS_APP_SYSTEM_RM, VSS_APP_AUTO } VSS_APPLICATION_LEVEL, *PVSS_APPLICATION_LEVEL; - [PInvokeData("vss.h", MSDNShortId = "NE:vss._VSS_APPLICATION_LEVEL")] - public enum VSS_APPLICATION_LEVEL - { - /// - /// The level at which this writer's freeze state will occur is not known. This indicates an application - /// error. - /// - VSS_APP_UNKNOWN, - - /// This writer freeze state will occur at the system application level. - VSS_APP_SYSTEM, - - /// This writer freeze state will occur at the back-end application level. - VSS_APP_BACK_END, - - /// This writer freeze state will occur at the front-end application level. - VSS_APP_FRONT_END, - - /// - VSS_APP_SYSTEM_RM, - - /// - /// This writer freeze state will be determined automatically. This enumeration value is reserved for future - /// use. - /// - VSS_APP_AUTO = -1, - } + VSS_VOLSNAP_ATTR_ROLLBACK_RECOVERY = 0x800000, /// - /// The VSS_BACKUP_SCHEMA enumeration is used by a writer to indicate the types of backup operations it can participate in. - /// The supported kinds of backup are expressed as a bit mask (or bitwise OR) of VSS_BACKUP_SCHEMA values. + /// Reserved for system use. + /// Windows Vista, Windows Server 2003 and Windows XP: + /// This value is not supported until Windows Server 2008. /// - /// - /// Writer set their backup schemas with calls to IVssCreateWriterMetadata::SetBackupSchema. - /// Requesters use IVssExamineWriterMetadata::GetBackupSchema to determine the backup schema that a writer supports. - /// - /// For a specific kind of backup operation to be supported, the writer must support the corresponding schema, and the requester - /// must set the corresponding backup type. - /// - /// - /// For example, to involve a writer in an incremental backup operation, the requester must set the backup type to - /// VSS_BT_INCREMENTAL, and the writer should have a backup schema that includes VSS_BS_INCREMENTAL. - /// - /// - /// A writer that does not support the backup schema corresponding to a requester's backup type should treat the backup operation - /// that is being performed as if it were a default (full) backup. If the desired backup type is not supported by the writer's - /// backup schema, the requester can either perform a full backup for this writer or exclude the writer from the backup operation. A - /// requester can exclude a writer by selecting none of the writer's components (see Working with Selectability and Logical Paths), - /// or by disabling the writer (see IVssBackupComponents::DisableWriterClasses or IVssBackupComponents::DisableWriterInstances). - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vss/ne-vss-vss_backup_schema typedef enum _VSS_BACKUP_SCHEMA { - // VSS_BS_UNDEFINED, VSS_BS_DIFFERENTIAL, VSS_BS_INCREMENTAL, VSS_BS_EXCLUSIVE_INCREMENTAL_DIFFERENTIAL, VSS_BS_LOG, VSS_BS_COPY, - // VSS_BS_TIMESTAMPED, VSS_BS_LAST_MODIFY, VSS_BS_LSN, VSS_BS_WRITER_SUPPORTS_NEW_TARGET, VSS_BS_WRITER_SUPPORTS_RESTORE_WITH_MOVE, - // VSS_BS_INDEPENDENT_SYSTEM_STATE, VSS_BS_ROLLFORWARD_RESTORE, VSS_BS_RESTORE_RENAME, VSS_BS_AUTHORITATIVE_RESTORE, - // VSS_BS_WRITER_SUPPORTS_PARALLEL_RESTORES } VSS_BACKUP_SCHEMA, *PVSS_BACKUP_SCHEMA; - [PInvokeData("vss.h", MSDNShortId = "NE:vss._VSS_BACKUP_SCHEMA")] - [Flags] - public enum VSS_BACKUP_SCHEMA - { - /// - /// The writer supports a simple full backup and restoration of entire files (as defined by a - /// VSS_BACKUP_TYPE - /// value of - /// VSS_BT_FULL - /// ). This backup scheme can be used as the basis of an incremental or - /// differential backup. This is the default value. - /// - VSS_BS_UNDEFINED = 0, - - /// - /// The writer supports differential backups (corresponding to the - /// VSS_BACKUP_TYPE - /// value - /// VSS_BT_DIFFERENTIAL - /// ). Files created or changed since the last full backup are saved. - /// Files are not marked as having been backed up. - /// This setting does not preclude mixing of incremental and differential backups. - /// This value is not supported for express writers. - /// - VSS_BS_DIFFERENTIAL = 0x0001, - - /// - /// The writer supports incremental backups (corresponding to the - /// VSS_BACKUP_TYPE - /// value - /// VSS_BT_INCREMENTAL - /// ). Files created or changed since the last full or incremental - /// backup are saved. Files are marked as having been backed up. - /// This setting does not preclude mixing of incremental and differential backups. - /// This value is not supported for express writers. - /// - VSS_BS_INCREMENTAL = 0x0002, - - /// - /// The writer supports both differential and incremental backup schemas, but only exclusively: for example, - /// you cannot follow a differential backup with an incremental one. A writer cannot support this schema if it does - /// not support both incremental and differential schemas ( - /// VSS_BS_DIFFERENTIAL - /// - VSS_BS_EXCLUSIVE_INCREMENTAL_DIFFERENTIAL = 0x0004, - - /// - /// The writer supports backups that involve only the log files it manages (corresponding to a - /// VSS_BACKUP_TYPE - /// value of - /// VSS_BT_LOG - /// ). This schema requires a writer to have added at least one file to at - /// least one component using the - /// IVssCreateWriterMetadata::AddDataBaseLogFiles - /// method. Requesters retrieve log file information using the - /// IVssWMComponent::GetDatabaseLogFile - /// method. - /// - VSS_BS_LOG = 0x0008, - - /// - /// Similar to the default backup schema ( - /// VSS_BT_UNDEFINED - /// ), the writer supports - /// copy backup operations (corresponding to - /// VSS_BT_COPY - /// ) where file access information - /// (such as information as to when a file was last backed up) will not be updated either in the writer's own state - /// information or in the file system information. This type of backup cannot be used as the basis of an incremental - /// or differential backup. - /// - VSS_BS_COPY = 0x0010, - - /// - /// A writer supports using the VSS time-stamp mechanism when evaluating if a file should be included in - /// differential or incremental operations (corresponding to - /// VSS_BT_DIFFERENTIAL - /// and - /// VSS_BT_INCREMENTAL - /// , respectively) using the - /// IVssComponent::GetBackupStamp - /// , - /// IVssComponent::GetPreviousBackupStamp - /// , - /// IVssComponent::SetBackupStamp - /// , and - /// IVssBackupComponents::SetPreviousBackupStamp - /// methods. - /// A writer cannot support this schema if it does not support either differential or incremental backup schemas - /// ( - /// VSS_BS_DIFFERENTIAL - /// or - /// VSS_BS_INCREMENTAL - /// ). - /// This value is not supported for express writers. - /// - VSS_BS_TIMESTAMPED = 0x0020, - - /// - /// When implementing incremental or differential backups with differenced files, a writer can provide last - /// modification time information for files (using - /// IVssComponent::AddDifferencedFilesByLastModifyTime - /// ). - /// A requester then can use - /// IVssComponent::GetDifferencedFile - /// to - /// obtain candidate files and information about their last modification data. The requester can use this - /// information (along with any records about previous backup operations it maintains) to decide if a file should be - /// included in incremental and differential backups. - /// This scheme does not apply to partial file implementations of incremental and differential backup - /// operations. - /// A writer cannot support this schema if it does not support either incremental or differential backup schemas - /// ( - /// VSS_BS_DIFFERENTIAL - /// or - /// VSS_BS_INCREMENTAL - /// ). - /// This value is not supported for express writers. - /// - VSS_BS_LAST_MODIFY = 0x0040, - - /// Reserved for system use. - VSS_BS_LSN = 0x0080, - - /// - /// The writer supports a requester changing the target for file restoration using - /// IVssBackupComponents::AddNewTarget - /// . - /// (See - /// Non-Default Backup And Restore Locations - /// for more information.) - /// This value is not supported for express writers. - /// - VSS_BS_WRITER_SUPPORTS_NEW_TARGET = 0x0100, - - /// - /// - /// The writer supports running multiple writer instances with the same class ID, and it supports a requester moving a component - /// to a different writer instance at restore time using - /// - /// IVssBackupComponentsEx::SetSelectedForRestoreEx - /// . - /// This value is not supported for express writers. - /// Windows Server 2003: - /// This value is not supported until Windows Server 2003 with SP1. - /// - VSS_BS_WRITER_SUPPORTS_RESTORE_WITH_MOVE = 0x0200, - - /// - /// - /// The writer supports backing up data that is part of the system state, but that can also be backed up independently of the - /// system state. - /// - /// Windows Server 2003: - /// This value is not supported until Windows Vista. - /// - VSS_BS_INDEPENDENT_SYSTEM_STATE = 0x0400, - - /// - /// The writer supports a requester setting a roll-forward restore point using - /// IVssBackupComponentsEx2::SetRollForward - /// . - /// This value is not supported for express writers. - /// Windows Server 2003: - /// This value is not supported until Windows Vista. - /// - VSS_BS_ROLLFORWARD_RESTORE = 0x1000, - - /// - /// The writer supports a requester setting a restore name using - /// IVssBackupComponentsEx2::SetRestoreName - /// . - /// This value is not supported for express writers. - /// Windows Server 2003: - /// This value is not supported until Windows Vista. - /// - VSS_BS_RESTORE_RENAME = 0x2000, - - /// - /// The writer supports a requester setting authoritative restore using - /// IVssBackupComponentsEx2::SetAuthoritativeRestore - /// . - /// This value is not supported for express writers. - /// Windows Server 2003: - /// This value is not supported until Windows Vista. - /// - VSS_BS_AUTHORITATIVE_RESTORE = 0x4000, - - /// - /// The writer supports multiple unsynchronized restore events. - /// This value is not supported for express writers. - /// Windows Vista and Windows Server 2003: - /// This value is not supported until Windows Server 2008. - /// - VSS_BS_WRITER_SUPPORTS_PARALLEL_RESTORES = 0x8000, - } - - /// The VSS_BACKUP_TYPE enumeration indicates the type of backup to be performed using VSS writer/requester coordination. - /// - /// An implementation of a backup type defined by a VSS_BACKUP_TYPE value must be done using the VSS API. - /// - /// This is particularly true in the case of incremental ( VSS_BT_INCREMENTAL) and differential ( VSS_BT_DIFFERENTIAL) - /// backups. In these cases, requesters and writers work together using the file backup specification masks - /// (VSS_FILE_SPEC_BACKUP_TYPE), and designations of files as being part of partial and differenced file operations to select which - /// files must be backed up. - /// - /// - /// A requester may also use other more traditional techniques to implement an incremental or differential restore, but it must not - /// override the information provided through the VSS interfaces. - /// - /// - /// If a requester, when processing a given backup type, encounters a writer that does not support that backup type, the requester - /// performs backup or restore operations for that particular writer's data as if the backup type was VSS_BT_FULL. - /// - /// Requesters set the backup type with a call to IVssBackupComponents::SetBackupState. - /// Writers use CVssWriter::GetBackupType to determine the backup type. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vss/ne-vss-vss_backup_type typedef enum _VSS_BACKUP_TYPE { VSS_BT_UNDEFINED, - // VSS_BT_FULL, VSS_BT_INCREMENTAL, VSS_BT_DIFFERENTIAL, VSS_BT_LOG, VSS_BT_COPY, VSS_BT_OTHER } VSS_BACKUP_TYPE, *PVSS_BACKUP_TYPE; - [PInvokeData("vss.h", MSDNShortId = "NE:vss._VSS_BACKUP_TYPE")] - public enum VSS_BACKUP_TYPE - { - /// - /// The backup type is not known. - /// This value indicates an application error. - /// - VSS_BT_UNDEFINED = 0, - - /// - /// Full backup: all files, regardless of whether they have been marked as backed up or not, are saved. This is - /// the default backup type and schema, and all writers support it. - /// Each file's backup history will be updated to reflect that it was backed up. - /// - VSS_BT_FULL, - - /// - /// Incremental backup: files created or changed since the last full or incremental backup are saved. Files are - /// marked as having been backed up. - /// A requester can implement this sort of backup on a particular writer only if it supports the - /// VSS_BS_INCREMENTAL - /// schema. - /// If a requester's backup type is - /// VSS_BT_INCREMENTAL - /// and a particular writer's - /// backup schema does not support that sort of backup, the requester will always perform a full - /// ( - /// VSS_BT_FULL - /// ) backup on that writer's data. - /// - VSS_BT_INCREMENTAL, - - /// - /// Differential backup: files created or changed since the last full backup are saved. Files are not marked as - /// having been backed up. - /// A requester can implement this sort of backup on a particular writer only if it supports the - /// VSS_BS_DIFFERENTIAL - /// schema. - /// If a requester's backup type is - /// VSS_BT_DIFFERENTIAL - /// and a particular writer's - /// backup schema does not support that sort of backup, the requester will always perform a full - /// ( - /// VSS_BT_FULL - /// ) backup on that writer's data. - /// - VSS_BT_DIFFERENTIAL, - - /// - /// The log file of a writer is to participate in backup or restore operations. - /// A requester can implement this sort of backup on a particular writer only if it supports the - /// VSS_BS_LOG - /// schema. - /// If a requester's backup type is - /// VSS_BT_LOG - /// and a particular writer's backup - /// schema does not support that sort of backup, the requester will always perform a full - /// ( - /// VSS_BT_FULL - /// ) backup on that writer's data. - /// - VSS_BT_LOG, - - /// - /// Files on disk will be copied to a backup medium regardless of the state of each file's backup history, and - /// the backup history will not be updated. - /// A requester can implement this sort of backup on a particular writer only if it supports the - /// VSS_BS_COPY - /// schema. - /// If a requester's backup type is - /// VSS_BT_COPY - /// and a particular writer's backup - /// schema does not support that sort of backup, the requester will always perform a full - /// ( - /// VSS_BT_FULL - /// ) backup on that writer's data. - /// - VSS_BT_COPY, - - /// Backup type that is not full, copy, log, incremental, or differential. - VSS_BT_OTHER, - } + VSS_VOLSNAP_ATTR_DELAYED_POSTSNAPSHOT = 0x1000000, /// - /// - /// The VSS_FILE_SPEC_BACKUP_TYPE enumeration is used by writers to indicate their support of certain backup operations—such - /// as incremental or differential backup—on the basis of file sets (a specified file or files). - /// - /// - /// File sets stored in the Writer Metadata Document are tagged with a bit mask (or bitwise OR) of VSS_FILE_SPEC_BACKUP_TYPE - /// values indicating the following: - /// - /// + /// Indicates that TxF recovery should be enforced during shadow copy creation. + /// Windows Vista, Windows Server 2003 and Windows XP: + /// This value is not supported until Windows Server 2008. + /// + VSS_VOLSNAP_ATTR_TXF_RECOVERY = 0x2000000, + + /// + VSS_VOLSNAP_ATTR_FILE_SHARE = 0x4000000, + } + + /// The VSS_WRITER_STATE enumeration indicates the current state of the writer. + /// A requester determines the state of a writer through IVssBackupComponents::GetWriterStatus. + // https://docs.microsoft.com/en-us/windows/win32/api/vss/ne-vss-vss_writer_state typedef enum _VSS_WRITER_STATE { VSS_WS_UNKNOWN, + // VSS_WS_STABLE, VSS_WS_WAITING_FOR_FREEZE, VSS_WS_WAITING_FOR_THAW, VSS_WS_WAITING_FOR_POST_SNAPSHOT, + // VSS_WS_WAITING_FOR_BACKUP_COMPLETE, VSS_WS_FAILED_AT_IDENTIFY, VSS_WS_FAILED_AT_PREPARE_BACKUP, VSS_WS_FAILED_AT_PREPARE_SNAPSHOT, + // VSS_WS_FAILED_AT_FREEZE, VSS_WS_FAILED_AT_THAW, VSS_WS_FAILED_AT_POST_SNAPSHOT, VSS_WS_FAILED_AT_BACKUP_COMPLETE, + // VSS_WS_FAILED_AT_PRE_RESTORE, VSS_WS_FAILED_AT_POST_RESTORE, VSS_WS_FAILED_AT_BACKUPSHUTDOWN, VSS_WS_COUNT } VSS_WRITER_STATE, *PVSS_WRITER_STATE; + [PInvokeData("vss.h", MSDNShortId = "NE:vss._VSS_WRITER_STATE")] + public enum VSS_WRITER_STATE + { + /// + /// The writer's state is not known. + /// This indicates an error on the part of the writer. + /// + VSS_WS_UNKNOWN = 0, + + /// + /// The writer has completed processing current shadow copy events and is ready to proceed, or + /// CVssWriter::OnPrepareSnapshot + /// has not yet + /// been called. + /// + VSS_WS_STABLE, + + /// The writer is waiting for the freeze state. + VSS_WS_WAITING_FOR_FREEZE, + + /// The writer is waiting for the thaw state. + VSS_WS_WAITING_FOR_THAW, + + /// + /// The writer is waiting for the + /// PostSnapshot + /// state. + /// + VSS_WS_WAITING_FOR_POST_SNAPSHOT, + + /// The writer is waiting for the requester to finish its backup operation. + VSS_WS_WAITING_FOR_BACKUP_COMPLETE, + + /// The writer vetoed the shadow copy creation process at the writer identification state. + VSS_WS_FAILED_AT_IDENTIFY, + + /// The writer vetoed the shadow copy creation process during the backup preparation state. + VSS_WS_FAILED_AT_PREPARE_BACKUP, + + /// + /// The writer vetoed the shadow copy creation process during the + /// PrepareForSnapshot + /// state. + /// + VSS_WS_FAILED_AT_PREPARE_SNAPSHOT, + + /// The writer vetoed the shadow copy creation process during the freeze state. + VSS_WS_FAILED_AT_FREEZE, + + /// The writer vetoed the shadow copy creation process during the thaw state. + VSS_WS_FAILED_AT_THAW, + + /// + /// The writer vetoed the shadow copy creation process during the + /// PostSnapshot + /// state. + /// + VSS_WS_FAILED_AT_POST_SNAPSHOT, + + /// + /// The shadow copy has been created and the writer failed during the + /// BackupComplete + /// state. A writer + /// should save information about this failure to the error log. For additional information on logging, see + /// Event and Error Handling Under VSS + /// . + /// + VSS_WS_FAILED_AT_BACKUP_COMPLETE, + + /// + /// The writer failed during the + /// PreRestore + /// state. + /// + VSS_WS_FAILED_AT_PRE_RESTORE, + + /// + /// The writer failed during the + /// PostRestore + /// state. + /// + VSS_WS_FAILED_AT_POST_RESTORE, + + /// The writer failed during the shutdown of the backup application. + VSS_WS_FAILED_AT_BACKUPSHUTDOWN, + + /// Reserved value. + VSS_WS_COUNT, + } + + /// + /// + /// The IVssAsync interface is returned to calling applications by methods that initiate asynchronous operations, which run in + /// the background and typically require a long time to complete. + /// + /// + /// The IVssAsync interface permits an application to monitor and control an asynchronous operation by waiting on its completion, + /// querying its status, or canceling it. + /// + /// + /// The calling application is responsible for calling IUnknown::Release to release the resources held by the returned IVssAsync + /// interface when it is no longer needed. + /// + /// The following methods return an IVssAsync interface: + /// + /// + /// IVssBackupComponents::BackupComplete + /// + /// + /// IVssBackupComponents::DoSnapshotSet + /// + /// + /// IVssBackupComponents::GatherWriterMetadata + /// + /// + /// IVssBackupComponents::GatherWriterStatus + /// + /// + /// IVssBackupComponents::ImportSnapshots + /// + /// + /// IVssBackupComponents::PostRestore + /// + /// + /// IVssBackupComponents::PrepareForBackup + /// + /// + /// IVssBackupComponents::PreRestore + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vss/nn-vss-ivssasync + [PInvokeData("vss.h", MSDNShortId = "NN:vss.IVssAsync")] + [ComImport, Guid("507C37B4-CF5B-4e95-B0AF-14EB9767467E"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IVssAsync + { + /// The Cancel method cancels an incomplete asynchronous operation. + /// + /// All calls to Cancel for all IVssAsync objects support the following status codes. + /// + /// + /// Value + /// Meaning + /// /// + /// S_OK + /// The asynchronous operation had been successfully canceled. + /// + /// + /// VSS_S_ASYNC_CANCELLED + /// The asynchronous operation had been canceled prior to calling this method. + /// + /// + /// VSS_S_ASYNC_FINISHED + /// The asynchronous operation had completed prior to calling this method. + /// + /// + /// VSS_E_UNEXPECTED /// - /// Whether the writer and the requester have to evaluate a given file set for participation in the specified type of backup operations + /// 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. /// /// + /// + /// + /// If an operation has completed unsuccessfully before Cancel was called, then Cancel returns the error that + /// operation encountered. + /// + /// + /// To obtain a complete list of return values for a specific IVssAsync::Cancel, see the error codes of the method that + /// returned the IVssAsync object. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vss/nf-vss-ivssasync-cancel HRESULT Cancel(); + [PreserveSig] + HRESULT Cancel(); + + /// The Wait method waits until an incomplete asynchronous operation finishes. + /// + /// Length of time, in milliseconds, that the method will wait for an asynchronous process to return before timing out. + /// The default value for this argument is INFINITE. + /// + /// Windows Server 2003: This parameter is reserved and must be INFINITE. If any other value is specified for this parameter, + /// the call to Wait fails with E_INVALIDARG. + /// + /// Windows XP: This method has no parameters. + /// + /// + /// All calls to Wait for all IVssAsync objects support the following status codes. + /// + /// + /// Value + /// Meaning + /// /// - /// Whether backing up the specified file will require a shadow copy + /// S_OK + /// The wait operation was successful. Call IVssAsync::QueryStatus to determine the final status of the asynchronous operation. + /// + /// + /// E_ACCESSDENIED + /// The wait operation failed because the user did not have the correct privileges. + /// + /// + /// 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. + /// /// /// - /// - /// + /// If an operation fails while being waited on, Wait returns the error that operation encountered. /// - /// When a writer sets a backup-required value of the VSS_FILE_SPEC_BACKUP_TYPE enumeration, it is indicating that the - /// requester perform the backup in such a way that, when the backup is restored, the current version of the file set is restored. - /// Typically, this means that the file set is copied as part of the backup. + /// To obtain a complete list of return values for a specific Wait, see the error codes of the method that returned the + /// IVssAsync object. /// - /// - /// This setting can be overridden if a file is added to the Backup Components Document as a differenced file (using - /// IVssComponent::AddDifferencedFilesByLastModifyTime) or as a partial file (using IVssComponent::AddPartialFile). - /// - /// - /// If a file is added as a differenced file, the writer establishes criteria by which the requester should decide whether or not to - /// actually copy a file to a backup medium. A writer typically adds differenced files to the Backup Components Document for - /// inclusion in a backup PostSnapshot event (see CVssWriter::OnPostSnapshot). See Incremental and Differential Backups for details. - /// - /// - /// When a writer sets a shadow copy-required value of the VSS_FILE_SPEC_BACKUP_TYPE enumeration, it indicates that the file - /// set should be backed up from a shadow-copied volume. File sets not tagged with a shadow copy-required value can be backed up - /// from the original volume. - /// - /// Writers set VSS_FILE_SPEC_BACKUP_TYPE values while handling an Identify event (see CVssWriter::OnIdentify). - /// - /// A bit mask (or bitwise OR) of VSS_FILE_SPEC_BACKUP_TYPE values can be applied to a file set when adding it to a component - /// using the IVssCreateWriterMetadata::AddFilesToFileGroup, IVssCreateWriterMetadata::AddDatabaseFiles, or - /// IVssCreateWriterMetadata::AddDatabaseLogFiles method. - /// - /// - /// If no explicit file specification backup type is supplied during the addition of a file specification to a component, the - /// specification is tagged with the default VSS_FILE_SPEC_BACKUP_TYPE value: (VSS_FSBT_ALL_BACKUP_REQUIRED | VSS_FSBT_ALL_SNAPSHOT_REQUIRED). - /// - /// - /// Requesters or writers can recover a file set's file specification backup type by using the IVssWMFiledesc::GetBackupTypeMask method. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vss/ne-vss-vss_file_spec_backup_type typedef enum _VSS_FILE_SPEC_BACKUP_TYPE { - // VSS_FSBT_FULL_BACKUP_REQUIRED, VSS_FSBT_DIFFERENTIAL_BACKUP_REQUIRED, VSS_FSBT_INCREMENTAL_BACKUP_REQUIRED, - // VSS_FSBT_LOG_BACKUP_REQUIRED, VSS_FSBT_FULL_SNAPSHOT_REQUIRED, VSS_FSBT_DIFFERENTIAL_SNAPSHOT_REQUIRED, - // VSS_FSBT_INCREMENTAL_SNAPSHOT_REQUIRED, VSS_FSBT_LOG_SNAPSHOT_REQUIRED, VSS_FSBT_CREATED_DURING_BACKUP, - // VSS_FSBT_ALL_BACKUP_REQUIRED, VSS_FSBT_ALL_SNAPSHOT_REQUIRED } VSS_FILE_SPEC_BACKUP_TYPE, *PVSS_FILE_SPEC_BACKUP_TYPE; - [PInvokeData("vss.h", MSDNShortId = "NE:vss._VSS_FILE_SPEC_BACKUP_TYPE")] - [Flags] - public enum VSS_FILE_SPEC_BACKUP_TYPE - { - /// - /// A file set tagged with this value must be involved in all types of backup operations. - /// A writer tags a file set with this value to indicate to the requester that it expects a copy of the current - /// version of the file set to be available following the restore of any backup operation with a - /// VSS_BACKUP_TYPE - /// of - /// VSS_BT_FULL - /// . - /// - VSS_FSBT_FULL_BACKUP_REQUIRED = 0x001, - - /// - /// A writer tags a file set with this value to indicate to the requester that it expects a copy of the current - /// version of the file set to be available following the restore of any backup operation with a - /// VSS_BACKUP_TYPE - /// of - /// VSS_BT_DIFFERENTIAL - /// . - /// This value is not supported for express writers. - /// - VSS_FSBT_DIFFERENTIAL_BACKUP_REQUIRED = 0x002, - - /// - /// A writer tags a file set with this value to indicate to the requester that it expects a copy of the current - /// version of the file set to be available following the restore of any backup operation with a - /// VSS_BACKUP_TYPE - /// of - /// VSS_BT_INCREMENTAL - /// . - /// This value is not supported for express writers. - /// - VSS_FSBT_INCREMENTAL_BACKUP_REQUIRED = 0x004, - - /// - /// A writer tags a file set with this value to indicate to the requester that it expects a copy of the current - /// version of the file set to be available following the restore of any backup operation with a - /// VSS_BACKUP_TYPE - /// of - /// VSS_BT_LOG - /// . - /// This value is not supported for express writers. - /// - VSS_FSBT_LOG_BACKUP_REQUIRED = 0x008, - - /// - /// A file set tagged with this value must be backed up from a shadow copy of a volume (and never from the - /// original volume) when participating in a backup operation with a - /// VSS_BACKUP_TYPE - /// of - /// VSS_BT_FULL - /// . - /// - VSS_FSBT_FULL_SNAPSHOT_REQUIRED = 0x100, - - /// - /// A file set tagged with this value must be backed up from a shadow copy of a volume (and never from the - /// original volume) when participating in a backup operation with a - /// VSS_BACKUP_TYPE - /// of - /// VSS_BT_DIFFERENTIAL - /// . - /// - VSS_FSBT_DIFFERENTIAL_SNAPSHOT_REQUIRED = 0x200, - - /// - /// A file set tagged with this value must be backed up from a shadow copy of a volume (and never from the - /// original volume) when participating in a backup operation with a - /// VSS_BACKUP_TYPE - /// of - /// VSS_BT_INCREMENTAL - /// . - /// - VSS_FSBT_INCREMENTAL_SNAPSHOT_REQUIRED = 0x400, - - /// - /// A file set tagged with this value must be backed up from a shadow copy of a volume (and never from the - /// original volume) when participating in a backup operation with a - /// VSS_BACKUP_TYPE - /// of - /// VSS_BT_LOG - /// ). - /// - VSS_FSBT_LOG_SNAPSHOT_REQUIRED = 0x800, - - /// - /// A writer tags a file set with this value to indicate to the requester that they expect the file to be created during the - /// snapshot sequence. - /// - VSS_FSBT_CREATED_DURING_BACKUP = 0x10000, - - /// - /// The default file backup specification type. A file set tagged with this value must always participate in - /// backup and restore operations. - /// - VSS_FSBT_ALL_BACKUP_REQUIRED = 0xF, - - /// - /// The shadow copy requirement for backup. A file set tagged with this value must always be backed up from a - /// shadow copy of a volume (and never from the original volume) when participating in a backup operation. - /// - VSS_FSBT_ALL_SNAPSHOT_REQUIRED = 0xF00, - } - - /// Defines shadow copy LUN flags. - // https://docs.microsoft.com/en-us/windows/win32/api/vss/ne-vss-vss_hardware_options typedef enum _VSS_HARDWARE_OPTIONS { - // VSS_BREAKEX_FLAG_MASK_LUNS, VSS_BREAKEX_FLAG_MAKE_READ_WRITE, VSS_BREAKEX_FLAG_REVERT_IDENTITY_ALL, - // VSS_BREAKEX_FLAG_REVERT_IDENTITY_NONE, VSS_ONLUNSTATECHANGE_NOTIFY_READ_WRITE, VSS_ONLUNSTATECHANGE_NOTIFY_LUN_PRE_RECOVERY, - // VSS_ONLUNSTATECHANGE_NOTIFY_LUN_POST_RECOVERY, VSS_ONLUNSTATECHANGE_DO_MASK_LUNS } VSS_HARDWARE_OPTIONS, *PVSS_HARDWARE_OPTIONS; - [PInvokeData("vss.h", MSDNShortId = "NE:vss._VSS_HARDWARE_OPTIONS")] - [Flags] - public enum VSS_HARDWARE_OPTIONS - { - /// The shadow copy LUN will be masked from the host. - VSS_BREAKEX_FLAG_MASK_LUNS = 0x001, - - /// The shadow copy LUN will be exposed to the host as a read-write volume. - VSS_BREAKEX_FLAG_MAKE_READ_WRITE = 0x002, - - /// - /// The disk identifiers of all of the shadow copy LUNs will be reverted to that of the original LUNs. However, if any of the - /// original LUNs are present on the system, the operation will fail and none of the identifiers will be reverted. - /// - VSS_BREAKEX_FLAG_REVERT_IDENTITY_ALL = 0x004, - - /// None of the disk identifiers of the shadow copy LUNs will be reverted. - VSS_BREAKEX_FLAG_REVERT_IDENTITY_NONE = 0x008, - - /// - /// - /// The shadow copy LUNs will be converted permanently to read-write. This flag is set only as a notification for the provider; - /// no provider action is required. For more information, see the - /// - /// IVssHardwareSnapshotProviderEx::OnLunStateChange - /// method. - /// - VSS_ONLUNSTATECHANGE_NOTIFY_READ_WRITE = 0x100, - - /// - /// - /// The shadow copy LUNs will be converted temporarily to read-write and are about to undergo TxF recovery or VSS auto-recovery. - /// This flag is set only as a notification for the provider; no provider action is required. For more information, see the - /// - /// IVssHardwareSnapshotProviderEx::OnLunStateChange - /// method. - /// - VSS_ONLUNSTATECHANGE_NOTIFY_LUN_PRE_RECOVERY = 0x200, - - /// - /// - /// The shadow copy LUNs have just undergone TxF recovery or VSS auto-recovery and have been converted back to read-only. This - /// flag is set only as a notification for the provider; no provider action is required. For more information, see the - /// - /// IVssHardwareSnapshotProviderEx::OnLunStateChange - /// method. - /// - VSS_ONLUNSTATECHANGE_NOTIFY_LUN_POST_RECOVERY = 0x400, - - /// - /// The provider must mask shadow copy LUNs from this computer. For more information, see the - /// IVssHardwareSnapshotProviderEx::OnLunStateChange - /// method. - /// - VSS_ONLUNSTATECHANGE_DO_MASK_LUNS = 0x800, - } - - /// - /// The VSS_OBJECT_TYPE enumeration is used by requesters to identify an object as a shadow copy set, shadow copy, or provider. - /// - /// - /// - /// VSS_OBJECT_TYPE is used when calling IVssBackupComponents::Query to specify the types of objects about which to obtain - /// information. An input of VSS_OBJECT_NONE will return information about all objects. - /// - /// - /// In addition, VSS_OBJECT_TYPE is used as an input to IVssBackupComponents::DeleteSnapshots. However, - /// DeleteSnapshots accepts only VSS_OBJECT_TYPE values of VSS_OBJECT_SNAPSHOT_SET or VSS_OBJECT_SNAPSHOT. - /// - /// The Type member of VSS_OBJECT_PROP is a member of the VSS_OBJECT_TYPE enumeration. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vss/ne-vss-vss_object_type typedef enum _VSS_OBJECT_TYPE { VSS_OBJECT_UNKNOWN, - // VSS_OBJECT_NONE, VSS_OBJECT_SNAPSHOT_SET, VSS_OBJECT_SNAPSHOT, VSS_OBJECT_PROVIDER, VSS_OBJECT_TYPE_COUNT } VSS_OBJECT_TYPE, *PVSS_OBJECT_TYPE; - [PInvokeData("vss.h", MSDNShortId = "NE:vss._VSS_OBJECT_TYPE")] - public enum VSS_OBJECT_TYPE - { - /// - /// The object type is not known. - /// This indicates an application error. - /// - VSS_OBJECT_UNKNOWN = 0, - - /// - /// The interpretation of this value depends on whether it is used as an input to a VSS method or returned as - /// an output from a VSS method. - /// When used as an input to a VSS method, it indicates that the method is not restricted to any particular - /// object type, but should act on all appropriate objects. In this sense, - /// VSS_OBJECT_NONE - /// can be thought of as a wildcard input. - /// When returned as an output, the object type is not known and means that there has been an application - /// error. - /// - VSS_OBJECT_NONE, - - /// Shadow copy set. - VSS_OBJECT_SNAPSHOT_SET, - - /// Shadow copy. - VSS_OBJECT_SNAPSHOT, - - /// Shadow copy provider. - VSS_OBJECT_PROVIDER, - - /// Reserved value. - VSS_OBJECT_TYPE_COUNT, - } - - /// - /// Not supported. - /// This enumeration is reserved for future use. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vss/ne-vss-vss_provider_capabilities typedef enum _VSS_PROVIDER_CAPABILITIES { - // VSS_PRV_CAPABILITY_LEGACY, VSS_PRV_CAPABILITY_COMPLIANT, VSS_PRV_CAPABILITY_LUN_REPOINT, VSS_PRV_CAPABILITY_LUN_RESYNC, - // VSS_PRV_CAPABILITY_OFFLINE_CREATION, VSS_PRV_CAPABILITY_MULTIPLE_IMPORT, VSS_PRV_CAPABILITY_RECYCLING, VSS_PRV_CAPABILITY_PLEX, - // VSS_PRV_CAPABILITY_DIFFERENTIAL, VSS_PRV_CAPABILITY_CLUSTERED } VSS_PROVIDER_CAPABILITIES, *PVSS_PROVIDER_CAPABILITIES; - [PInvokeData("vss.h", MSDNShortId = "NE:vss._VSS_PROVIDER_CAPABILITIES")] - [Flags] - public enum VSS_PROVIDER_CAPABILITIES - { - /// - VSS_PRV_CAPABILITY_LEGACY = 0x001, - - /// - VSS_PRV_CAPABILITY_COMPLIANT = 0x002, - - /// - VSS_PRV_CAPABILITY_LUN_REPOINT = 0x004, - - /// - VSS_PRV_CAPABILITY_LUN_RESYNC = 0x008, - - /// - VSS_PRV_CAPABILITY_OFFLINE_CREATION = 0x010, - - /// - VSS_PRV_CAPABILITY_MULTIPLE_IMPORT = 0x020, - - /// - VSS_PRV_CAPABILITY_RECYCLING = 0x040, - - /// - VSS_PRV_CAPABILITY_PLEX = 0x080, - - /// - VSS_PRV_CAPABILITY_DIFFERENTIAL = 0x100, - - /// - VSS_PRV_CAPABILITY_CLUSTERED = 0x200, - } - - /// The VSS_PROVIDER_TYPE enumeration specifies the provider type. - // https://docs.microsoft.com/en-us/windows/win32/api/vss/ne-vss-vss_provider_type typedef enum _VSS_PROVIDER_TYPE { - // VSS_PROV_UNKNOWN, VSS_PROV_SYSTEM, VSS_PROV_SOFTWARE, VSS_PROV_HARDWARE, VSS_PROV_FILESHARE } VSS_PROVIDER_TYPE, *PVSS_PROVIDER_TYPE; - [PInvokeData("vss.h", MSDNShortId = "NE:vss._VSS_PROVIDER_TYPE")] - public enum VSS_PROVIDER_TYPE - { - /// - /// The provider type is unknown. - /// This indicates an error in the application or the VSS service, or that no provider is available. - /// - VSS_PROV_UNKNOWN = 0, - - /// The default provider that ships with Windows. - VSS_PROV_SYSTEM, - - /// A software provider. - VSS_PROV_SOFTWARE, - - /// A hardware provider. - VSS_PROV_HARDWARE, - - /// - /// A file share provider. - /// Windows 7, Windows Server 2008 R2, Windows Vista, Windows Server 2008, Windows XP and Windows Server 2003: - /// This enumeration value is not supported until Windows 8 and Windows Server 2012. - /// - VSS_PROV_FILESHARE, - } - - /// Used by a requester to specify how a resynchronization operation is to be performed. - // https://docs.microsoft.com/en-us/windows/win32/api/vss/ne-vss-vss_recovery_options typedef enum _VSS_RECOVERY_OPTIONS { - // VSS_RECOVERY_REVERT_IDENTITY_ALL, VSS_RECOVERY_NO_VOLUME_CHECK } VSS_RECOVERY_OPTIONS, *PVSS_RECOVERY_OPTIONS; - [PInvokeData("vss.h", MSDNShortId = "NE:vss._VSS_RECOVERY_OPTIONS")] - [Flags] - public enum VSS_RECOVERY_OPTIONS - { - /// - /// After the resynchronization operation is complete, the signature of each target LUN should be identical to that of the - /// original LUN that was used to create the shadow copy. - /// - VSS_RECOVERY_REVERT_IDENTITY_ALL = 0x100, - - /// Volume safety checks should not be performed. - VSS_RECOVERY_NO_VOLUME_CHECK = 0x200, - } - - /// - /// The VSS_RESTORE_TYPE enumeration is used by a requester to indicate the type of restore operation it is about to perform. - /// - /// - /// A requester can optionally set the type of a restore operation using IVssBackupComponents::SetRestoreState. - /// A writer can retrieve the type of a restore operation by calling CVssWriter::GetRestoreType. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vss/ne-vss-vss_restore_type typedef enum _VSS_RESTORE_TYPE { - // VSS_RTYPE_UNDEFINED, VSS_RTYPE_BY_COPY, VSS_RTYPE_IMPORT, VSS_RTYPE_OTHER } VSS_RESTORE_TYPE, *PVSS_RESTORE_TYPE; - [PInvokeData("vss.h", MSDNShortId = "NE:vss._VSS_RESTORE_TYPE")] - public enum VSS_RESTORE_TYPE - { - /// - /// No restore type is defined. - /// This is the default restore type. However, writers should treat this restore type as if it were VSS_RTYPE_BY_COPY. - /// This indicates an error on the part of the requester. - /// - VSS_RTYPE_UNDEFINED = 0, - - /// - /// A requester restores backed-up data to the original volume from a backup - /// medium. - /// - VSS_RTYPE_BY_COPY, - - /// - /// A requester does not copy data from a backup medium, but imports a transportable shadow copy and uses this - /// imported volume for operations such as data mining. - /// Windows Server 2003, Standard Edition and Windows Server 2003, Web Edition: - /// This value is not supported. All editions of Windows Server 2003 with SP1 support this value. - /// - VSS_RTYPE_IMPORT, - - /// A restore type not currently enumerated. This value indicates an application error. - VSS_RTYPE_OTHER, - } - - /// - /// The VSS_ROLLFORWARD_TYPE enumeration is used by a requester to indicate the type of roll-forward operation it is about to perform. - /// - /// - /// A requester sets the roll-forward operation type and specifies the restore point for partial roll-forward operations using IVssBackupComponentsEx2::SetRollForward. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vss/ne-vss-vss_rollforward_type typedef enum _VSS_ROLLFORWARD_TYPE { - // VSS_RF_UNDEFINED, VSS_RF_NONE, VSS_RF_ALL, VSS_RF_PARTIAL } VSS_ROLLFORWARD_TYPE, *PVSS_ROLLFORWARD_TYPE; - [PInvokeData("vss.h", MSDNShortId = "NE:vss._VSS_ROLLFORWARD_TYPE")] - public enum VSS_ROLLFORWARD_TYPE - { - /// - /// No roll-forward type is defined. - /// This indicates an error on the part of the requester. - /// - VSS_RF_UNDEFINED = 0, - - /// The roll-forward operation should not roll forward through logs. - VSS_RF_NONE, - - /// The roll-forward operation should roll forward through all logs. - VSS_RF_ALL, - - /// The roll-forward operation should roll forward through logs up to a specified restore point. - VSS_RF_PARTIAL, - } - - /// - /// The VSS_SNAPSHOT_COMPATIBILITY enumeration indicates which volume control or file I/O operations are disabled for the - /// volume that has been shadow copied. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vss/ne-vss-vss_snapshot_compatibility typedef enum _VSS_SNAPSHOT_COMPATIBILITY - // { VSS_SC_DISABLE_DEFRAG, VSS_SC_DISABLE_CONTENTINDEX } VSS_SNAPSHOT_COMPATIBILITY; - [PInvokeData("vss.h", MSDNShortId = "NE:vss._VSS_SNAPSHOT_COMPATIBILITY")] - [Flags] - public enum VSS_SNAPSHOT_COMPATIBILITY - { - /// - /// The provider managing the shadow copies for a specified volume does not support defragmentation operations - /// on that volume. - /// - VSS_SC_DISABLE_DEFRAG = 0x01, - - /// - /// The provider managing the shadow copies for a specified volume does not support content index operations on - /// that volume. - /// - VSS_SC_DISABLE_CONTENTINDEX = 0x02, - } - - /// - /// The _VSS_SNAPSHOT_CONTEXT enumeration enables a requester using IVssBackupComponents::SetContext to specify how a shadow - /// copy is to be created, queried, or deleted and the degree of writer involvement. - /// - /// - /// The data type to be used with values of _VSS_SNAPSHOT_CONTEXT is LONG. - /// The default context for VSS shadow copies is VSS_CTX_BACKUP. - /// - /// Windows XP: The only supported context is the default, VSS_CTX_BACKUP. Calling IVssBackupComponents::SetContext - /// will return E_NOTIMPL. - /// - /// For details on how to use VSS shadow copies contexts, see Implementation Details for Creating Shadow Copies. - /// - /// Shadow copy behavior can be further controlled by using a bitwise OR to combine a supported _VSS_VOLUME_SNAPSHOT_ATTRIBUTES with - /// valid _VSS_SNAPSHOT_CONTEXT values as an argument to the IVssBackupComponents::SetContext method. - /// - /// - /// Currently, the only supported modifications are the bitwise OR of a _VSS_SNAPSHOT_CONTEXT value with the - /// VSS_VOLSNAP_ATTR_TRANSPORTABLE and either the VSS_VOLSNAP_ATTR_DIFFERENTIAL or the VSS_VOLSNAP_ATTR_PLEX - /// value of the _VSS_VOLUME_SNAPSHOT_ATTRIBUTES enumeration. - /// - /// However, these values cannot be used to modify VSS_CTX_CLIENT_ACCESSIBLE context. - /// - /// The use of VSS_VOLSNAP_ATTR_TRANSPORTABLE is limited to systems running Windows Server 2008 Enterprise, Windows Server - /// 2008 Datacenter, Windows Server 2003, Enterprise Edition, or Windows Server 2003, Datacenter Edition. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vss/ne-vss-vss_snapshot_context typedef enum _VSS_SNAPSHOT_CONTEXT { - // VSS_CTX_BACKUP, VSS_CTX_FILE_SHARE_BACKUP, VSS_CTX_NAS_ROLLBACK, VSS_CTX_APP_ROLLBACK, VSS_CTX_CLIENT_ACCESSIBLE, - // VSS_CTX_CLIENT_ACCESSIBLE_WRITERS, VSS_CTX_ALL } VSS_SNAPSHOT_CONTEXT, *PVSS_SNAPSHOT_CONTEXT; - [PInvokeData("vss.h", MSDNShortId = "NE:vss._VSS_SNAPSHOT_CONTEXT")] - [Flags] - public enum VSS_SNAPSHOT_CONTEXT : uint - { - /// - /// The standard backup context. Specifies an auto-release, nonpersistent shadow copy in which writers are - /// involved in the creation. - /// - VSS_CTX_BACKUP = 0, - - /// Specifies an auto-release, nonpersistent shadow copy created without writer involvement. - VSS_CTX_FILE_SHARE_BACKUP = VSS_VOLUME_SNAPSHOT_ATTRIBUTES.VSS_VOLSNAP_ATTR_NO_WRITERS, - - /// - /// Specifies a persistent, non-auto-release shadow copy without writer involvement. This context should be - /// used when there is no need for writer involvement to ensure that files are in a consistent state at the time - /// of the shadow copy. - /// Lightweight automated file rollback mechanisms or persistent shadow copies of file shares or data volumes - /// that are not expected to contain any system-related files or databases might run under this context. For - /// example, a requester could use this context for creating a shadow copy of a NAS volume hosting documents and - /// simple user shares. Those types of data do not need writer involvement to create a consistent shadow copy. - /// - VSS_CTX_NAS_ROLLBACK = VSS_VOLUME_SNAPSHOT_ATTRIBUTES.VSS_VOLSNAP_ATTR_PERSISTENT | VSS_VOLUME_SNAPSHOT_ATTRIBUTES.VSS_VOLSNAP_ATTR_NO_AUTO_RELEASE | VSS_VOLUME_SNAPSHOT_ATTRIBUTES.VSS_VOLSNAP_ATTR_NO_WRITERS, - - /// - /// Specifies a persistent, non-auto-release shadow copy with writer involvement. This context is designed - /// to be used when writers are needed to ensure that files are in a well-defined state prior to shadow copy. - /// Automated file rollback mechanisms of system volumes and shadow copies to be used in data mining or restore - /// operations might run under this context. This context is similar to - /// VSS_CTX_BACKUP - /// but allows a requester more control over the persistence of the shadow copy. - /// - VSS_CTX_APP_ROLLBACK = VSS_VOLUME_SNAPSHOT_ATTRIBUTES.VSS_VOLSNAP_ATTR_PERSISTENT | VSS_VOLUME_SNAPSHOT_ATTRIBUTES.VSS_VOLSNAP_ATTR_NO_AUTO_RELEASE, - - /// - /// Specifies a read-only, - /// client-accessible shadow copy - /// - /// that supports Shadow Copies for Shared Folders and is created without writer involvement. Only the system provider (the - /// default provider available on the system) can create this type of shadow copy. - /// - /// Most requesters will want to use the - /// VSS_CTX_NAS_ROLLBACK - /// context for persistent, non-auto-release shadow copies without writer involvement. - /// - VSS_CTX_CLIENT_ACCESSIBLE = VSS_VOLUME_SNAPSHOT_ATTRIBUTES.VSS_VOLSNAP_ATTR_PERSISTENT | VSS_VOLUME_SNAPSHOT_ATTRIBUTES.VSS_VOLSNAP_ATTR_NO_AUTO_RELEASE | VSS_VOLUME_SNAPSHOT_ATTRIBUTES.VSS_VOLSNAP_ATTR_CLIENT_ACCESSIBLE | VSS_VOLUME_SNAPSHOT_ATTRIBUTES.VSS_VOLSNAP_ATTR_NO_WRITERS, - - /// - /// Specifies a read-only, - /// client-accessible shadow copy - /// - /// that is created with writer involvement. Only the system provider (the default provider available on the system) can create - /// this type of shadow copy. - /// - /// Most requesters will want to use the - /// VSS_CTX_APP_ROLLBACK - /// context for persistent, non-auto-release shadow copies with writer involvement. - /// Windows Server 2003 and Windows XP: - /// This context is not supported by Windows Server 2003 and Windows XP. - /// - VSS_CTX_CLIENT_ACCESSIBLE_WRITERS = VSS_VOLUME_SNAPSHOT_ATTRIBUTES.VSS_VOLSNAP_ATTR_PERSISTENT | VSS_VOLUME_SNAPSHOT_ATTRIBUTES.VSS_VOLSNAP_ATTR_NO_AUTO_RELEASE | VSS_VOLUME_SNAPSHOT_ATTRIBUTES.VSS_VOLSNAP_ATTR_CLIENT_ACCESSIBLE, - - /// - /// All types of currently live shadow copies are available for administrative operations, such as shadow copy - /// queries (see - /// IVssBackupComponents::Query - /// ). - /// VSS_CTX_ALL - /// is a valid context for all VSS interfaces except - /// IVssBackupComponents::StartSnapshotSet - /// and - /// IVssBackupComponents::DoSnapshotSet - /// . - /// - VSS_CTX_ALL = 0xffffffff, - } - - /// - /// The VSS_SNAPSHOT_STATE enumeration is returned by a provider to specify the state of a given shadow copy operation. - /// - /// - /// - /// The shadow copy state is contained in the m_eStatus member of a VSS_SNAPSHOT_PROP object, which can be obtained for a - /// single shadow copy by calling IVssBackupComponents::GetSnapshotProperties. - /// - /// - /// Because IVssBackupComponents::GetSnapshotProperties fails during shadow copy creation with VSS_E_OBJECT_NOT_FOUND, a - /// requester cannot obtain any VSS_SNAPSHOT_STATE value other than VSS_SS_CREATED. - /// - /// - /// Calls to IVssBackupComponents::Query can also be used to obtain the shadow copy state. IVssBackupComponents::Query is - /// used to return lists of shadow copies, which may be iterated over by means of the IVssEnumObject interface to obtain - /// VSS_SNAPSHOT_PROP objects for each shadow copy that have completed on a given system. This means that, like - /// IVssBackupComponents::GetSnapshotProperties, the IVssBackupComponents::Query method can return only a shadow copy state - /// of VSS_SS_CREATED. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vss/ne-vss-vss_snapshot_state typedef enum _VSS_SNAPSHOT_STATE { - // VSS_SS_UNKNOWN, VSS_SS_PREPARING, VSS_SS_PROCESSING_PREPARE, VSS_SS_PREPARED, VSS_SS_PROCESSING_PRECOMMIT, VSS_SS_PRECOMMITTED, - // VSS_SS_PROCESSING_COMMIT, VSS_SS_COMMITTED, VSS_SS_PROCESSING_POSTCOMMIT, VSS_SS_PROCESSING_PREFINALCOMMIT, - // VSS_SS_PREFINALCOMMITTED, VSS_SS_PROCESSING_POSTFINALCOMMIT, VSS_SS_CREATED, VSS_SS_ABORTED, VSS_SS_DELETED, - // VSS_SS_POSTCOMMITTED, VSS_SS_COUNT } VSS_SNAPSHOT_STATE, *PVSS_SNAPSHOT_STATE; - [PInvokeData("vss.h", MSDNShortId = "NE:vss._VSS_SNAPSHOT_STATE")] - public enum VSS_SNAPSHOT_STATE - { - /// - /// Reserved for system use. - /// Unknown shadow copy state. - /// - VSS_SS_UNKNOWN = 0, - - /// - /// Reserved for system use. - /// Shadow copy is being prepared. - /// - VSS_SS_PREPARING, - - /// - /// Reserved for system use. - /// Processing of the shadow copy preparation is in progress. - /// - VSS_SS_PROCESSING_PREPARE, - - /// - /// Reserved for system use. - /// Shadow copy has been prepared. - /// - VSS_SS_PREPARED, - - /// - /// Reserved for system use. - /// Processing of the shadow copy precommit is in process. - /// - VSS_SS_PROCESSING_PRECOMMIT, - - /// - /// Reserved for system use. - /// Shadow copy is precommitted. - /// - VSS_SS_PRECOMMITTED, - - /// - /// Reserved for system use. - /// Processing of the shadow copy commit is in process. - /// - VSS_SS_PROCESSING_COMMIT, - - /// - /// Reserved for system use. - /// Shadow copy is committed. - /// - VSS_SS_COMMITTED, - - /// - /// Reserved for system use. - /// Processing of the shadow copy postcommit is in process. - /// - VSS_SS_PROCESSING_POSTCOMMIT, - - /// - /// Reserved for system use. - /// Processing of the shadow copy file commit operation is underway. - /// - VSS_SS_PROCESSING_PREFINALCOMMIT, - - /// - /// Reserved for system use. - /// Processing of the shadow copy file commit operation is done. - /// - VSS_SS_PREFINALCOMMITTED, - - /// - /// Reserved for system use. - /// Processing of the shadow copy following the final commit and prior to shadow copy create is underway. - /// - VSS_SS_PROCESSING_POSTFINALCOMMIT, - - /// Shadow copy is created. - VSS_SS_CREATED, - - /// - /// Reserved for system use. - /// Shadow copy creation is aborted. - /// - VSS_SS_ABORTED, - - /// - /// Reserved for system use. - /// Shadow copy has been deleted. - /// - VSS_SS_DELETED, - - /// - VSS_SS_POSTCOMMITTED, - - /// Reserved value. - VSS_SS_COUNT, - } - - /// - /// Allows additional attributes to be specified for a shadow copy. The context of a shadow copy (as set by the - /// IVssBackupComponents::SetContext method) may be modified by a bitmask that contains a valid combination of - /// _VSS_VOLUME_SNAPSHOT_ATTRIBUTES and _VSS_SNAPSHOT_CONTEXT enumeration values. - /// - /// - /// The default context for VSS shadow copies is VSS_CTX_BACKUP. - /// - /// A requester sets the context for a shadow copy about to be created by passing the member of the _VSS_SNAPSHOT_CONTEXT - /// enumeration to the IVssBackupComponents::SetContext method. - /// - /// - /// Requesters can modify this context by using a bitwise OR of the _VSS_SNAPSHOT_CONTEXT value with a supported value from the - /// _VSS_VOLUME_SNAPSHOT_ATTRIBUTES enumeration as an argument to IVssBackupComponents::SetContext. - /// - /// - /// Unless specifically requested to support a given mechanism, providers are free to use any type of mechanism to implement a - /// shadow copy. Therefore, in the case where a shadow copy method is not specified, the provider is free to choose a differential - /// mechanism ( VSS_VOLSNAP_ATTR_DIFFERENTIAL), a PLEX mechanism ( VSS_VOLSNAP_ATTR_PLEX), or any other mechanism to - /// support the shadow copy. - /// - /// - /// While a provider can support both mechanisms, they are mutually exclusive for a given shadow copy. Requesters should not use - /// both VSS_VOLSNAP_ATTR_DIFFERENTIAL and VSS_VOLSNAP_ATTR_PLEX to modify a specific shadow copy context. - /// - /// - /// Currently, VSS_VOLSNAP_ATTR_DIFFERENTIAL, VSS_VOLSNAP_ATTR_PLEX, and VSS_VOLSNAP_ATTR_TRANSPORTABLE are the - /// only values of the _VSS_VOLUME_SNAPSHOT_ATTRIBUTES enumeration that can be used to modify any context. - /// - /// In addition, it cannot be used to modify a VSS_CTX_CLIENT_ACCESSIBLE context. - /// - /// A requester can obtain information about a specific shadow copy (identified by VSS_ID) by unpacking the VSS_SNAPSHOT_PROP - /// structure from the VSS_OBJECT_PROP structure returned by a call to IVssBackupComponents::GetSnapshotProperties. - /// - /// - /// A requester can also obtain a VSS_SNAPSHOT_PROP structure for each of multiple shadow copies by calling - /// IVssBackupComponents::Query and using IVssEnumObject to iterate the returns. - /// - /// - /// The shadow copies' context and attributes are found as a bit mask contained in the m_lSnapshotAttributes member of the - /// VSS_SNAPSHOT_PROP structure. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vss/ne-vss-vss_volume_snapshot_attributes typedef enum - // _VSS_VOLUME_SNAPSHOT_ATTRIBUTES { VSS_VOLSNAP_ATTR_PERSISTENT, VSS_VOLSNAP_ATTR_NO_AUTORECOVERY, - // VSS_VOLSNAP_ATTR_CLIENT_ACCESSIBLE, VSS_VOLSNAP_ATTR_NO_AUTO_RELEASE, VSS_VOLSNAP_ATTR_NO_WRITERS, - // VSS_VOLSNAP_ATTR_TRANSPORTABLE, VSS_VOLSNAP_ATTR_NOT_SURFACED, VSS_VOLSNAP_ATTR_NOT_TRANSACTED, - // VSS_VOLSNAP_ATTR_HARDWARE_ASSISTED, VSS_VOLSNAP_ATTR_DIFFERENTIAL, VSS_VOLSNAP_ATTR_PLEX, VSS_VOLSNAP_ATTR_IMPORTED, - // VSS_VOLSNAP_ATTR_EXPOSED_LOCALLY, VSS_VOLSNAP_ATTR_EXPOSED_REMOTELY, VSS_VOLSNAP_ATTR_AUTORECOVER, - // VSS_VOLSNAP_ATTR_ROLLBACK_RECOVERY, VSS_VOLSNAP_ATTR_DELAYED_POSTSNAPSHOT, VSS_VOLSNAP_ATTR_TXF_RECOVERY, - // VSS_VOLSNAP_ATTR_FILE_SHARE } VSS_VOLUME_SNAPSHOT_ATTRIBUTES, *PVSS_VOLUME_SNAPSHOT_ATTRIBUTES; - [PInvokeData("vss.h", MSDNShortId = "NE:vss._VSS_VOLUME_SNAPSHOT_ATTRIBUTES")] - [Flags] - public enum VSS_VOLUME_SNAPSHOT_ATTRIBUTES : uint - { - /// - /// The shadow copy is persistent across reboots. - /// This attribute is automatically set for - /// _VSS_SNAPSHOT_CONTEXT - /// contexts of - /// VSS_CTX_APP_ROLLBACK - /// , - /// VSS_CTX_CLIENT_ACCESSIBLE - /// , - /// VSS_CTX_CLIENT_ACCESSIBLE_WRITERS - /// , and - /// VSS_CTX_NAS_ROLLBACK - /// . - /// This attribute should not be used explicitly by requesters when setting the context of a shadow copy. - /// - VSS_VOLSNAP_ATTR_PERSISTENT = 0x01, - - /// - /// Auto-recovery - /// is disabled for the shadow copy. - /// - /// A requester can modify a shadow copy context with a bitwise OR of this attribute. By doing this, the requester instructs VSS - /// to make the shadow copy read-only immediately after it is created, without allowing writers or other applications to update - /// components in the shadow copy. - /// - /// - /// Disabling auto-recovery can cause the shadow copy to be in an inconsistent state if any of its components are involved in - /// transactional database operations, such as transactional read and write operations managed by Transactional NTFS (TxF). This - /// is because disabling auto-recovery prevents incomplete transactions from being rolled back. - /// - /// - /// Disabling auto-recovery also prevents writers from excluding files from the shadow copy. When auto-recovery is disabled, a - /// writer can still call the - /// - /// IVssCreateWriterMetadataEx::AddExcludeFilesFromSnapshot - /// method, but the writer's - /// CVssWriter::OnPostSnapshot - /// method cannot delete the files from the shadow copy. - /// Windows Server 2003 and Windows XP: - /// This value is not supported until Windows Vista. - /// - VSS_VOLSNAP_ATTR_NO_AUTORECOVERY = 0x02, - - /// - /// The specified shadow copy is a - /// client-accessible shadow copy - /// that supports Shadow Copies for Shared Folders, and should not be exposed. - /// This attribute is automatically set for - /// VSS_CTX_CLIENT_ACCESSIBLE - /// and - /// VSS_CTX_CLIENT_ACCESSIBLE_WRITERS - /// . - /// This attribute should not be used explicitly by requesters when setting the context of a shadow copy. - /// - VSS_VOLSNAP_ATTR_CLIENT_ACCESSIBLE = 0x04, - - /// - /// The shadow copy is not automatically deleted when the shadow copy requester process ends. The shadow copy - /// can be deleted only by a call to - /// IVssBackupComponents::DeleteSnapshots - /// . - /// This attribute is automatically set for - /// _VSS_SNAPSHOT_CONTEXT - /// contexts of - /// VSS_CTX_APP_ROLLBACK - /// , - /// VSS_CTX_CLIENT_ACCESSIBLE - /// , - /// VSS_CTX_CLIENT_ACCESSIBLE_WRITERS - /// , and - /// VSS_CTX_NAS_ROLLBACK - /// . - /// This attribute should not be used explicitly by requesters when setting the context of a shadow copy. - /// - VSS_VOLSNAP_ATTR_NO_AUTO_RELEASE = 0x08, - - /// - /// No writers are involved in creating the shadow copy. - /// This attribute is automatically set for - /// _VSS_SNAPSHOT_CONTEXT - /// contexts of - /// VSS_CTX_NAS_ROLLBACK - /// , - /// VSS_CTX_FILE_SHARE_BACKUP - /// , and - /// VSS_CTX_CLIENT_ACCESSIBLE - /// . - /// This attribute should not be used explicitly by requesters when setting the context of a shadow copy. - /// - VSS_VOLSNAP_ATTR_NO_WRITERS = 0x10, - - /// - /// The shadow copy is to be transported and therefore should not be surfaced locally. - /// This attribute can be used explicitly by requesters when setting the context of a shadow copy, if the - /// provider for shadow copy supports transportable shadow copies. - /// Windows Server 2003, Standard Edition, Windows Server 2003, Web Edition and Windows XP: - /// This attribute is not supported. All editions of Windows Server 2003 with SP1 support this attribute. - /// See - /// Importing Transportable Shadow Copied Volumes - /// for more information. - /// - VSS_VOLSNAP_ATTR_TRANSPORTABLE = 0x20, - - /// - /// The shadow copy is not currently exposed. - /// Unless the shadow copy is explicitly exposed or mounted, this attribute is set for all shadow copies. - /// This attribute should not be used explicitly by requesters when setting the context of a shadow copy. - /// - VSS_VOLSNAP_ATTR_NOT_SURFACED = 0x40, - - /// - /// The shadow copy is not transacted. - /// - /// A requester can modify a shadow copy context with a bitwise OR of this attribute. By doing this, the requester instructs VSS - /// to disable built-in integration between VSS and transaction and resource managers. - /// - /// - /// Setting this attribute guarantees that the requester will not receive VSS_E_TRANSACTION_FREEZE_TIMEOUT errors. However, it - /// may cause unwanted consequences, such as the loss of transactional integrity or even data loss. - /// - /// Windows Server 2003 and Windows XP: - /// This value is not supported until Windows Vista. - /// - VSS_VOLSNAP_ATTR_NOT_TRANSACTED = 0x80, - - /// - /// Indicates that a given provider is a hardware provider. - /// This attribute is automatically set for hardware providers. - /// This enumeration value cannot be used to manually set the context (using the - /// IVssBackupComponents::SetContext - /// method) of a shadow copy by a bit mask (or bitwise OR) of this enumeration value and a valid shadow copy - /// context value from - /// _VSS_SNAPSHOT_CONTEXT - /// . - /// - VSS_VOLSNAP_ATTR_HARDWARE_ASSISTED = 0x10000, - - /// - /// Indicates that a given provider uses differential data or a copy-on-write mechanism to implement shadow copies. - /// A requester can modify a shadow copy context with a bitwise OR of this attribute. By doing this, the - /// requester instructs providers to create a shadow copy using a differential implementation. If no shadow copy - /// provider installed on the system supports the requested attributes, a VSS_E_VOLUME_NOT_SUPPORTED error will be - /// returned to - /// IVssBackupComponents::AddToSnapshotSet - /// . - /// - VSS_VOLSNAP_ATTR_DIFFERENTIAL = 0x20000, - - /// - /// Indicates that a given provider uses a PLEX or mirrored split mechanism to implement shadow copies. - /// A requester can modify a shadow copy context with a bitwise OR of this attribute. By doing this, the - /// requester instructs the providers to create a shadow copy using a PLEX implementation. If no shadow copy - /// provider installed on the system supports the requested attributes, a VSS_E_VOLUME_NOT_SUPPORTED error will be - /// returned to - /// IVssBackupComponents::AddToSnapshotSet - /// . - /// - VSS_VOLSNAP_ATTR_PLEX = 0x40000, - - /// - /// The shadow copy of the volume was imported onto this machine using the - /// IVssBackupComponents::ImportSnapshots - /// method rather than created using the - /// IVssBackupComponents::DoSnapshotSet - /// method. - /// This attribute is automatically set if a shadow copy is imported. - /// This attribute should not be used explicitly by requesters when setting the context of a shadow copy. - /// - VSS_VOLSNAP_ATTR_IMPORTED = 0x80000, - - /// - /// The shadow copy is locally exposed. If this bit flag and the VSS_VOLSNAP_ATTR_EXPOSED_REMOTELY bit flag are - /// not set, the shadow copy is hidden. - /// The attribute is automatically added to a shadow copy context upon calling the - /// IVssBackupComponents::ExposeSnapshot - /// method to expose a shadow copy locally. - /// This attribute should not be used explicitly by requesters when setting the context of a shadow copy. - /// - VSS_VOLSNAP_ATTR_EXPOSED_LOCALLY = 0x100000, - - /// - /// The shadow copy is remotely exposed. If this bit flag and the VSS_VOLSNAP_ATTR_EXPOSED_LOCALLY bit flag are - /// not set, the shadow copy is hidden. - /// The attribute is automatically added to a shadow copy context upon calling the - /// IVssBackupComponents::ExposeSnapshot - /// method to expose a shadow copy locally. - /// This attribute should not be used explicitly by requesters when setting the context of a shadow copy. - /// - VSS_VOLSNAP_ATTR_EXPOSED_REMOTELY = 0x200000, - - /// - /// Indicates that the writer will need to - /// auto-recover - /// the component in - /// CVssWriter::OnPostSnapshot - /// . - /// This attribute should not be used explicitly by requesters when setting the context of a shadow copy. - /// - VSS_VOLSNAP_ATTR_AUTORECOVER = 0x400000, - - /// - /// Indicates that the writer will need to - /// auto-recover - /// the component in - /// CVssWriter::OnPostSnapshot - /// if the shadow copy is being used for rollback (for data mining, for example). - /// - /// A requester would set this flag in the shadow copy context to indicate that the shadow copy is being created for a - /// non-backup purpose such as data mining. - /// - /// - VSS_VOLSNAP_ATTR_ROLLBACK_RECOVERY = 0x800000, - - /// - /// Reserved for system use. - /// Windows Vista, Windows Server 2003 and Windows XP: - /// This value is not supported until Windows Server 2008. - /// - VSS_VOLSNAP_ATTR_DELAYED_POSTSNAPSHOT = 0x1000000, - - /// - /// Indicates that TxF recovery should be enforced during shadow copy creation. - /// Windows Vista, Windows Server 2003 and Windows XP: - /// This value is not supported until Windows Server 2008. - /// - VSS_VOLSNAP_ATTR_TXF_RECOVERY = 0x2000000, - - /// - VSS_VOLSNAP_ATTR_FILE_SHARE = 0x4000000, - } - - /// The VSS_WRITER_STATE enumeration indicates the current state of the writer. - /// A requester determines the state of a writer through IVssBackupComponents::GetWriterStatus. - // https://docs.microsoft.com/en-us/windows/win32/api/vss/ne-vss-vss_writer_state typedef enum _VSS_WRITER_STATE { VSS_WS_UNKNOWN, - // VSS_WS_STABLE, VSS_WS_WAITING_FOR_FREEZE, VSS_WS_WAITING_FOR_THAW, VSS_WS_WAITING_FOR_POST_SNAPSHOT, - // VSS_WS_WAITING_FOR_BACKUP_COMPLETE, VSS_WS_FAILED_AT_IDENTIFY, VSS_WS_FAILED_AT_PREPARE_BACKUP, - // VSS_WS_FAILED_AT_PREPARE_SNAPSHOT, VSS_WS_FAILED_AT_FREEZE, VSS_WS_FAILED_AT_THAW, VSS_WS_FAILED_AT_POST_SNAPSHOT, - // VSS_WS_FAILED_AT_BACKUP_COMPLETE, VSS_WS_FAILED_AT_PRE_RESTORE, VSS_WS_FAILED_AT_POST_RESTORE, VSS_WS_FAILED_AT_BACKUPSHUTDOWN, - // VSS_WS_COUNT } VSS_WRITER_STATE, *PVSS_WRITER_STATE; - [PInvokeData("vss.h", MSDNShortId = "NE:vss._VSS_WRITER_STATE")] - public enum VSS_WRITER_STATE - { - /// - /// The writer's state is not known. - /// This indicates an error on the part of the writer. - /// - VSS_WS_UNKNOWN = 0, - - /// - /// The writer has completed processing current shadow copy events and is ready to proceed, or - /// CVssWriter::OnPrepareSnapshot - /// has not yet - /// been called. - /// - VSS_WS_STABLE, - - /// The writer is waiting for the freeze state. - VSS_WS_WAITING_FOR_FREEZE, - - /// The writer is waiting for the thaw state. - VSS_WS_WAITING_FOR_THAW, - - /// - /// The writer is waiting for the - /// PostSnapshot - /// state. - /// - VSS_WS_WAITING_FOR_POST_SNAPSHOT, - - /// The writer is waiting for the requester to finish its backup operation. - VSS_WS_WAITING_FOR_BACKUP_COMPLETE, - - /// The writer vetoed the shadow copy creation process at the writer identification state. - VSS_WS_FAILED_AT_IDENTIFY, - - /// The writer vetoed the shadow copy creation process during the backup preparation state. - VSS_WS_FAILED_AT_PREPARE_BACKUP, - - /// - /// The writer vetoed the shadow copy creation process during the - /// PrepareForSnapshot - /// state. - /// - VSS_WS_FAILED_AT_PREPARE_SNAPSHOT, - - /// The writer vetoed the shadow copy creation process during the freeze state. - VSS_WS_FAILED_AT_FREEZE, - - /// The writer vetoed the shadow copy creation process during the thaw state. - VSS_WS_FAILED_AT_THAW, - - /// - /// The writer vetoed the shadow copy creation process during the - /// PostSnapshot - /// state. - /// - VSS_WS_FAILED_AT_POST_SNAPSHOT, - - /// - /// The shadow copy has been created and the writer failed during the - /// BackupComplete - /// state. A writer - /// should save information about this failure to the error log. For additional information on logging, see - /// Event and Error Handling Under VSS - /// . - /// - VSS_WS_FAILED_AT_BACKUP_COMPLETE, - - /// - /// The writer failed during the - /// PreRestore - /// state. - /// - VSS_WS_FAILED_AT_PRE_RESTORE, - - /// - /// The writer failed during the - /// PostRestore - /// state. - /// - VSS_WS_FAILED_AT_POST_RESTORE, - - /// The writer failed during the shutdown of the backup application. - VSS_WS_FAILED_AT_BACKUPSHUTDOWN, - - /// Reserved value. - VSS_WS_COUNT, - } - - /// - /// - /// The IVssAsync interface is returned to calling applications by methods that initiate asynchronous operations, which run - /// in the background and typically require a long time to complete. - /// - /// - /// The IVssAsync interface permits an application to monitor and control an asynchronous operation by waiting on its - /// completion, querying its status, or canceling it. - /// - /// - /// The calling application is responsible for calling IUnknown::Release to release the resources held by the returned - /// IVssAsync interface when it is no longer needed. - /// - /// The following methods return an IVssAsync interface: - /// + /// + /// This method can succeed even if the method that returns it failed. + // https://docs.microsoft.com/en-us/windows/win32/api/vss/nf-vss-ivssasync-wait HRESULT Wait( [in] DWORD dwMilliseconds ); + [PreserveSig] + HRESULT Wait(uint dwMilliseconds = 0xffffffff); + + /// The QueryStatus method queries the status of an asynchronous operation. + /// + /// The status of the asynchronous operation that returned the current IVssAsync object. + /// All calls to QueryStatus for all IVssAsync objects support the following status codes. + /// + /// + /// Value + /// Meaning + /// /// - /// IVssBackupComponents::BackupComplete + /// VSS_S_ASYNC_CANCELLED + /// The asynchronous operation was canceled by a previous call to IVssAsync::Cancel. /// /// - /// IVssBackupComponents::DoSnapshotSet + /// VSS_S_ASYNC_FINISHED + /// The asynchronous operation was completed successfully. /// /// - /// IVssBackupComponents::GatherWriterMetadata - /// - /// - /// IVssBackupComponents::GatherWriterStatus - /// - /// - /// IVssBackupComponents::ImportSnapshots - /// - /// - /// IVssBackupComponents::PostRestore - /// - /// - /// IVssBackupComponents::PrepareForBackup - /// - /// - /// IVssBackupComponents::PreRestore + /// VSS_S_ASYNC_PENDING + /// The asynchronous operation is still running. /// /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vss/nn-vss-ivssasync - [PInvokeData("vss.h", MSDNShortId = "NN:vss.IVssAsync")] - [ComImport, Guid("507C37B4-CF5B-4e95-B0AF-14EB9767467E"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IVssAsync - { - /// The Cancel method cancels an incomplete asynchronous operation. - /// - /// All calls to Cancel for all IVssAsync objects support the following status codes. - /// - /// - /// Value - /// Meaning - /// - /// - /// S_OK - /// The asynchronous operation had been successfully canceled. - /// - /// - /// VSS_S_ASYNC_CANCELLED - /// The asynchronous operation had been canceled prior to calling this method. - /// - /// - /// VSS_S_ASYNC_FINISHED - /// The asynchronous operation had completed prior to calling this method. - /// - /// - /// 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. - /// - /// - /// - /// - /// If an operation has completed unsuccessfully before Cancel was called, then Cancel returns the error that - /// operation encountered. - /// - /// - /// To obtain a complete list of return values for a specific IVssAsync::Cancel, see the error codes of the method that - /// returned the IVssAsync object. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vss/nf-vss-ivssasync-cancel HRESULT Cancel(); - [PreserveSig] - HRESULT Cancel(); - - /// The Wait method waits until an incomplete asynchronous operation finishes. - /// - /// Length of time, in milliseconds, that the method will wait for an asynchronous process to return before timing out. - /// The default value for this argument is INFINITE. - /// - /// Windows Server 2003: This parameter is reserved and must be INFINITE. If any other value is specified for this - /// parameter, the call to Wait fails with E_INVALIDARG. - /// - /// Windows XP: This method has no parameters. - /// - /// - /// All calls to Wait for all IVssAsync objects support the following status codes. - /// - /// - /// Value - /// Meaning - /// - /// - /// S_OK - /// The wait operation was successful. Call IVssAsync::QueryStatus to determine the final status of the asynchronous operation. - /// - /// - /// E_ACCESSDENIED - /// The wait operation failed because the user did not have the correct privileges. - /// - /// - /// 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. - /// - /// - /// - /// If an operation fails while being waited on, Wait returns the error that operation encountered. - /// - /// To obtain a complete list of return values for a specific Wait, see the error codes of the method that returned the - /// IVssAsync object. - /// - /// - /// This method can succeed even if the method that returns it failed. - // https://docs.microsoft.com/en-us/windows/win32/api/vss/nf-vss-ivssasync-wait HRESULT Wait( [in] DWORD dwMilliseconds ); - [PreserveSig] - HRESULT Wait(uint dwMilliseconds = 0xffffffff); - - /// The QueryStatus method queries the status of an asynchronous operation. - /// - /// The status of the asynchronous operation that returned the current IVssAsync object. - /// All calls to QueryStatus for all IVssAsync objects support the following status codes. - /// - /// - /// Value - /// Meaning - /// - /// - /// VSS_S_ASYNC_CANCELLED - /// The asynchronous operation was canceled by a previous call to IVssAsync::Cancel. - /// - /// - /// VSS_S_ASYNC_FINISHED - /// The asynchronous operation was completed successfully. - /// - /// - /// VSS_S_ASYNC_PENDING - /// The asynchronous operation is still running. - /// - /// - /// - /// Additional return values can be returned, but depend on the return codes of the method that initially returned the IVssAsync object. - /// - /// - /// The value of this parameter should be NULL. - /// - /// The following are the valid return codes for this method. - /// - /// - /// Value - /// Meaning - /// - /// - /// S_OK - /// The query operation was successful. - /// - /// - /// E_ACCESSDENIED - /// The query operation failed because the user did not have the correct privileges. - /// - /// - /// E_INVALIDARG - /// The pointer to the variable used to hold the pHrResult return value is NULL or is not a valid memory location. - /// - /// - /// 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. - /// - /// - /// - /// - /// - /// - /// In the event of an error during the course of an asynchronous operation, QueryStatus will return the same error code - /// as the method that initially returned the IVssAsync object. - /// - /// - /// To obtain a complete list of return values for an IVssAsync::QueryStatus object returned by a specific method, see - /// the error codes documented for that method. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vss/nf-vss-ivssasync-querystatus HRESULT QueryStatus( [out] HRESULT - // *pHrResult, [out] INT *pReserved ); - [PreserveSig] - HRESULT QueryStatus(out HRESULT pHrResult, [In, Optional] IntPtr pReserved); - } - - /// /// - /// The IVssEnumObject interface contains methods to iterate over and perform other operations on a list of enumerated objects. + /// Additional return values can be returned, but depend on the return codes of the method that initially returned the IVssAsync object. /// - /// - /// The calling application is responsible for calling IUnknown::Release to release the resources held by the returned - /// IVssEnumObject when it is no longer needed. It may also need to call IUnknown::Release to release temporary - /// objects (such as strings) returned during enumeration. - /// - /// The IVssBackupComponents::Query method returns an IVssEnumObject object. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vss/nn-vss-ivssenumobject - [PInvokeData("vss.h", MSDNShortId = "NN:vss.IVssEnumObject")] - [ComImport, Guid("AE1C7110-2F60-11d3-8A39-00C04F72D8E3"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - public interface IVssEnumObject : ICOMEnum - { - /// The Next method returns the specified number of objects from the specified list of enumerated objects. - /// The number of elements to be read from the list of enumerated objects into the rgelt buffer. - /// - /// The address of a caller-allocated buffer that receives celtVSS_OBJECT_PROP structures that contain the returned objects. - /// This parameter is required and cannot be NULL. - /// - /// The number of elements that were returned in the rgelt buffer. - /// - /// The following are the valid return codes for this method. - /// - /// - /// Value - /// Meaning - /// - /// - /// S_OK - /// The operation was successful. - /// - /// - /// S_FALSE - /// The number of returned items is less than the number requested. - /// - /// - /// E_FAIL - /// There is an internal error in the enumerator. - /// - /// - /// E_POINTER - /// One of the required pointer parameters is NULL. - /// - /// - /// - /// - /// - /// When requesting the return of more than one VSS_OBJECT_PROP object, a return value of S_FALSE indicates that the end of the - /// enumeration list has been reached. If more objects were requested than remained in the list, Next will return all the - /// remaining objects, set the pceltFetched parameter to a nonzero value, and return S_FALSE. - /// - /// - /// The output rgelt parameter must point to an allocated array containing celt VSS_OBJECT_PROP structures, and cannot be NULL. - /// - /// - /// It is the caller's responsibility to free system resources returned by IVssEnumObject::Next to the VSS_OBJECT_PROP - /// structure pointed to by the rgelt parameter. - /// - /// - /// The callers must use CoTaskMemFree for every string value in the VSS_SNAPSHOT_PROP or VSS_PROVIDER_PROP object in the - /// returned VSS_OBJECT_PROP structure. - /// - /// - /// In the case of VSS_SNAPSHOT_PROP, this can be done manually, or the utility function VssFreeSnapshotProperties can be used. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vss/nf-vss-ivssenumobject-next HRESULT Next( [in] ULONG celt, [out] - // VSS_OBJECT_PROP *rgelt, [out] ULONG *pceltFetched ); - [PreserveSig] - HRESULT Next(uint celt, [Out, MarshalAs(UnmanagedType.LPArray)] VSS_OBJECT_PROP[] rgelt, out uint pceltFetched); - - /// The Skip method skips the specified number of objects. - /// Number of elements to be skipped in the list of enumerated objects. - /// - /// The following are the valid return codes for this method. - /// - /// - /// Value - /// Meaning - /// - /// - /// S_OK - /// The operation was successful. - /// - /// - /// S_FALSE - /// An attempt was made to access a location beyond the end of the list of items. - /// - /// - /// E_FAIL - /// There was an internal error in the enumerator. - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vss/nf-vss-ivssenumobject-skip HRESULT Skip( [in] ULONG celt ); - [PreserveSig] - HRESULT Skip(uint celt); - - /// The Reset method resets the enumerator so that IVssEnumObject:Next starts at the first enumerated object. - // https://docs.microsoft.com/en-us/windows/win32/api/vss/nf-vss-ivssenumobject-reset HRESULT Reset(); - void Reset(); - - /// - /// The Clone method creates a copy of the specified list of enumerated elements by creating a copy of the IVssEnumObject - /// enumerator object. - /// - /// - /// Doubly indirect pointer to an IVssEnumObject enumerator object. Set the value of this parameter to NULL before - /// calling this method. - /// - /// - /// The cloned enumerator object will refer to the same list of VSS_OBJECT_PROP structures. - /// - /// The caller must call the Release method of the returned interface pointer to deallocate the system resources held by the - /// IVssEnumObject enumerator object pointed to by the ppEnum parameter. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vss/nf-vss-ivssenumobject-clone HRESULT Clone( [in, out] IVssEnumObject - // **ppenum ); - IVssEnumObject Clone(); - }; - - /// The VSS_OBJECT_PROP structure defines the properties of a provider, volume, shadow copy, or shadow copy set. + /// + /// The value of this parameter should be NULL. + /// + /// The following are the valid return codes for this method. + /// + /// + /// Value + /// Meaning + /// + /// + /// S_OK + /// The query operation was successful. + /// + /// + /// E_ACCESSDENIED + /// The query operation failed because the user did not have the correct privileges. + /// + /// + /// E_INVALIDARG + /// The pointer to the variable used to hold the pHrResult return value is NULL or is not a valid memory location. + /// + /// + /// 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. + /// + /// + /// + /// /// /// - /// A requester obtains VSS_OBJECT_PROP structures by using IVssEnumObject::Next to iterate over the list of objects returned - /// by a call to IVssBackupComponents::Query. + /// In the event of an error during the course of an asynchronous operation, QueryStatus will return the same error code as + /// the method that initially returned the IVssAsync object. /// /// - /// As its members are filled by a COM interface, prior to deleting the property structures VSS_SNAPSHOT_PROP and VSS_PROVIDER_PROP, - /// the memory they contain must be released by calling CoTaskMemFree for every string and byte array value contained in each structure. + /// To obtain a complete list of return values for an IVssAsync::QueryStatus object returned by a specific method, see the + /// error codes documented for that method. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vss/nf-vss-ivssasync-querystatus HRESULT QueryStatus( [out] HRESULT + // *pHrResult, [out] INT *pReserved ); + [PreserveSig] + HRESULT QueryStatus(out HRESULT pHrResult, [In, Optional] IntPtr pReserved); + } + + /// + /// + /// The IVssEnumObject interface contains methods to iterate over and perform other operations on a list of enumerated objects. + /// + /// + /// The calling application is responsible for calling IUnknown::Release to release the resources held by the returned + /// IVssEnumObject when it is no longer needed. It may also need to call IUnknown::Release to release temporary objects + /// (such as strings) returned during enumeration. + /// + /// The IVssBackupComponents::Query method returns an IVssEnumObject object. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vss/nn-vss-ivssenumobject + [PInvokeData("vss.h", MSDNShortId = "NN:vss.IVssEnumObject")] + [ComImport, Guid("AE1C7110-2F60-11d3-8A39-00C04F72D8E3"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IVssEnumObject : ICOMEnum + { + /// The Next method returns the specified number of objects from the specified list of enumerated objects. + /// The number of elements to be read from the list of enumerated objects into the rgelt buffer. + /// + /// The address of a caller-allocated buffer that receives celtVSS_OBJECT_PROP structures that contain the returned objects. This + /// parameter is required and cannot be NULL. + /// + /// The number of elements that were returned in the rgelt buffer. + /// + /// The following are the valid return codes for this method. + /// + /// + /// Value + /// Meaning + /// + /// + /// S_OK + /// The operation was successful. + /// + /// + /// S_FALSE + /// The number of returned items is less than the number requested. + /// + /// + /// E_FAIL + /// There is an internal error in the enumerator. + /// + /// + /// E_POINTER + /// One of the required pointer parameters is NULL. + /// + /// + /// + /// + /// + /// When requesting the return of more than one VSS_OBJECT_PROP object, a return value of S_FALSE indicates that the end of the + /// enumeration list has been reached. If more objects were requested than remained in the list, Next will return all the + /// remaining objects, set the pceltFetched parameter to a nonzero value, and return S_FALSE. + /// + /// + /// The output rgelt parameter must point to an allocated array containing celt VSS_OBJECT_PROP structures, and cannot be NULL. + /// + /// + /// It is the caller's responsibility to free system resources returned by IVssEnumObject::Next to the VSS_OBJECT_PROP + /// structure pointed to by the rgelt parameter. + /// + /// + /// The callers must use CoTaskMemFree for every string value in the VSS_SNAPSHOT_PROP or VSS_PROVIDER_PROP object in the returned + /// VSS_OBJECT_PROP structure. /// /// /// In the case of VSS_SNAPSHOT_PROP, this can be done manually, or the utility function VssFreeSnapshotProperties can be used. /// /// - // https://docs.microsoft.com/en-us/windows/win32/api/vss/ns-vss-vss_object_prop typedef struct _VSS_OBJECT_PROP { VSS_OBJECT_TYPE - // Type; VSS_OBJECT_UNION Obj; } VSS_OBJECT_PROP, *PVSS_OBJECT_PROP; - [PInvokeData("vss.h", MSDNShortId = "NS:vss._VSS_OBJECT_PROP")] - [StructLayout(LayoutKind.Sequential)] - public struct VSS_OBJECT_PROP - { - /// Object type. Refer to VSS_OBJECT_TYPE. - public VSS_OBJECT_TYPE Type; + // https://docs.microsoft.com/en-us/windows/win32/api/vss/nf-vss-ivssenumobject-next HRESULT Next( [in] ULONG celt, [out] + // VSS_OBJECT_PROP *rgelt, [out] ULONG *pceltFetched ); + [PreserveSig] + HRESULT Next(uint celt, [Out, MarshalAs(UnmanagedType.LPArray)] VSS_OBJECT_PROP[] rgelt, out uint pceltFetched); - /// - /// Object properties: a union of VSS_SNAPSHOT_PROP and VSS_PROVIDER_PROP structures. (See VSS_OBJECT_UNION.) - /// - /// It contains information for an object of the type specified by the Type member of the VSS_OBJECT_PROP - /// structure. Objects can be providers, volumes, shadow copies, or shadow copy sets. - /// - /// - public VSS_OBJECT_UNION Obj; - } + /// The Skip method skips the specified number of objects. + /// Number of elements to be skipped in the list of enumerated objects. + /// + /// The following are the valid return codes for this method. + /// + /// + /// Value + /// Meaning + /// + /// + /// S_OK + /// The operation was successful. + /// + /// + /// S_FALSE + /// An attempt was made to access a location beyond the end of the list of items. + /// + /// + /// E_FAIL + /// There was an internal error in the enumerator. + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vss/nf-vss-ivssenumobject-skip HRESULT Skip( [in] ULONG celt ); + [PreserveSig] + HRESULT Skip(uint celt); + + /// The Reset method resets the enumerator so that IVssEnumObject:Next starts at the first enumerated object. + // https://docs.microsoft.com/en-us/windows/win32/api/vss/nf-vss-ivssenumobject-reset HRESULT Reset(); + void Reset(); /// - /// The VSS_OBJECT_UNION defines the union of object types that can be defined by the VSS_OBJECT_PROP structure (section 2.2.3.2). + /// The Clone method creates a copy of the specified list of enumerated elements by creating a copy of the IVssEnumObject + /// enumerator object. /// - [PInvokeData("vss.h", MSDNShortId = "NS:vss._VSS_OBJECT_PROP")] - [StructLayout(LayoutKind.Explicit)] - public struct VSS_OBJECT_UNION - { - /// The structure specifies a shadow copy object as a VSS_SNAPSHOT_PROP structure (section 2.2.3.3). - [FieldOffset(0)] - public VSS_SNAPSHOT_PROP Snap; - - /// - /// The structure specifies a VSS provider object. The Shadow Copy Management Protocol is not used to manage VSS provider - /// objects; therefore, this member MUST NOT be referenced and MUST be ignored on receipt. - /// - [FieldOffset(0)] - public VSS_PROVIDER_PROP Prov; - } - - /// The VSS_PROVIDER_PROP structure specifies shadow copy provider properties. - // https://docs.microsoft.com/en-us/windows/win32/api/vss/ns-vss-vss_provider_prop typedef struct _VSS_PROVIDER_PROP { VSS_ID - // m_ProviderId; VSS_PWSZ m_pwszProviderName; VSS_PROVIDER_TYPE m_eProviderType; VSS_PWSZ m_pwszProviderVersion; VSS_ID - // m_ProviderVersionId; CLSID m_ClassId; } VSS_PROVIDER_PROP, *PVSS_PROVIDER_PROP; - [PInvokeData("vss.h", MSDNShortId = "NS:vss._VSS_PROVIDER_PROP")] - [StructLayout(LayoutKind.Sequential)] - public struct VSS_PROVIDER_PROP - { - /// Identifies the provider who supports shadow copies of this class. - public Guid m_ProviderId; - - /// Null-terminated wide character string containing the provider name. - [MarshalAs(UnmanagedType.LPWStr)] - public string m_pwszProviderName; - - /// Provider type. See VSS_PROVIDER_TYPE for more information. - public VSS_PROVIDER_TYPE m_eProviderType; - - /// Null-terminated wide character string containing the provider version in readable format. - [MarshalAs(UnmanagedType.LPWStr)] public string m_pwszProviderVersion; - - /// A VSS_ID (GUID) uniquely identifying the version of a provider. - public Guid m_ProviderVersionId; - - /// Class identifier of the component registered in the local machine's COM catalog. - public Guid m_ClassId; - } - - /// The VSS_SNAPSHOT_PROP structure contains the properties of a shadow copy or shadow copy set. + /// + /// Doubly indirect pointer to an IVssEnumObject enumerator object. Set the value of this parameter to NULL before calling + /// this method. + /// /// + /// The cloned enumerator object will refer to the same list of VSS_OBJECT_PROP structures. /// - /// Requesters typically obtain a pointer to a VSS_SNAPSHOT_PROP structure by using the - /// IVssBackupComponents::GetSnapshotProperties method or the IVssSoftwareSnapshotProvider::GetSnapshotProperties method. When this - /// structure is no longer needed, the caller is responsible for freeing it by using the VssFreeSnapshotProperties function. - /// - /// - /// The shadow copy device object contained in m_pwszSnapshotDeviceObject is used to address files on the shadow copy of the - /// volume. For instance, if the original volume has a file with a path of "\topleveldir\File.html", then the path to the shadow - /// copy of the file is " m_pwszSnapshotDeviceObject"+"\topleveldir\File.html". - /// - /// - /// When a shadow copy is exposed as a share, the value of m_pwszExposedName will be the share name. When the shadow copy is - /// exposed as a drive letter or mounted folder, the shadow copy m_pwszExposedName is a drive letter followed by a colon—for - /// example, "X:" or a mounted folder path (for example, "Y:\MountX"). - /// - /// - /// If a shadow copy is exposed as a drive letter or mounted folder, then (as with mounting any device) the entire shadow copy - /// starting at its root will be exposed at the mount point. In this case, m_pwszExposedPath will be null. - /// - /// - /// If the shadow copy is exposed as a share, the value of m_pwszExposedPath will be the path to the portion of the volume - /// that is shared. + /// The caller must call the Release method of the returned interface pointer to deallocate the system resources held by the + /// IVssEnumObject enumerator object pointed to by the ppEnum parameter. /// /// - // https://docs.microsoft.com/en-us/windows/win32/api/vss/ns-vss-vss_snapshot_prop typedef struct _VSS_SNAPSHOT_PROP { VSS_ID - // m_SnapshotId; VSS_ID m_SnapshotSetId; LONG m_lSnapshotsCount; VSS_PWSZ m_pwszSnapshotDeviceObject; VSS_PWSZ - // m_pwszOriginalVolumeName; VSS_PWSZ m_pwszOriginatingMachine; VSS_PWSZ m_pwszServiceMachine; VSS_PWSZ m_pwszExposedName; VSS_PWSZ - // m_pwszExposedPath; VSS_ID m_ProviderId; LONG m_lSnapshotAttributes; VSS_TIMESTAMP m_tsCreationTimestamp; VSS_SNAPSHOT_STATE - // m_eStatus; } VSS_SNAPSHOT_PROP, *PVSS_SNAPSHOT_PROP; - [PInvokeData("vss.h", MSDNShortId = "NS:vss._VSS_SNAPSHOT_PROP")] - [StructLayout(LayoutKind.Sequential)] - public struct VSS_SNAPSHOT_PROP - { - /// A VSS_ID (GUID) uniquely identifying the shadow copy identifier. - public Guid m_SnapshotId; + // https://docs.microsoft.com/en-us/windows/win32/api/vss/nf-vss-ivssenumobject-clone HRESULT Clone( [in, out] IVssEnumObject + // **ppenum ); + IVssEnumObject Clone(); + } - /// A VSS_ID (GUID) uniquely identifying the shadow copy set containing the shadow copy. - public Guid m_SnapshotSetId; + /// The VSS_OBJECT_PROP structure defines the properties of a provider, volume, shadow copy, or shadow copy set. + /// + /// + /// A requester obtains VSS_OBJECT_PROP structures by using IVssEnumObject::Next to iterate over the list of objects returned by + /// a call to IVssBackupComponents::Query. + /// + /// + /// As its members are filled by a COM interface, prior to deleting the property structures VSS_SNAPSHOT_PROP and VSS_PROVIDER_PROP, the + /// memory they contain must be released by calling CoTaskMemFree for every string and byte array value contained in each structure. + /// + /// In the case of VSS_SNAPSHOT_PROP, this can be done manually, or the utility function VssFreeSnapshotProperties can be used. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vss/ns-vss-vss_object_prop typedef struct _VSS_OBJECT_PROP { VSS_OBJECT_TYPE Type; + // VSS_OBJECT_UNION Obj; } VSS_OBJECT_PROP, *PVSS_OBJECT_PROP; + [PInvokeData("vss.h", MSDNShortId = "NS:vss._VSS_OBJECT_PROP")] + [StructLayout(LayoutKind.Sequential)] + public struct VSS_OBJECT_PROP + { + /// Object type. Refer to VSS_OBJECT_TYPE. + public VSS_OBJECT_TYPE Type; - /// - /// - /// Number of volumes included with the shadow copy in the shadow copy set when it was created. Because it is possible for - /// applications to release individual shadow copies without releasing the shadow copy set, at any given time the number of - /// shadow copies in the shadow copy set may be less than m_LSnapshotsCount. - /// - /// The maximum number of shadow-copied volumes permitted in a shadow copy set is 64. - /// - public int m_lSnapshotsCount; + /// + /// Object properties: a union of VSS_SNAPSHOT_PROP and VSS_PROVIDER_PROP structures. (See VSS_OBJECT_UNION.) + /// + /// It contains information for an object of the type specified by the Type member of the VSS_OBJECT_PROP structure. + /// Objects can be providers, volumes, shadow copies, or shadow copy sets. + /// + /// + public VSS_OBJECT_UNION Obj; + } - /// - /// - /// Null-terminated wide character string containing the name of the device object for the shadow copy of the volume. The device - /// object can be thought of as the root of a shadow copy of a volume. Requesters will use this device name when accessing files - /// on a shadow-copied volume that it needs to work with. - /// - /// The device name does not contain a trailing "". - /// - [MarshalAs(UnmanagedType.LPWStr)] - public string m_pwszSnapshotDeviceObject; + /// + /// The VSS_OBJECT_UNION defines the union of object types that can be defined by the VSS_OBJECT_PROP structure (section 2.2.3.2). + /// + [PInvokeData("vss.h", MSDNShortId = "NS:vss._VSS_OBJECT_PROP")] + [StructLayout(LayoutKind.Explicit)] + public struct VSS_OBJECT_UNION + { + /// The structure specifies a shadow copy object as a VSS_SNAPSHOT_PROP structure (section 2.2.3.3). + [FieldOffset(0)] + public VSS_SNAPSHOT_PROP Snap; - /// Null-terminated wide character string containing the name of the volume that had been shadow copied. - [MarshalAs(UnmanagedType.LPWStr)] - public string m_pwszOriginalVolumeName; + /// + /// The structure specifies a VSS provider object. The Shadow Copy Management Protocol is not used to manage VSS provider objects; + /// therefore, this member MUST NOT be referenced and MUST be ignored on receipt. + /// + [FieldOffset(0)] + public VSS_PROVIDER_PROP Prov; + } - /// Null-terminated wide character string containing the name of the machine containing the original volume. - [MarshalAs(UnmanagedType.LPWStr)] - public string m_pwszOriginatingMachine; + /// The VSS_PROVIDER_PROP structure specifies shadow copy provider properties. + // https://docs.microsoft.com/en-us/windows/win32/api/vss/ns-vss-vss_provider_prop typedef struct _VSS_PROVIDER_PROP { VSS_ID + // m_ProviderId; VSS_PWSZ m_pwszProviderName; VSS_PROVIDER_TYPE m_eProviderType; VSS_PWSZ m_pwszProviderVersion; VSS_ID + // m_ProviderVersionId; CLSID m_ClassId; } VSS_PROVIDER_PROP, *PVSS_PROVIDER_PROP; + [PInvokeData("vss.h", MSDNShortId = "NS:vss._VSS_PROVIDER_PROP")] + [StructLayout(LayoutKind.Sequential)] + public struct VSS_PROVIDER_PROP + { + /// Identifies the provider who supports shadow copies of this class. + public Guid m_ProviderId; - /// - /// Null-terminated wide character string containing the name of the machine running the Volume Shadow Copy Service that created - /// the shadow copy. - /// - [MarshalAs(UnmanagedType.LPWStr)] - public string m_pwszServiceMachine; + /// String containing the provider name. + public StrPtrUni m_pwszProviderName; - /// - /// Null-terminated wide character string containing the name of the shadow copy when it is exposed. This is a drive letter or - /// mounted folder (if the shadow copy is exposed as a local volume), or a share name. Corresponds to the wszExpose parameter of - /// the IVssBackupComponents::ExposeSnapshot method. - /// - [MarshalAs(UnmanagedType.LPWStr)] - public string m_pwszExposedName; + /// Provider type. See VSS_PROVIDER_TYPE for more information. + public VSS_PROVIDER_TYPE m_eProviderType; - /// - /// Null-terminated wide character string indicating the portion of the shadow copy of a volume made available if it is exposed - /// as a share. Corresponds to the wszPathFromRoot parameter of the IVssBackupComponents::ExposeSnapshot method. - /// - [MarshalAs(UnmanagedType.LPWStr)] - public string m_pwszExposedPath; + /// String containing the provider version in readable format. + public StrPtrUni m_pwszProviderVersion; - /// A VSS_ID (GUID) uniquely identifying the provider used to create this shadow copy. - public Guid m_ProviderId; + /// A VSS_ID (GUID) uniquely identifying the version of a provider. + public Guid m_ProviderVersionId; - /// - /// The attributes of the shadow copy expressed as a bit mask (or bitwise OR) of members of the _VSS_VOLUME_SNAPSHOT_ATTRIBUTES enumeration. - /// - public int m_lSnapshotAttributes; + /// Class identifier of the component registered in the local machine's COM catalog. + public Guid m_ClassId; + } - /// - /// Time stamp indicating when the shadow copy was created. The exact time is determined by the provider. See VSS_TIMESTAMP for - /// information about the time-stamp format. - /// - public FILETIME m_tsCreationTimestamp; + /// The VSS_SNAPSHOT_PROP structure contains the properties of a shadow copy or shadow copy set. + /// + /// + /// Requesters typically obtain a pointer to a VSS_SNAPSHOT_PROP structure by using the + /// IVssBackupComponents::GetSnapshotProperties method or the IVssSoftwareSnapshotProvider::GetSnapshotProperties method. When this + /// structure is no longer needed, the caller is responsible for freeing it by using the VssFreeSnapshotProperties function. + /// + /// + /// The shadow copy device object contained in m_pwszSnapshotDeviceObject is used to address files on the shadow copy of the + /// volume. For instance, if the original volume has a file with a path of "\topleveldir\File.html", then the path to the shadow copy of + /// the file is " m_pwszSnapshotDeviceObject"+"\topleveldir\File.html". + /// + /// + /// When a shadow copy is exposed as a share, the value of m_pwszExposedName will be the share name. When the shadow copy is + /// exposed as a drive letter or mounted folder, the shadow copy m_pwszExposedName is a drive letter followed by a colon—for + /// example, "X:" or a mounted folder path (for example, "Y:\MountX"). + /// + /// + /// If a shadow copy is exposed as a drive letter or mounted folder, then (as with mounting any device) the entire shadow copy starting + /// at its root will be exposed at the mount point. In this case, m_pwszExposedPath will be null. + /// + /// + /// If the shadow copy is exposed as a share, the value of m_pwszExposedPath will be the path to the portion of the volume that + /// is shared. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vss/ns-vss-vss_snapshot_prop typedef struct _VSS_SNAPSHOT_PROP { VSS_ID + // m_SnapshotId; VSS_ID m_SnapshotSetId; LONG m_lSnapshotsCount; VSS_PWSZ m_pwszSnapshotDeviceObject; VSS_PWSZ m_pwszOriginalVolumeName; + // VSS_PWSZ m_pwszOriginatingMachine; VSS_PWSZ m_pwszServiceMachine; VSS_PWSZ m_pwszExposedName; VSS_PWSZ m_pwszExposedPath; VSS_ID + // m_ProviderId; LONG m_lSnapshotAttributes; VSS_TIMESTAMP m_tsCreationTimestamp; VSS_SNAPSHOT_STATE m_eStatus; } VSS_SNAPSHOT_PROP, *PVSS_SNAPSHOT_PROP; + [PInvokeData("vss.h", MSDNShortId = "NS:vss._VSS_SNAPSHOT_PROP")] + [StructLayout(LayoutKind.Sequential)] + public struct VSS_SNAPSHOT_PROP + { + /// A VSS_ID (GUID) uniquely identifying the shadow copy identifier. + public Guid m_SnapshotId; - /// Current shadow copy creation status. See VSS_SNAPSHOT_STATE. - public VSS_SNAPSHOT_STATE m_eStatus; - } + /// A VSS_ID (GUID) uniquely identifying the shadow copy set containing the shadow copy. + public Guid m_SnapshotSetId; + + /// + /// + /// Number of volumes included with the shadow copy in the shadow copy set when it was created. Because it is possible for + /// applications to release individual shadow copies without releasing the shadow copy set, at any given time the number of shadow + /// copies in the shadow copy set may be less than m_LSnapshotsCount. + /// + /// The maximum number of shadow-copied volumes permitted in a shadow copy set is 64. + /// + public int m_lSnapshotsCount; + + /// + /// + /// String containing the name of the device object for the shadow copy of the volume. The device object can be thought of as the + /// root of a shadow copy of a volume. Requesters will use this device name when accessing files on a shadow-copied volume that it + /// needs to work with. + /// + /// The device name does not contain a trailing "". + /// + public StrPtrUni m_pwszSnapshotDeviceObject; + + /// String containing the name of the volume that had been shadow copied. + public StrPtrUni m_pwszOriginalVolumeName; + + /// String containing the name of the machine containing the original volume. + public StrPtrUni m_pwszOriginatingMachine; + + /// String containing the name of the machine running the Volume Shadow Copy Service that created the shadow copy. + public StrPtrUni m_pwszServiceMachine; + + /// + /// String containing the name of the shadow copy when it is exposed. This is a drive letter or mounted folder (if the shadow copy + /// is exposed as a local volume), or a share name. Corresponds to the wszExpose parameter of the + /// IVssBackupComponents::ExposeSnapshot method. + /// + public StrPtrUni m_pwszExposedName; + + /// + /// String indicating the portion of the shadow copy of a volume made available if it is exposed as a share. Corresponds to the + /// wszPathFromRoot parameter of the IVssBackupComponents::ExposeSnapshot method. + /// + public StrPtrUni m_pwszExposedPath; + + /// A VSS_ID (GUID) uniquely identifying the provider used to create this shadow copy. + public Guid m_ProviderId; + + /// + /// The attributes of the shadow copy expressed as a bit mask (or bitwise OR) of members of the _VSS_VOLUME_SNAPSHOT_ATTRIBUTES enumeration. + /// + public VSS_VOLUME_SNAPSHOT_ATTRIBUTES m_lSnapshotAttributes; + + /// + /// Time stamp indicating when the shadow copy was created. The exact time is determined by the provider. See VSS_TIMESTAMP for + /// information about the time-stamp format. + /// + public FILETIME m_tsCreationTimestamp; + + /// Current shadow copy creation status. See VSS_SNAPSHOT_STATE. + public VSS_SNAPSHOT_STATE m_eStatus; } } \ No newline at end of file diff --git a/PInvoke/VssApi/vswriter.cs b/PInvoke/VssApi/vswriter.cs index e43f5e02..9429ac6d 100644 --- a/PInvoke/VssApi/vswriter.cs +++ b/PInvoke/VssApi/vswriter.cs @@ -1,1623 +1,1403 @@ using System; +using System.Collections; +using System.Collections.Generic; using System.Runtime.InteropServices; -using FILETIME = System.Runtime.InteropServices.ComTypes.FILETIME; -namespace Vanara.PInvoke +namespace Vanara.PInvoke.VssApi { - public static partial class VssApi + /// + /// + /// The VSS_ALTERNATE_WRITER_STATE enumeration is used to indicate whether a given writer has an associated alternate writer. The + /// existence of an alternate writer is set during writer initialization by CVssWriter::Initialize. + /// + /// Currently, the only supported value for a method taking a VSS_ALTERNATE_WRITER_STATE argument is VSS_AWS_NO_ALTERNATE_WRITER. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/ne-vswriter-vss_alternate_writer_state typedef enum + // VSS_ALTERNATE_WRITER_STATE { VSS_AWS_UNDEFINED, VSS_AWS_NO_ALTERNATE_WRITER, VSS_AWS_ALTERNATE_WRITER_EXISTS, + // VSS_AWS_THIS_IS_ALTERNATE_WRITER } ; + [PInvokeData("vswriter.h", MSDNShortId = "NE:vswriter.VSS_ALTERNATE_WRITER_STATE")] + public enum VSS_ALTERNATE_WRITER_STATE + { + /// + /// No information is available as to the existence of an alternate writer. This value indicates an application + /// error. This enumeration value is reserved for future use. + /// + VSS_AWS_UNDEFINED = 0, + + /// A given writer does not have an alternate writer. + VSS_AWS_NO_ALTERNATE_WRITER, + + /// + /// An alternate writer exists. This alternate writer runs when the writer is not available. This enumeration + /// value is reserved for future use. + /// + VSS_AWS_ALTERNATE_WRITER_EXISTS, + + /// The writer in question is an alternate writer. This enumeration value is reserved for future use. + VSS_AWS_THIS_IS_ALTERNATE_WRITER, + } + + /// + /// The VSS_COMPONENT_FLAGS enumeration is used by writers to indicate support for auto-recovery. These values are used in the + /// dwComponentFlags member of the VSS_COMPONENTINFO structure and the dwComponentFlags parameter of the + /// IVssCreateWriterMetadata::AddComponent method. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/ne-vswriter-vss_component_flags typedef enum VSS_COMPONENT_FLAGS { + // VSS_CF_BACKUP_RECOVERY, VSS_CF_APP_ROLLBACK_RECOVERY, VSS_CF_NOT_SYSTEM_STATE } ; + [PInvokeData("vswriter.h", MSDNShortId = "NE:vswriter.VSS_COMPONENT_FLAGS")] + [Flags] + public enum VSS_COMPONENT_FLAGS + { + /// + /// The writer will need write access to this component after the shadow copy has been created. + /// This flag can be used together with the + /// VSS_VOLSNAP_ATTR_TRANSPORTABLE + /// value of the + /// _VSS_VOLUME_SNAPSHOT_ATTRIBUTES + /// enumeration if the VSS hardware provider supports LUN masking. + /// Windows Vista and Windows Server 2003 with SP1: + /// This flag is incompatible with + /// VSS_VOLSNAP_ATTR_TRANSPORTABLE + /// . + /// This flag is not supported for express writers. + /// + VSS_CF_BACKUP_RECOVERY = 0x01, + + /// + /// If this is a rollback shadow copy + /// (see the + /// VSS_VOLSNAP_ATTR_ROLLBACK_RECOVERY + /// value of the + /// _VSS_VOLUME_SNAPSHOT_ATTRIBUTES + /// enumeration), the writer for this + /// component will need write access to this component after the shadow copy has been created. + /// This flag can be used together with the + /// VSS_VOLSNAP_ATTR_TRANSPORTABLE + /// value of the + /// _VSS_VOLUME_SNAPSHOT_ATTRIBUTES + /// enumeration if the VSS hardware provider supports LUN masking. + /// Windows Vista and Windows Server 2003 with SP1: + /// This flag is incompatible with + /// VSS_VOLSNAP_ATTR_TRANSPORTABLE + /// . + /// This flag is not supported for express writers. + /// + VSS_CF_APP_ROLLBACK_RECOVERY = 0x02, + + /// + /// This component is not part of system state. + /// Windows Server 2003 with SP1: + /// This value is not supported until Windows Vista. + /// + VSS_CF_NOT_SYSTEM_STATE = 0x04, + } + + /// + /// The VSS_COMPONENT_TYPE enumeration is used by both the requester and the writer to specify the type of component being used + /// with a shadow copy backup operation. + /// + /// + /// A writer sets a component's type when it adds the component to its Writer Metadata Document using IVssCreateWriterMetadata::AddComponent. + /// + /// Writers and requesters can find the type information of components selected for inclusion in a Backup Components Document through + /// calls to IVssComponent::GetComponentType to return a component type directly. + /// + /// A requester can obtain the type of any component in a given writer's Writer Metadata Document by doing the following: + /// + /// + /// Using IVssExamineWriterMetadata::GetComponent to obtain a IVssWMComponent interface + /// + /// + /// Using IVssWMComponent::GetComponentInfo to return a VSS_COMPONENTINFO structure + /// + /// + /// Examining the Type member of the VSS_COMPONENTINFO object + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/ne-vswriter-vss_component_type typedef enum VSS_COMPONENT_TYPE { + // VSS_CT_UNDEFINED, VSS_CT_DATABASE, VSS_CT_FILEGROUP } ; + [PInvokeData("vswriter.h", MSDNShortId = "NE:vswriter.VSS_COMPONENT_TYPE")] + public enum VSS_COMPONENT_TYPE + { + /// + /// Undefined component type. + /// This value indicates an application error. + /// + VSS_CT_UNDEFINED = 0, + + /// Database component. + VSS_CT_DATABASE, + + /// File group component. This is any component other than a database. + VSS_CT_FILEGROUP, + } + + /// + /// The VSS_FILE_RESTORE_STATUS enumeration defines the set of statuses of a file restore operation performed on the files + /// managed by a selected component or component set (see Working with Selectability and Logical Paths for information on selecting components). + /// + /// + /// + /// If any files managed by a component or, if it defines a component set, any of its subcomponents cannot be restored, the value of + /// VSS_FILE_RESTORE_STATUS must indicate an error. + /// + /// Both the values VSS_RS_FAILED and VSS_RS_NONE indicate that a restore operation did not complete successfully: + /// + /// + /// + /// VSS_RS_NONE indicates a restore failed gracefully: no files from the component or its subcomponents were restored to disk. + /// + /// + /// + /// VSS_RS_FAIL indicates a restore failed gracelessly, leaving some files restored to disk and some files unrestored. + /// + /// + /// + /// Requesters must set a restore status (using IVssBackupComponents::SetFileRestoreStatus) for every component (and its component set, + /// if it defines one) explicitly added for restore to the Backup Components Document (using either + /// IVssBackupComponents::SetSelectedForRestore or IVssBackupComponents::AddRestoreSubcomponent). + /// + /// + /// Writers and requesters can query the status of the restoration of a component or a component set defined by a selectable component + /// with calls to IVssComponent::GetFileRestoreStatus. If this method is called for a component that was not selected, the value + /// returned is undefined. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/ne-vswriter-vss_file_restore_status typedef enum VSS_FILE_RESTORE_STATUS + // { VSS_RS_UNDEFINED, VSS_RS_NONE, VSS_RS_ALL, VSS_RS_FAILED } ; + [PInvokeData("vswriter.h", MSDNShortId = "NE:vswriter.VSS_FILE_RESTORE_STATUS")] + public enum VSS_FILE_RESTORE_STATUS + { + /// + /// The restore state is undefined. + /// This value indicates an error, or indicates that a restore operation has not yet started. + /// This value is not supported for components that are owned by express writers. + /// + VSS_RS_UNDEFINED = 0, + + /// + /// No files were restored. + /// This value indicates an error in restoration that did not leave any restored files on disk. + /// + VSS_RS_NONE, + + /// + /// All files were restored. This value indicates success and should be set for each component that was + /// restored successfully. + /// + VSS_RS_ALL, + + /// + /// The restore process failed. + /// This value indicates an error in restoration that did leave some restored files on disk. This means the + /// components on disk are now corrupt. + /// + VSS_RS_FAILED, + } + + /// + /// + /// The VSS_RESTORE_TARGET enumeration is used by a writer at restore time to indicate how all the files included in a selected + /// component, and all the files in any component set it defines, are to be restored. (See Working with Selectability and Logical Paths + /// for information on selecting components.) + /// + /// Setting a restore target modifies or overrides the restore method set during backup (see VSS_RESTOREMETHOD_ENUM). + /// + /// + /// A target of VSS_RT_UNDEFINED indicates an error state. + /// + /// At backup time, writers set the default restore behavior by indicating a restore method (VSS_RESTOREMETHOD_ENUM) set with IVssCreateWriterMetadata::SetRestoreMethod. + /// + /// + /// If a writer does not explicitly set the restore target of a component and any component set it defines, by default it is set to VSS_RT_ORIGINAL. + /// + /// + /// At restore time, a VSS_RESTORE_TARGET value other than VSS_RT_ORIGINAL overrides the value of the originally specified + /// restore method specified by VSS_RESTOREMETHOD_ENUM and set by IVssCreateWriterMetadata::SetRestoreMethod. + /// + /// + /// Only writers (using IVssComponent::SetRestoreTarget) can set a restore target ( VSS_RESTORE_TARGET) and change how files are + /// restored overriding the restore method). + /// + /// Requesters and writers can access the current restore target through IVssComponent::GetRestoreTarget. + /// + /// A restore target of VSS_RT_ORIGINAL does not mean that files should be restored to their original location, but that the + /// originally specified restore method (VSS_RESTOREMETHOD_ENUM) must be respected. For instance, if a writer set a restore method of + /// VSS_RME_RESTORE_TO_ALTERNATE_LOCATION for a selected component and the restore target is VSS_RT_ORIGINAL, files should + /// be restored to the alternate location defined by the writer. + /// + /// + /// (In this example, if a writer has failed to define alternate location mappings, then it is a writer error, and the requester should + /// report it.) + /// + /// + /// A restore target of VSS_RT_ALTERNATE without an alternate location mapping defined constitutes a writer error, and the + /// requester should report it as such. + /// + /// See Non-Default Backup And Restore Locations for more information. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/ne-vswriter-vss_restore_target typedef enum VSS_RESTORE_TARGET { + // VSS_RT_UNDEFINED, VSS_RT_ORIGINAL, VSS_RT_ALTERNATE, VSS_RT_DIRECTED, VSS_RT_ORIGINAL_LOCATION } ; + [PInvokeData("vswriter.h", MSDNShortId = "NE:vswriter.VSS_RESTORE_TARGET")] + public enum VSS_RESTORE_TARGET + { + /// + /// No target is defined. + /// This value indicates an error on the part of the writer. + /// This value is not supported for express writers. + /// + VSS_RT_UNDEFINED = 0, + + /// + /// This is the default restore target. + /// This value indicates that the restoration of the files included in a selected component (or the component set + /// defined by that component) should proceed according to the original restore method specified at backup time by + /// a + /// VSS_RESTOREMETHOD_ENUM + /// value. + /// + VSS_RT_ORIGINAL, + + /// + /// The files are restored to a location determined from an existing alternate location mapping. + /// The restore target should be set to + /// VSS_RT_ALTERNATE + /// only when alternate location + /// mappings have been set for all the files managed by a selected component or component set. + /// This value is not supported for express writers. + /// + VSS_RT_ALTERNATE, + + /// + /// Use directed targeting by the writer at restore time to restore a file. + /// Directed targeting allows a writer to control, on a file-by-file basis, how a file is + /// restored—indicating how much of a file is to be restored and into which files the + /// backed-up file is to be restored. + /// This value is not supported for express writers. + /// + VSS_RT_DIRECTED, + + /// + /// The files are restored to the location at which they were at backup time, even if the original + /// restore method that was specified at backup time was + /// VSS_RME_RESTORE_TO_ALTERNATE_LOCATION + /// . + /// Windows Server 2003 and Windows XP: + /// This value is not supported. + /// This value is not supported for express writers. + /// + VSS_RT_ORIGINAL_LOCATION, + } + + /// + /// + /// The VSS_RESTOREMETHOD_ENUM enumeration is used by a writer at backup time to specify through its Writer Metadata Document the + /// default file restore method to be used with all the files in all the components it manages. + /// + /// + /// The restore method is writer-wide and is also referred to as the original restore target and indicated by a VSS_RESTORE_TARGET value + /// of VSS_RT_ORIGINAL. + /// + /// + /// + /// + /// A writer sets the restore method in the Writer Metadata Document by calling IVssCreateWriterMetadata::SetRestoreMethod during backup + /// to specify its desired restore method in its metadata. + /// + /// + /// A requester retrieves a writer's requested restore method by calling IVssExamineWriterMetadata::GetRestoreMethod and acts accordingly. + /// + /// The restore method applies to all files in all components of a given writer. + /// + /// The restore method may be overridden on a component-by-component basis at restore time if a writer sets a VSS_RESTORE_TARGET value + /// other than VSS_RT_ORIGINAL with IVssComponent::SetRestoreTarget. + /// + /// + /// A restore method of VSS_RME_RESTORE_TO_ALTERNATE_LOCATION without an alternate location mapping defined constitutes a writer + /// error, and the requester should report it as such. + /// + /// + /// When a restore method requires a check on the status of files currently on disk ( VSS_RME_RESTORE_IF_NOT_THERE, + /// VSS_RME_RESTORE_IF_CAN_REPLACE, or VSS_RME_RESTORE_AT_REBOOT_IF_CANNOT_REPLACE), ideally, you should use file I/O + /// operations to verify that an entire component can be restored before actually proceeding with the restore. + /// + /// The safest way to do this would be to open exclusively (no-sharing) all the target files with CreateFile prior to the restore. + /// In the case of VSS_RME_RESTORE_IF_NOT_THERE, a creation disposition flag of CREATE_NEW should also be set. + /// + /// If the open operations succeed, the restore can proceed and should use the handles returned by CreateFile to actually write restored + /// data to disk. + /// + /// + /// If not, an error can be returned—depending on the method—or alternate location mapping checked and (if it is available) used, or the + /// components files staged for restore at the next reboot. + /// + /// This may be a problem for very large components (some of which may have thousands of files), due to system overhead. + /// In this case, an available though less reliable option is to do the following: + /// + /// + /// Copy all files currently on disk and to be restored to a temporary cache. + /// + /// + /// + /// Attempt to replace the files currently on disk with the backed-up files (which could be either on disk in a second temporary area, + /// or on a backup medium). + /// + /// + /// + /// + /// If any files fail to restore, then terminate the restore operation and copy the original files back from their temporary location + /// and proceed with alternate location mapping or restore on reboot operations. + /// + /// + /// + /// For more information on backup and restore file locations under VSS, see Non-Default Backup And Restore Locations. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/ne-vswriter-vss_restoremethod_enum typedef enum VSS_RESTOREMETHOD_ENUM { + // VSS_RME_UNDEFINED, VSS_RME_RESTORE_IF_NOT_THERE, VSS_RME_RESTORE_IF_CAN_REPLACE, VSS_RME_STOP_RESTORE_START, + // VSS_RME_RESTORE_TO_ALTERNATE_LOCATION, VSS_RME_RESTORE_AT_REBOOT, VSS_RME_RESTORE_AT_REBOOT_IF_CANNOT_REPLACE, VSS_RME_CUSTOM, + // VSS_RME_RESTORE_STOP_START } ; + [PInvokeData("vswriter.h", MSDNShortId = "NE:vswriter.VSS_RESTOREMETHOD_ENUM")] + public enum VSS_RESTOREMETHOD_ENUM + { + /// + /// No restore method is defined. + /// This indicates an error on the part of the writer. + /// This value is not supported for express writers. + /// + VSS_RME_UNDEFINED = 0, + + /// + /// The requester should restore the files of a selected component or component set only if there are no versions of + /// those files currently on the disk. + /// Unless alternate location mappings are defined for file restoration, if a version of any file managed by a + /// selected component or component set is currently on the disk, none of the files managed by the selected + /// component or component set should be restored. + /// If a file's alternate location mapping is defined, and a version of the files is present on disk at the + /// original location, files should be written to the alternate location only if no version of the file exists at + /// the alternate location. + /// + VSS_RME_RESTORE_IF_NOT_THERE, + + /// + /// + /// The requester should restore files of a selected component or component set only if the files currently on the disk can be overwritten. + /// + /// Unless alternate location mappings are defined for file restoration, if there is a version of any file that + /// cannot be overwritten of the selected component or component set on the disk, none of the files managed by the + /// component or component set should be restored. + /// If a file's alternate location mapping is defined, files should be written to the alternate location. + /// + VSS_RME_RESTORE_IF_CAN_REPLACE, + + /// + /// The requester should perform the restore operation as follows: + /// + /// + /// Send the PreRestore event and wait for all writers to process it. + /// + /// + /// Stop the service. + /// + /// + /// Restore the files to their original locations. + /// + /// + /// Restart the service. + /// + /// + /// Send the PostRestore event and wait for all writers to process it. + /// + /// + /// The service to be stopped is specified the writer beforehand when it calls the + /// IVssCreateWriterMetadata::SetRestoreMethod + /// method. The requester can obtain the name of the service by calling the + /// IVssExamineWriterMetadata::GetRestoreMethod + /// method. + /// Note that if the writer is hosted in the service that is being stopped, that writer will not receive the + /// PostRestore + /// event, because the writer instance ID changes when the service is stopped and restarted. + /// + VSS_RME_STOP_RESTORE_START, + + /// + /// The requester should restore the files of the selected component or component set to the location specified by the + /// alternate location mapping specified in the writer component metadata file. (See + /// IVssCreateWriterMetadata::AddAlternateLocationMapping + /// , + /// IVssComponent::GetAlternateLocationMapping + /// , + /// IVssExamineWriterMetadata::GetAlternateLocationMapping + /// , + /// and + /// IVssWMFiledesc::GetAlternateLocation + /// .) + /// This value is not supported for express writers. + /// + VSS_RME_RESTORE_TO_ALTERNATE_LOCATION, + + /// + /// The requester should restore the files of a selected component or component set after the computer is restarted. + /// The files to be restored should be copied to a temporary location, and the requester should use + /// MoveFileEx + /// with the + /// MOVEFILE_DELAY_UNTIL_REBOOT + /// flag to complete the restoration of these files to their + /// proper location after the computer is restarted. + /// + VSS_RME_RESTORE_AT_REBOOT, + + /// + /// If possible, the requester should restore the files of the selected component or component set to their correct + /// location immediately. + /// If there are versions of any of the files managed by the selected component or component set on the disk that + /// cannot be overwritten, then all the files managed by the selected component or component set should be restored + /// after the computer is restarted. + /// In this case, files to be restored should be copied to a temporary location on disk, and the requester should + /// use + /// MoveFileEx + /// with the + /// MOVEFILE_DELAY_UNTIL_REBOOT + /// flag to complete the restoration of these files to their + /// proper location after the computer is restarted. + /// + VSS_RME_RESTORE_AT_REBOOT_IF_CANNOT_REPLACE, + + /// + /// The requester should use a custom restore method to restore the files that are managed by the selected + /// component or component set. + /// A custom restore may use file retrieval API functions or protocols that are private to a given writer + /// application. Such a restore need not use the information in the writer component metadata file. (See + /// Custom Backups and Restores + /// for more + /// information.) + /// This value is not supported for express writers. + /// + VSS_RME_CUSTOM, + + /// + /// The requester should perform the restore operation as follows: + /// + /// + /// Send the PreRestore event and wait for all writers to process it. + /// + /// + /// Restore the files to their original locations. + /// + /// + /// Send the PostRestore event and wait for all writers to process it. + /// + /// + /// Stop the service. + /// + /// + /// Restart the service. + /// + /// + /// The service to be stopped is specified by the writer beforehand when it calls the + /// IVssCreateWriterMetadata::SetRestoreMethod + /// method. The requester can obtain the name of the service by calling the + /// IVssExamineWriterMetadata::GetRestoreMethod + /// method. + /// + VSS_RME_RESTORE_STOP_START, + } + + /// The VSS_SOURCE_TYPE enumeration specifies the type of data that a writer manages. + /// + /// + /// The source type of the data that a writer manages is specified when it initializes its cooperation with the shadow copy mechanism + /// through a call to CVssWriter::Initialize. + /// + /// Information about the source type of the data that a writer manages can be retrieved through its metadata using IVssExamineWriterMetadata::GetIdentity. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/ne-vswriter-vss_source_type typedef enum VSS_SOURCE_TYPE { + // VSS_ST_UNDEFINED, VSS_ST_TRANSACTEDDB, VSS_ST_NONTRANSACTEDDB, VSS_ST_OTHER } ; + [PInvokeData("vswriter.h", MSDNShortId = "NE:vswriter.VSS_SOURCE_TYPE")] + public enum VSS_SOURCE_TYPE + { + /// + /// The source of the data is not known. + /// This indicates a writer error, and the requester should report it. + /// + VSS_ST_UNDEFINED = 0, + + /// The source of the data is a database that supports transactions, such as Microsoft SQL Server. + VSS_ST_TRANSACTEDDB, + + /// The source of the data is a database that does not support transactions. + VSS_ST_NONTRANSACTEDDB, + + /// + /// Unclassified source type—data will be in a file group. + /// This is the default source type. + /// + VSS_ST_OTHER, + } + + /// + /// The VSS_SUBSCRIBE_MASK enumeration is used by a writer when subscribing to the VSS service. It indicates the events that the + /// writer is willing to receive. + /// + /// + /// A bit mask (or bitwise OR) of VSS_SUBSCRIBE_MASK values is used as an argument only to CVssWriter::Subscribe. + /// Currently, the only supported VSS_SUBSCRIBE_MASK bit mask is ( VSS_SM_BACKUP_EVENTS_FLAG | VSS_SM_RESTORE_EVENTS_FLAG). + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/ne-vswriter-vss_subscribe_mask typedef enum VSS_SUBSCRIBE_MASK { + // VSS_SM_POST_SNAPSHOT_FLAG, VSS_SM_BACKUP_EVENTS_FLAG, VSS_SM_RESTORE_EVENTS_FLAG, VSS_SM_IO_THROTTLING_FLAG, VSS_SM_ALL_FLAGS } ; + [PInvokeData("vswriter.h", MSDNShortId = "NE:vswriter.VSS_SUBSCRIBE_MASK")] + [Flags] + public enum VSS_SUBSCRIBE_MASK : uint + { + /// + /// This enumeration value is reserved for future use. + /// Specifies that the writer expects to be notified after the shadow copy it is participating in has completed. + /// It will then call + /// CVssWriter::OnPostSnapshot + /// . + /// + VSS_SM_POST_SNAPSHOT_FLAG = 0x01, + + /// + /// Currently, + /// VSS_SM_BACKUP_EVENTS_FLAG + /// can be used as an argument only when + /// combined through a bitwise OR with + /// VSS_SM_RESTORE_EVENTS_FLAG + /// . + /// Specifies that the writer can expect to receive the following events: + /// + /// + /// A PrepareForSnapshot event when the writer will call CVssWriter::OnPrepareSnapshot. + /// + /// + /// A PrepareForBackup event when the writer will call CVssWriter::OnPrepareBackup. + /// + /// + /// A Freeze event when the writer will call CVssWriter::OnFreeze. + /// + /// + /// A BackupComplete event when the writer will call CVssWriter::OnBackupComplete. + /// + /// + /// A Thaw event when the writer will call CVssWriter::OnThaw. + /// + /// + /// A PostSnapshot event when the writer will call CVssWriter::OnPostSnapshot. + /// + /// + /// + VSS_SM_BACKUP_EVENTS_FLAG = 0x02, + + /// + /// Currently, + /// VSS_SM_RESTORE_EVENTS_FLAG + /// can be used as an argument only when + /// combined through a bitwise OR with + /// VSS_SM_BACKUP_EVENTS_FLAG + /// . + /// Specifies that the writer can expect to receive the following events: + /// + /// + /// A PreRestore event when the writer will call CVssWriter::OnPreRestore. + /// + /// + /// A PostRestore event when the writer will call CVssWriter::OnPostRestore. + /// + /// + /// + VSS_SM_RESTORE_EVENTS_FLAG = 0x04, + + /// This enumeration value is reserved for future use. + VSS_SM_IO_THROTTLING_FLAG = 0x08, + + /// + /// This enumeration value is reserved for future use. + /// Specifies that the writer expects to be notified for all events. + /// + VSS_SM_ALL_FLAGS = 0xFFFFFFFF, + } + + /// + /// The VSS_USAGE_TYPE enumeration specifies how the host system uses the data managed by a writer involved in a VSS operation. + /// + /// + /// + /// The usage type of the data that a writer manages is specified when it initializes its cooperation with the shadow copy mechanism + /// through CVssWriter::Initialize. + /// + /// Information about the usage type of the data that a writer manages can be retrieved through its metadata using IVssExamineWriterMetadata::GetIdentity. + /// + /// Requester applications that are interested in backing up system state should look for writers with the + /// VSS_UT_BOOTABLESYSTEMSTATE or VSS_UT_SYSTEMSERVICE usage type. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/ne-vswriter-vss_usage_type typedef enum VSS_USAGE_TYPE { + // VSS_UT_UNDEFINED, VSS_UT_BOOTABLESYSTEMSTATE, VSS_UT_SYSTEMSERVICE, VSS_UT_USERDATA, VSS_UT_OTHER } ; + [PInvokeData("vswriter.h", MSDNShortId = "NE:vswriter.VSS_USAGE_TYPE")] + public enum VSS_USAGE_TYPE + { + /// + /// The usage type is not known. + /// This indicates an error on the part of the writer. + /// + VSS_UT_UNDEFINED = 0, + + /// The data stored by the writer is part of the bootable system state. + VSS_UT_BOOTABLESYSTEMSTATE, + + /// The writer either stores data used by a system service or is a system service itself. + VSS_UT_SYSTEMSERVICE, + + /// The data is user data. + VSS_UT_USERDATA, + + /// Unclassified data. + VSS_UT_OTHER, + } + + /// + /// The VSS_WRITERRESTORE_ENUM enumeration is used by a writer to indicate to a requester the conditions under which it will + /// handle events generated during a restore operation. + /// + /// + /// + /// A writer passes a value of VSS_WRITERRESTORE_ENUM to IVssCreateWriterMetadata::SetRestoreMethod to indicate through its + /// metadata how it interacts with requesters during a restore operation. + /// + /// A requester retrieves information about a writer's participation by calling IVssExamineWriterMetadata::GetRestoreMethod. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/ne-vswriter-vss_writerrestore_enum typedef enum VSS_WRITERRESTORE_ENUM { + // VSS_WRE_UNDEFINED, VSS_WRE_NEVER, VSS_WRE_IF_REPLACE_FAILS, VSS_WRE_ALWAYS } ; + [PInvokeData("vswriter.h", MSDNShortId = "NE:vswriter.VSS_WRITERRESTORE_ENUM")] + public enum VSS_WRITERRESTORE_ENUM + { + /// + /// It is not known whether the writer will perform special operations during the restore operation. + /// This state indicates a writer error. + /// + VSS_WRE_UNDEFINED = 0, + + /// The writer does not require restore events. + VSS_WRE_NEVER, + + /// + /// Indicates that the writer always expects to handle a + /// PreRestore + /// ( + /// CvssWriter::OnPreRestore + /// ) event, but expects + /// to handle a + /// PostRestore + /// event + /// ( + /// CvssWriter::OnPostRestore + /// ) only if a restore + /// fails when implementing either a + /// VSS_RME_RESTORE_IF_NOT_THERE + /// or + /// VSS_RME_RESTORE_IF_CAN_REPLACE + /// restore method + /// ( + /// VSS_RESTOREMETHOD_ENUM + /// ). + /// + VSS_WRE_IF_REPLACE_FAILS, + + /// The writer always performs special operations during the restore operation. + VSS_WRE_ALWAYS, + } + + /// Defines methods to manipulate a list that can be appended. + /// The type of the elements in the collection. + public interface IAppendOnlyList : IReadOnlyList + { + /// Adds an item to the list. + /// The object to add to the list. + void Add(T item); + } + + /// + /// + /// The IVssComponent interface is a C++ (not COM) interface containing methods for examining and modifying information about + /// components contained in a requester's Backup Components Document. + /// + /// + /// 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 IVssBackupComponents::AddComponent method. + /// + /// + /// Information about components explicitly added during a restore operation using IVssBackupComponents::AddRestoreSubcomponent are not + /// available through the IVssComponent interface. + /// + /// + /// Some information common to both components and implicitly selected subcomponents available through IVssComponent objects + /// includes the following: + /// + /// + /// + /// Backup time stamp + /// + /// + /// Pre-/post-restore Failure Messages + /// + /// + /// Restore metadata + /// + /// + /// Restore target + /// + /// + /// + /// Some information in the IVssComponent object is on a per-file basis and can refer to files managed either by explicitly + /// selected components or by implicitly selected subcomponents: + /// + /// + /// + /// Alternate location mappings + /// + /// + /// Partial files + /// + /// + /// Directed target + /// + /// + /// + /// Other information is not included in the Backup Components Document and can be inferred using the IVssComponent object in + /// conjunction with the appropriate Writer Metadata Documents based on a writer's component hierarchy expressed in the logical paths + /// (see Working with Selectability and Logical Paths). + /// + /// + /// The interface can be used by either a writer or a requester, although certain methods are supported only for writers. In this way, a + /// writer can request changes in a backup or restore operation, such as adding a new target, or learn of requester actions, such as the + /// use of an alternate location. + /// + /// The following methods return an IVssComponent interface: + /// + /// + /// IVssWriterComponents::GetComponent + /// + /// + /// IVssWriterComponentsExt::GetComponent + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nl-vswriter-ivsscomponent + [PInvokeData("vswriter.h", MSDNShortId = "NL:vswriter.IVssComponent")] + public interface IVssComponent { /// /// - /// The VSS_ALTERNATE_WRITER_STATE enumeration is used to indicate whether a given writer has an associated alternate writer. - /// The existence of an alternate writer is set during writer initialization by CVssWriter::Initialize. + /// The GetAdditionalRestores method 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. /// - /// Currently, the only supported value for a method taking a VSS_ALTERNATE_WRITER_STATE argument is VSS_AWS_NO_ALTERNATE_WRITER. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/ne-vswriter-vss_alternate_writer_state typedef enum - // VSS_ALTERNATE_WRITER_STATE { VSS_AWS_UNDEFINED, VSS_AWS_NO_ALTERNATE_WRITER, VSS_AWS_ALTERNATE_WRITER_EXISTS, - // VSS_AWS_THIS_IS_ALTERNATE_WRITER } ; - [PInvokeData("vswriter.h", MSDNShortId = "NE:vswriter.VSS_ALTERNATE_WRITER_STATE")] - public enum VSS_ALTERNATE_WRITER_STATE - { - /// - /// No information is available as to the existence of an alternate writer. This value indicates an application - /// error. This enumeration value is reserved for future use. - /// - VSS_AWS_UNDEFINED = 0, - - /// A given writer does not have an alternate writer. - VSS_AWS_NO_ALTERNATE_WRITER, - - /// - /// An alternate writer exists. This alternate writer runs when the writer is not available. This enumeration - /// value is reserved for future use. - /// - VSS_AWS_ALTERNATE_WRITER_EXISTS, - - /// The writer in question is an alternate writer. This enumeration value is reserved for future use. - VSS_AWS_THIS_IS_ALTERNATE_WRITER, - } - - /// - /// The VSS_COMPONENT_FLAGS enumeration is used by writers to indicate support for auto-recovery. These values are used in - /// the dwComponentFlags member of the VSS_COMPONENTINFO structure and the dwComponentFlags parameter of the - /// IVssCreateWriterMetadata::AddComponent method. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/ne-vswriter-vss_component_flags typedef enum VSS_COMPONENT_FLAGS { - // VSS_CF_BACKUP_RECOVERY, VSS_CF_APP_ROLLBACK_RECOVERY, VSS_CF_NOT_SYSTEM_STATE } ; - [PInvokeData("vswriter.h", MSDNShortId = "NE:vswriter.VSS_COMPONENT_FLAGS")] - [Flags] - public enum VSS_COMPONENT_FLAGS - { - /// - /// The writer will need write access to this component after the shadow copy has been created. - /// This flag can be used together with the - /// VSS_VOLSNAP_ATTR_TRANSPORTABLE - /// value of the - /// _VSS_VOLUME_SNAPSHOT_ATTRIBUTES - /// enumeration if the VSS hardware provider supports LUN masking. - /// Windows Vista and Windows Server 2003 with SP1: - /// This flag is incompatible with - /// VSS_VOLSNAP_ATTR_TRANSPORTABLE - /// . - /// This flag is not supported for express writers. - /// - VSS_CF_BACKUP_RECOVERY = 0x01, - - /// - /// If this is a rollback shadow copy - /// (see the - /// VSS_VOLSNAP_ATTR_ROLLBACK_RECOVERY - /// value of the - /// _VSS_VOLUME_SNAPSHOT_ATTRIBUTES - /// enumeration), the writer for this - /// component will need write access to this component after the shadow copy has been created. - /// This flag can be used together with the - /// VSS_VOLSNAP_ATTR_TRANSPORTABLE - /// value of the - /// _VSS_VOLUME_SNAPSHOT_ATTRIBUTES - /// enumeration if the VSS hardware provider supports LUN masking. - /// Windows Vista and Windows Server 2003 with SP1: - /// This flag is incompatible with - /// VSS_VOLSNAP_ATTR_TRANSPORTABLE - /// . - /// This flag is not supported for express writers. - /// - VSS_CF_APP_ROLLBACK_RECOVERY = 0x02, - - /// - /// This component is not part of system state. - /// Windows Server 2003 with SP1: - /// This value is not supported until Windows Vista. - /// - VSS_CF_NOT_SYSTEM_STATE = 0x04, - } - - /// - /// The VSS_COMPONENT_TYPE enumeration is used by both the requester and the writer to specify the type of component being - /// used with a shadow copy backup operation. + /// Either a writer or a requester can call this method. /// + /// + /// The address of a caller-allocated variable that receives true if additional restores will occur for the current + /// component, or false otherwise. + /// /// - /// A writer sets a component's type when it adds the component to its Writer Metadata Document using IVssCreateWriterMetadata::AddComponent. /// - /// Writers and requesters can find the type information of components selected for inclusion in a Backup Components Document - /// through calls to IVssComponent::GetComponentType to return a component type directly. + /// The value returned by GetAdditionalRestores will be false, unless during a restore operation a requester calls IVssBackupComponents::SetAdditionalRestores. + /// + /// + /// GetAdditionalRestores should be used to check if it is necessary to use more than one backup set to completely restore a + /// component. A component might first be retrieved by restoring data from a full backup, and then updating that data from one or + /// more subsequent incremental or differential backups. + /// + /// + /// The GetAdditionalRestores method is typically used by writers that support an explicit recovery mechanism as part of + /// their PostRestore event handler (CVssWriter::OnPostRestore)—for instance, the Exchange Server, and database applications such as + /// SQL Server. For these applications, it is often not possible to perform additional differential, incremental, or log restores + /// after such a recovery is performed. + /// + /// + /// Therefore, if GetAdditionalRestores returns true for a component, such a writer should not execute its explicit + /// recovery mechanism and should expect that additional differential, incremental, or log restores will be done. + /// + /// + /// When SetAdditionalRestores returns false, then after the restore has finished, when handling the PostRestore event, the + /// writer can complete its recovery operation and be brought back online. /// - /// A requester can obtain the type of any component in a given writer's Writer Metadata Document by doing the following: - /// - /// - /// Using IVssExamineWriterMetadata::GetComponent to obtain a IVssWMComponent interface - /// - /// - /// Using IVssWMComponent::GetComponentInfo to return a VSS_COMPONENTINFO structure - /// - /// - /// Examining the Type member of the VSS_COMPONENTINFO object - /// - /// /// - // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/ne-vswriter-vss_component_type typedef enum VSS_COMPONENT_TYPE { - // VSS_CT_UNDEFINED, VSS_CT_DATABASE, VSS_CT_FILEGROUP } ; - [PInvokeData("vswriter.h", MSDNShortId = "NE:vswriter.VSS_COMPONENT_TYPE")] - public enum VSS_COMPONENT_TYPE - { - /// - /// Undefined component type. - /// This value indicates an application error. - /// - VSS_CT_UNDEFINED = 0, - - /// Database component. - VSS_CT_DATABASE, - - /// File group component. This is any component other than a database. - VSS_CT_FILEGROUP, - } + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getadditionalrestores HRESULT + // GetAdditionalRestores( [out] bool *pbAdditionalRestores ); + bool AdditionalRestores { get; } /// - /// The VSS_FILE_RESTORE_STATUS enumeration defines the set of statuses of a file restore operation performed on the files - /// managed by a selected component or component set (see Working with Selectability and Logical Paths for information on selecting components). + /// The AlternateLocationMappings property is used to return a file set's alternate locations for file restoration. This can + /// be called by either a writer or a requester. /// + /// List of IVssWMFiledesc objects containing the mapping information. /// /// - /// If any files managed by a component or, if it defines a component set, any of its subcomponents cannot be restored, the value of - /// VSS_FILE_RESTORE_STATUS must indicate an error. + /// The value returned by IVssComponent::GetAlternateLocationMapping should also not be confused with that returned by IVssExamineWriterMetadata::GetAlternateLocationMapping: /// - /// Both the values VSS_RS_FAILED and VSS_RS_NONE indicate that a restore operation did not complete successfully: /// /// /// - /// VSS_RS_NONE indicates a restore failed gracefully: no files from the component or its subcomponents were restored to disk. + /// IVssExamineWriterMetadata::GetAlternateLocationMapping is the alternate location mapping to which a file may be restored if necessary. /// /// /// - /// VSS_RS_FAIL indicates a restore failed gracelessly, leaving some files restored to disk and some files unrestored. + /// IVssComponent::GetAlternateLocationMapping is the alternate location to which a file was in fact restored. + /// + /// + /// A file should always be restored to its alternate location mapping if either of the following is true: + /// + /// + /// The restore method (set at backup time) is VSS_RME_RESTORE_TO_ALTERNATE_LOCATION. + /// + /// + /// Its restore target was set (at restore time) to VSS_RT_ALTERNATE. + /// + /// + /// In either case, having no alternate location mapping defined constitutes a writer error. + /// A file can be restored to an alternate location mapping if either of the following is true: + /// + /// + /// The restore method is VSS_RME_RESTORE_IF_NOT_THERE and a version of the file is already present on disk. + /// + /// + /// The restore method is VSS_RME_RESTORE_IF_CAN_REPLACE and a version of the file is present on disk and cannot be replaced. /// /// /// - /// Requesters must set a restore status (using IVssBackupComponents::SetFileRestoreStatus) for every component (and its component - /// set, if it defines one) explicitly added for restore to the Backup Components Document (using either - /// IVssBackupComponents::SetSelectedForRestore or IVssBackupComponents::AddRestoreSubcomponent). + /// An alternate location mapping is used only during a restore operation and should not be confused with an alternate path, which + /// is used only during a backup operation. /// /// - /// Writers and requesters can query the status of the restoration of a component or a component set defined by a selectable - /// component with calls to IVssComponent::GetFileRestoreStatus. If this method is called for a component that was not selected, the - /// value returned is undefined. + /// The mapping returned by GetAlternateLocationMapping refers to the alternate location mappings used in the course of + /// restoring files. /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/ne-vswriter-vss_file_restore_status typedef enum - // VSS_FILE_RESTORE_STATUS { VSS_RS_UNDEFINED, VSS_RS_NONE, VSS_RS_ALL, VSS_RS_FAILED } ; - [PInvokeData("vswriter.h", MSDNShortId = "NE:vswriter.VSS_FILE_RESTORE_STATUS")] - public enum VSS_FILE_RESTORE_STATUS - { - /// - /// The restore state is undefined. - /// This value indicates an error, or indicates that a restore operation has not yet started. - /// This value is not supported for components that are owned by express writers. - /// - VSS_RS_UNDEFINED = 0, - - /// - /// No files were restored. - /// This value indicates an error in restoration that did not leave any restored files on disk. - /// - VSS_RS_NONE, - - /// - /// All files were restored. This value indicates success and should be set for each component that was - /// restored successfully. - /// - VSS_RS_ALL, - - /// - /// The restore process failed. - /// This value indicates an error in restoration that did leave some restored files on disk. This means the - /// components on disk are now corrupt. - /// - VSS_RS_FAILED, - } - - /// - /// - /// The VSS_RESTORE_TARGET enumeration is used by a writer at restore time to indicate how all the files included in a - /// selected component, and all the files in any component set it defines, are to be restored. (See Working with Selectability and - /// Logical Paths for information on selecting components.) - /// - /// Setting a restore target modifies or overrides the restore method set during backup (see VSS_RESTOREMETHOD_ENUM). - /// - /// - /// A target of VSS_RT_UNDEFINED indicates an error state. - /// - /// At backup time, writers set the default restore behavior by indicating a restore method (VSS_RESTOREMETHOD_ENUM) set with IVssCreateWriterMetadata::SetRestoreMethod. - /// - /// - /// If a writer does not explicitly set the restore target of a component and any component set it defines, by default it is set to VSS_RT_ORIGINAL. - /// - /// - /// At restore time, a VSS_RESTORE_TARGET value other than VSS_RT_ORIGINAL overrides the value of the originally - /// specified restore method specified by VSS_RESTOREMETHOD_ENUM and set by IVssCreateWriterMetadata::SetRestoreMethod. - /// - /// - /// Only writers (using IVssComponent::SetRestoreTarget) can set a restore target ( VSS_RESTORE_TARGET) and change how files - /// are restored overriding the restore method). - /// - /// Requesters and writers can access the current restore target through IVssComponent::GetRestoreTarget. - /// - /// A restore target of VSS_RT_ORIGINAL does not mean that files should be restored to their original location, but that the - /// originally specified restore method (VSS_RESTOREMETHOD_ENUM) must be respected. For instance, if a writer set a restore method - /// of VSS_RME_RESTORE_TO_ALTERNATE_LOCATION for a selected component and the restore target is VSS_RT_ORIGINAL, files - /// should be restored to the alternate location defined by the writer. - /// - /// - /// (In this example, if a writer has failed to define alternate location mappings, then it is a writer error, and the requester - /// should report it.) - /// - /// - /// A restore target of VSS_RT_ALTERNATE without an alternate location mapping defined constitutes a writer error, and the - /// requester should report it as such. - /// - /// See Non-Default Backup And Restore Locations for more information. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/ne-vswriter-vss_restore_target typedef enum VSS_RESTORE_TARGET { - // VSS_RT_UNDEFINED, VSS_RT_ORIGINAL, VSS_RT_ALTERNATE, VSS_RT_DIRECTED, VSS_RT_ORIGINAL_LOCATION } ; - [PInvokeData("vswriter.h", MSDNShortId = "NE:vswriter.VSS_RESTORE_TARGET")] - public enum VSS_RESTORE_TARGET - { - /// - /// No target is defined. - /// This value indicates an error on the part of the writer. - /// This value is not supported for express writers. - /// - VSS_RT_UNDEFINED = 0, - - /// - /// This is the default restore target. - /// This value indicates that the restoration of the files included in a selected component (or the component set - /// defined by that component) should proceed according to the original restore method specified at backup time by - /// a - /// VSS_RESTOREMETHOD_ENUM - /// value. - /// - VSS_RT_ORIGINAL, - - /// - /// The files are restored to a location determined from an existing alternate location mapping. - /// The restore target should be set to - /// VSS_RT_ALTERNATE - /// only when alternate location - /// mappings have been set for all the files managed by a selected component or component set. - /// This value is not supported for express writers. - /// - VSS_RT_ALTERNATE, - - /// - /// Use directed targeting by the writer at restore time to restore a file. - /// Directed targeting allows a writer to control, on a file-by-file basis, how a file is - /// restored—indicating how much of a file is to be restored and into which files the - /// backed-up file is to be restored. - /// This value is not supported for express writers. - /// - VSS_RT_DIRECTED, - - /// - /// The files are restored to the location at which they were at backup time, even if the original - /// restore method that was specified at backup time was - /// VSS_RME_RESTORE_TO_ALTERNATE_LOCATION - /// . - /// Windows Server 2003 and Windows XP: - /// This value is not supported. - /// This value is not supported for express writers. - /// - VSS_RT_ORIGINAL_LOCATION, - } - - /// - /// - /// The VSS_RESTOREMETHOD_ENUM enumeration is used by a writer at backup time to specify through its Writer Metadata Document - /// the default file restore method to be used with all the files in all the components it manages. - /// - /// - /// The restore method is writer-wide and is also referred to as the original restore target and indicated by a VSS_RESTORE_TARGET - /// value of VSS_RT_ORIGINAL. - /// - /// - /// - /// - /// A writer sets the restore method in the Writer Metadata Document by calling IVssCreateWriterMetadata::SetRestoreMethod during - /// backup to specify its desired restore method in its metadata. - /// - /// - /// A requester retrieves a writer's requested restore method by calling IVssExamineWriterMetadata::GetRestoreMethod and acts accordingly. - /// - /// The restore method applies to all files in all components of a given writer. - /// - /// The restore method may be overridden on a component-by-component basis at restore time if a writer sets a VSS_RESTORE_TARGET - /// value other than VSS_RT_ORIGINAL with IVssComponent::SetRestoreTarget. - /// - /// - /// A restore method of VSS_RME_RESTORE_TO_ALTERNATE_LOCATION without an alternate location mapping defined constitutes a - /// writer error, and the requester should report it as such. - /// - /// - /// When a restore method requires a check on the status of files currently on disk ( VSS_RME_RESTORE_IF_NOT_THERE, - /// VSS_RME_RESTORE_IF_CAN_REPLACE, or VSS_RME_RESTORE_AT_REBOOT_IF_CANNOT_REPLACE), ideally, you should use file I/O - /// operations to verify that an entire component can be restored before actually proceeding with the restore. - /// - /// - /// The safest way to do this would be to open exclusively (no-sharing) all the target files with CreateFile prior to the restore. - /// - /// In the case of VSS_RME_RESTORE_IF_NOT_THERE, a creation disposition flag of CREATE_NEW should also be set. - /// - /// If the open operations succeed, the restore can proceed and should use the handles returned by CreateFile to actually write - /// restored data to disk. - /// - /// - /// If not, an error can be returned—depending on the method—or alternate location mapping checked and (if it is available) used, or - /// the components files staged for restore at the next reboot. - /// - /// This may be a problem for very large components (some of which may have thousands of files), due to system overhead. - /// In this case, an available though less reliable option is to do the following: - /// - /// - /// Copy all files currently on disk and to be restored to a temporary cache. - /// - /// - /// - /// Attempt to replace the files currently on disk with the backed-up files (which could be either on disk in a second temporary - /// area, or on a backup medium). - /// - /// - /// - /// - /// If any files fail to restore, then terminate the restore operation and copy the original files back from their temporary - /// location and proceed with alternate location mapping or restore on reboot operations. - /// - /// - /// + /// Alternate location mappings are added to an IVssComponent object by IVssBackupComponents::AddAlternativeLocationMapping. /// For more information on backup and restore file locations under VSS, see Non-Default Backup And Restore Locations. /// - // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/ne-vswriter-vss_restoremethod_enum typedef enum - // VSS_RESTOREMETHOD_ENUM { VSS_RME_UNDEFINED, VSS_RME_RESTORE_IF_NOT_THERE, VSS_RME_RESTORE_IF_CAN_REPLACE, - // VSS_RME_STOP_RESTORE_START, VSS_RME_RESTORE_TO_ALTERNATE_LOCATION, VSS_RME_RESTORE_AT_REBOOT, - // VSS_RME_RESTORE_AT_REBOOT_IF_CANNOT_REPLACE, VSS_RME_CUSTOM, VSS_RME_RESTORE_STOP_START } ; - [PInvokeData("vswriter.h", MSDNShortId = "NE:vswriter.VSS_RESTOREMETHOD_ENUM")] - public enum VSS_RESTOREMETHOD_ENUM - { - /// - /// No restore method is defined. - /// This indicates an error on the part of the writer. - /// This value is not supported for express writers. - /// - VSS_RME_UNDEFINED = 0, + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getalternatelocationmapping HRESULT + // GetAlternateLocationMapping( [in] UINT iMapping, [out] IVssWMFiledesc **ppFiledesc ); + IReadOnlyList AlternateLocationMappings { get; } - /// - /// The requester should restore the files of a selected component or component set only if there are no versions of - /// those files currently on the disk. - /// Unless alternate location mappings are defined for file restoration, if a version of any file managed by a - /// selected component or component set is currently on the disk, none of the files managed by the selected - /// component or component set should be restored. - /// If a file's alternate location mapping is defined, and a version of the files is present on disk at the - /// original location, files should be written to the alternate location only if no version of the file exists at - /// the alternate location. - /// - VSS_RME_RESTORE_IF_NOT_THERE, - - /// - /// - /// The requester should restore files of a selected component or component set only if the files currently on the disk can be overwritten. - /// - /// Unless alternate location mappings are defined for file restoration, if there is a version of any file that - /// cannot be overwritten of the selected component or component set on the disk, none of the files managed by the - /// component or component set should be restored. - /// If a file's alternate location mapping is defined, files should be written to the alternate location. - /// - VSS_RME_RESTORE_IF_CAN_REPLACE, - - /// - /// The requester should perform the restore operation as follows: - /// - /// - /// Send the PreRestore event and wait for all writers to process it. - /// - /// - /// Stop the service. - /// - /// - /// Restore the files to their original locations. - /// - /// - /// Restart the service. - /// - /// - /// Send the PostRestore event and wait for all writers to process it. - /// - /// - /// The service to be stopped is specified the writer beforehand when it calls the - /// IVssCreateWriterMetadata::SetRestoreMethod - /// method. The requester can obtain the name of the service by calling the - /// IVssExamineWriterMetadata::GetRestoreMethod - /// method. - /// Note that if the writer is hosted in the service that is being stopped, that writer will not receive the - /// PostRestore - /// event, because the writer instance ID changes when the service is stopped and restarted. - /// - VSS_RME_STOP_RESTORE_START, - - /// - /// The requester should restore the files of the selected component or component set to the location specified by the - /// alternate location mapping specified in the writer component metadata file. (See - /// IVssCreateWriterMetadata::AddAlternateLocationMapping - /// , - /// IVssComponent::GetAlternateLocationMapping - /// , - /// IVssExamineWriterMetadata::GetAlternateLocationMapping - /// , - /// and - /// IVssWMFiledesc::GetAlternateLocation - /// .) - /// This value is not supported for express writers. - /// - VSS_RME_RESTORE_TO_ALTERNATE_LOCATION, - - /// - /// The requester should restore the files of a selected component or component set after the computer is restarted. - /// The files to be restored should be copied to a temporary location, and the requester should use - /// MoveFileEx - /// with the - /// MOVEFILE_DELAY_UNTIL_REBOOT - /// flag to complete the restoration of these files to their - /// proper location after the computer is restarted. - /// - VSS_RME_RESTORE_AT_REBOOT, - - /// - /// If possible, the requester should restore the files of the selected component or component set to their correct - /// location immediately. - /// If there are versions of any of the files managed by the selected component or component set on the disk that - /// cannot be overwritten, then all the files managed by the selected component or component set should be restored - /// after the computer is restarted. - /// In this case, files to be restored should be copied to a temporary location on disk, and the requester should - /// use - /// MoveFileEx - /// with the - /// MOVEFILE_DELAY_UNTIL_REBOOT - /// flag to complete the restoration of these files to their - /// proper location after the computer is restarted. - /// - VSS_RME_RESTORE_AT_REBOOT_IF_CANNOT_REPLACE, - - /// - /// The requester should use a custom restore method to restore the files that are managed by the selected - /// component or component set. - /// A custom restore may use file retrieval API functions or protocols that are private to a given writer - /// application. Such a restore need not use the information in the writer component metadata file. (See - /// Custom Backups and Restores - /// for more - /// information.) - /// This value is not supported for express writers. - /// - VSS_RME_CUSTOM, - - /// - /// The requester should perform the restore operation as follows: - /// - /// - /// Send the PreRestore event and wait for all writers to process it. - /// - /// - /// Restore the files to their original locations. - /// - /// - /// Send the PostRestore event and wait for all writers to process it. - /// - /// - /// Stop the service. - /// - /// - /// Restart the service. - /// - /// - /// The service to be stopped is specified by the writer beforehand when it calls the - /// IVssCreateWriterMetadata::SetRestoreMethod - /// method. The requester can obtain the name of the service by calling the - /// IVssExamineWriterMetadata::GetRestoreMethod - /// method. - /// - VSS_RME_RESTORE_STOP_START, - } - - /// The VSS_SOURCE_TYPE enumeration specifies the type of data that a writer manages. + /// Determines whether a requester has marked the restore of a component as authoritative for a replicated data store. + /// + /// The address of a caller-allocated variable that receives true if the restore is authoritative, or false otherwise. + /// /// /// - /// The source type of the data that a writer manages is specified when it initializes its cooperation with the shadow copy - /// mechanism through a call to CVssWriter::Initialize. + /// A writer indicates that it supports authoritative restore by setting the VSS_BS_AUTHORITATIVE_RESTORE flag in its backup + /// schema mask. /// - /// Information about the source type of the data that a writer manages can be retrieved through its metadata using IVssExamineWriterMetadata::GetIdentity. + /// For more information, see Setting VSS Restore Options. /// - // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/ne-vswriter-vss_source_type typedef enum VSS_SOURCE_TYPE { - // VSS_ST_UNDEFINED, VSS_ST_TRANSACTEDDB, VSS_ST_NONTRANSACTEDDB, VSS_ST_OTHER } ; - [PInvokeData("vswriter.h", MSDNShortId = "NE:vswriter.VSS_SOURCE_TYPE")] - public enum VSS_SOURCE_TYPE - { - /// - /// The source of the data is not known. - /// This indicates a writer error, and the requester should report it. - /// - VSS_ST_UNDEFINED = 0, - - /// The source of the data is a database that supports transactions, such as Microsoft SQL Server. - VSS_ST_TRANSACTEDDB, - - /// The source of the data is a database that does not support transactions. - VSS_ST_NONTRANSACTEDDB, - - /// - /// Unclassified source type—data will be in a file group. - /// This is the default source type. - /// - VSS_ST_OTHER, - } + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponentex-getauthoritativerestore HRESULT + // GetAuthoritativeRestore( [out] bool *pbAuth ); + bool AuthoritativeRestore { get; } /// - /// The VSS_SUBSCRIBE_MASK enumeration is used by a writer when subscribing to the VSS service. It indicates the events that - /// the writer is willing to receive. - /// - /// - /// A bit mask (or bitwise OR) of VSS_SUBSCRIBE_MASK values is used as an argument only to CVssWriter::Subscribe. - /// Currently, the only supported VSS_SUBSCRIBE_MASK bit mask is ( VSS_SM_BACKUP_EVENTS_FLAG | VSS_SM_RESTORE_EVENTS_FLAG). - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/ne-vswriter-vss_subscribe_mask typedef enum VSS_SUBSCRIBE_MASK { - // VSS_SM_POST_SNAPSHOT_FLAG, VSS_SM_BACKUP_EVENTS_FLAG, VSS_SM_RESTORE_EVENTS_FLAG, VSS_SM_IO_THROTTLING_FLAG, VSS_SM_ALL_FLAGS } ; - [PInvokeData("vswriter.h", MSDNShortId = "NE:vswriter.VSS_SUBSCRIBE_MASK")] - [Flags] - public enum VSS_SUBSCRIBE_MASK : uint - { - /// - /// This enumeration value is reserved for future use. - /// Specifies that the writer expects to be notified after the shadow copy it is participating in has completed. - /// It will then call - /// CVssWriter::OnPostSnapshot - /// . - /// - VSS_SM_POST_SNAPSHOT_FLAG = 0x01, - - /// - /// Currently, - /// VSS_SM_BACKUP_EVENTS_FLAG - /// can be used as an argument only when - /// combined through a bitwise OR with - /// VSS_SM_RESTORE_EVENTS_FLAG - /// . - /// Specifies that the writer can expect to receive the following events: - /// - /// - /// A PrepareForSnapshot event when the writer will call CVssWriter::OnPrepareSnapshot. - /// - /// - /// A PrepareForBackup event when the writer will call CVssWriter::OnPrepareBackup. - /// - /// - /// A Freeze event when the writer will call CVssWriter::OnFreeze. - /// - /// - /// A BackupComplete event when the writer will call CVssWriter::OnBackupComplete. - /// - /// - /// A Thaw event when the writer will call CVssWriter::OnThaw. - /// - /// - /// A PostSnapshot event when the writer will call CVssWriter::OnPostSnapshot. - /// - /// - /// - VSS_SM_BACKUP_EVENTS_FLAG = 0x02, - - /// - /// Currently, - /// VSS_SM_RESTORE_EVENTS_FLAG - /// can be used as an argument only when - /// combined through a bitwise OR with - /// VSS_SM_BACKUP_EVENTS_FLAG - /// . - /// Specifies that the writer can expect to receive the following events: - /// - /// - /// A PreRestore event when the writer will call CVssWriter::OnPreRestore. - /// - /// - /// A PostRestore event when the writer will call CVssWriter::OnPostRestore. - /// - /// - /// - VSS_SM_RESTORE_EVENTS_FLAG = 0x04, - - /// This enumeration value is reserved for future use. - VSS_SM_IO_THROTTLING_FLAG = 0x08, - - /// - /// This enumeration value is reserved for future use. - /// Specifies that the writer expects to be notified for all events. - /// - VSS_SM_ALL_FLAGS = 0xFFFFFFFF, - } - - /// - /// The VSS_USAGE_TYPE enumeration specifies how the host system uses the data managed by a writer involved in a VSS operation. + /// + /// The GetBackupMetadata method retrieves private, writer-specific backup metadata that might have been set during a + /// PrepareForBackup event by CVssWriter::OnPrepareBackup using IVssComponent::SetBackupMetadata. + /// + /// Only a writer can call this method. + /// + /// + /// The address of a caller-allocated variable that receives a string containing the backup metadata that was added during an + /// OnPrepareBackup event. + /// + /// + /// This method can be called at any time depending on the logic of a given writer. + /// If no backup metadata has been set, GetBackupMetadata returns S_FALSE. + /// + /// If the call to GetBackupMetadata is successful, the caller is responsible for freeing the string that is returned in the + /// pbstrMetadata parameter by calling the SysFreeString function. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getbackupmetadata HRESULT + // GetBackupMetadata( [out] BSTR *pbstrData ); + string BackupMetadata { get; set; } + + /// + /// + /// The GetBackupOptions method returns the backup options specified to the writer that manages the currently selected + /// component or component set by a requester using IVssBackupComponents::SetBackupOptions. + /// + /// Either a writer or a requester can call this method. + /// + /// + /// The address of a caller-allocated variable that receives a string containing the backup options for the current writer. + /// + /// + /// If no backup options have been set, S_FALSE is returned. + /// + /// If the call to GetBackupOptions is successful, the caller is responsible for freeing the string that is returned in the + /// pbstrBackupOptions parameter by calling the SysFreeString function. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getbackupoptions HRESULT GetBackupOptions( + // [out] BSTR *pbstrBackupOptions ); + string BackupOptions { get; } + + /// + /// The GetBackupStamp method returns the backup stamp string stored by a writer for a given component. + /// Either a writer or a requester can call this method. + /// + /// + /// The address of a caller-allocated variable that receives a string containing the backup stamp indicating the time at which the + /// component was backed up. + /// + /// + /// If no backup time stamp has been set, GetBackupStamp returns S_FALSE. + /// + /// If the call to GetBackupStamp is successful, the caller is responsible for freeing the string that is returned in the + /// pbstrBackupStamp parameter by calling the SysFreeString function. + /// + /// The string returned refers to all files in the component and any nonselectable subcomponents it has. + /// + /// The backup stamp retrieved by GetBackupStamp is generally set by a writer by a call to IVssComponent::SetBackupStamp from + /// within the PostSnapshot event handler, CVssWriter::OnPostSnapshot. + /// + /// + /// Requesters merely store the backup stamps in the Backup Components Document; they do not make direct use of the backup stamp, + /// know how to generate it, or understand its format. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getbackupstamp HRESULT GetBackupStamp( + // [out] BSTR *pbstrBackupStamp ); + string BackupStamp { get; set; } + + /// + /// + /// The GetBackupSucceeded method returns the status of a complete attempt at backing up all the files of a selected + /// component or component set as a VSS_FILE_RESTORE_STATUS enumeration. (See Working with Selectability and Logical Paths for + /// information on selecting components.) + /// + /// Either a writer or a requester can call this method. + /// + /// + /// The address of a caller-allocated variable that receives true if the backup was successful, or false otherwise. + /// + /// + /// This method should not be called prior to a BackupComplete event, and is designed for use in an implementation of the event + /// handler CVssWriter::OnBackupComplete. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getbackupsucceeded HRESULT + // GetBackupSucceeded( [out] bool *pbSucceeded ); + bool BackupSucceeded { get; } + + /// + /// The GetComponentName method returns the logical name of this component. + /// Either a writer or a requester can call this method. + /// + /// Pointer to a string containing the logical name of the component. + /// The caller should free the memory held by the pwszName parameter by calling SysFreeString. + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getcomponentname HRESULT GetComponentName( + // [out] BSTR *pbstrName ); + string ComponentName { get; } + + /// + /// The GetComponentType method returns the type of this component in terms of the VSS_COMPONENT_TYPE enumeration. + /// Either a writer or a requester can call this method. + /// + /// + /// The address of a caller-allocated variable that receives a VSS_COMPONENT_TYPE enumeration value that specifies the type of the component. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getcomponenttype HRESULT GetComponentType( + // [out] VSS_COMPONENT_TYPE *pct ); + VSS_COMPONENT_TYPE ComponentType { get; } + + /// + /// + /// The GetDifferencedFile method returns information about a file set (a 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). + /// + /// This method can be called by a requester or a writer during backup or restore operations. /// /// + /// GetDifferencedFile can be called by a requester or a writer during backup or restore operations. /// - /// The usage type of the data that a writer manages is specified when it initializes its cooperation with the shadow copy mechanism - /// through CVssWriter::Initialize. - /// - /// Information about the usage type of the data that a writer manages can be retrieved through its metadata using IVssExamineWriterMetadata::GetIdentity. - /// - /// Requester applications that are interested in backing up system state should look for writers with the - /// VSS_UT_BOOTABLESYSTEMSTATE or VSS_UT_SYSTEMSERVICE usage type. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/ne-vswriter-vss_usage_type typedef enum VSS_USAGE_TYPE { - // VSS_UT_UNDEFINED, VSS_UT_BOOTABLESYSTEMSTATE, VSS_UT_SYSTEMSERVICE, VSS_UT_USERDATA, VSS_UT_OTHER } ; - [PInvokeData("vswriter.h", MSDNShortId = "NE:vswriter.VSS_USAGE_TYPE")] - public enum VSS_USAGE_TYPE - { - /// - /// The usage type is not known. - /// This indicates an error on the part of the writer. - /// - VSS_UT_UNDEFINED = 0, - - /// The data stored by the writer is part of the bootable system state. - VSS_UT_BOOTABLESYSTEMSTATE, - - /// The writer either stores data used by a system service or is a system service itself. - VSS_UT_SYSTEMSERVICE, - - /// The data is user data. - VSS_UT_USERDATA, - - /// Unclassified data. - VSS_UT_OTHER, - } - - /// - /// The VSS_WRITERRESTORE_ENUM enumeration is used by a writer to indicate to a requester the conditions under which it will - /// handle events generated during a restore operation. - /// - /// - /// - /// A writer passes a value of VSS_WRITERRESTORE_ENUM to IVssCreateWriterMetadata::SetRestoreMethod to indicate through its - /// metadata how it interacts with requesters during a restore operation. - /// - /// A requester retrieves information about a writer's participation by calling IVssExamineWriterMetadata::GetRestoreMethod. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/ne-vswriter-vss_writerrestore_enum typedef enum - // VSS_WRITERRESTORE_ENUM { VSS_WRE_UNDEFINED, VSS_WRE_NEVER, VSS_WRE_IF_REPLACE_FAILS, VSS_WRE_ALWAYS } ; - [PInvokeData("vswriter.h", MSDNShortId = "NE:vswriter.VSS_WRITERRESTORE_ENUM")] - public enum VSS_WRITERRESTORE_ENUM - { - /// - /// It is not known whether the writer will perform special operations during the restore operation. - /// This state indicates a writer error. - /// - VSS_WRE_UNDEFINED = 0, - - /// The writer does not require restore events. - VSS_WRE_NEVER, - - /// - /// Indicates that the writer always expects to handle a - /// PreRestore - /// ( - /// CvssWriter::OnPreRestore - /// ) event, but expects - /// to handle a - /// PostRestore - /// event - /// ( - /// CvssWriter::OnPostRestore - /// ) only if a restore - /// fails when implementing either a - /// VSS_RME_RESTORE_IF_NOT_THERE - /// or - /// VSS_RME_RESTORE_IF_CAN_REPLACE - /// restore method - /// ( - /// VSS_RESTOREMETHOD_ENUM - /// ). - /// - VSS_WRE_IF_REPLACE_FAILS, - - /// The writer always performs special operations during the restore operation. - VSS_WRE_ALWAYS, - } - - /// - /// - /// The IVssComponent interface is a C++ (not COM) interface containing methods for examining and modifying information about - /// components contained in a requester's Backup Components Document. + /// If the call to GetDifferencedFile is successful, the caller is responsible for freeing the string that is returned in the + /// pbstrPath and pbstrFilespec parameters by calling the SysFreeString function. /// /// - /// 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 IVssBackupComponents::AddComponent method. + /// As writers can indicate differenced files with calls to IVssComponent::AddDifferencedFilesByLastModifyTime at any time prior to + /// the actual backing up of files, typically while handling a PostSnapshot event (CVssWriter::OnPostSnapshot), during backups + /// GetDifferencedFile is not usefully called prior to the return of IVssBackupComponents::DoSnapshotSet has successfully returned. /// /// - /// Information about components explicitly added during a restore operation using IVssBackupComponents::AddRestoreSubcomponent are - /// not available through the IVssComponent interface. + /// The time stamp returned by GetDifferencedFile applies to all files that match the returned path (pbstrPath) and file + /// specification (pbstrFilespec). /// /// - /// Some information common to both components and implicitly selected subcomponents available through IVssComponent objects - /// includes the following: + /// If the time-stamp value returned by GetDifferencedFile (pftLastModifyTime) is nonzero, a requester must respect this + /// value regardless of its own records and file system information and use it to determine whether the differenced file should be + /// included in a differential or incremental backup. /// + /// + /// If the time stamp returned by GetDifferencedFile is zero, the requester can use file system information and its own + /// records to determine whether the differenced files should be included in a differential or incremental backup. + /// + /// Differenced files can be either of the following: /// /// - /// Backup time stamp - /// - /// - /// Pre-/post-restore Failure Messages - /// - /// - /// Restore metadata - /// - /// - /// Restore target - /// - /// - /// - /// Some information in the IVssComponent object is on a per-file basis and can refer to files managed either by explicitly - /// selected components or by implicitly selected subcomponents: - /// - /// - /// - /// Alternate location mappings - /// - /// - /// Partial files - /// - /// - /// Directed target - /// - /// - /// - /// Other information is not included in the Backup Components Document and can be inferred using the IVssComponent object in - /// conjunction with the appropriate Writer Metadata Documents based on a writer's component hierarchy expressed in the logical - /// paths (see Working with Selectability and Logical Paths). - /// - /// - /// The interface can be used by either a writer or a requester, although certain methods are supported only for writers. In this - /// way, a writer can request changes in a backup or restore operation, such as adding a new target, or learn of requester actions, - /// such as the use of an alternate location. - /// - /// The following methods return an IVssComponent interface: - /// - /// - /// IVssWriterComponents::GetComponent - /// - /// - /// IVssWriterComponentsExt::GetComponent - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nl-vswriter-ivsscomponent - [PInvokeData("vswriter.h", MSDNShortId = "NL:vswriter.IVssComponent")] - [ComVisible(true), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - private interface IVssComponent - { - [PreserveSig] - HRESULT AddDifferencedFilesByLastModifyLSN([MarshalAs(UnmanagedType.LPWStr)] string wszPath, - [MarshalAs(UnmanagedType.LPWStr)] string wszFilespec, - [MarshalAs(UnmanagedType.Bool)] bool bRecursive, - [MarshalAs(UnmanagedType.BStr)] string bstrLsnString); - - // add differenced files by last modify time - [PreserveSig] - HRESULT AddDifferencedFilesByLastModifyTime([MarshalAs(UnmanagedType.LPWStr)] string wszPath, [MarshalAs(UnmanagedType.LPWStr)] string wszFilespec, - [MarshalAs(UnmanagedType.Bool)] bool bRecursive, FILETIME ftLastModifyTime); - - // add a directed target specification - [PreserveSig] - HRESULT AddDirectedTarget([MarshalAs(UnmanagedType.LPWStr)] string wszSourcePath, - [MarshalAs(UnmanagedType.LPWStr)] string wszSourceFilename, - [MarshalAs(UnmanagedType.LPWStr)] string wszSourceRangeList, - [MarshalAs(UnmanagedType.LPWStr)] string wszDestinationPath, - [MarshalAs(UnmanagedType.LPWStr)] string wszDestinationFilename, - [MarshalAs(UnmanagedType.LPWStr)] string wszDestinationRangeList); - - // indicate that only ranges in the file are to be backed up - [PreserveSig] - HRESULT AddPartialFile([MarshalAs(UnmanagedType.LPWStr)] string wszPath, - [MarshalAs(UnmanagedType.LPWStr)] string wszFilename, - [MarshalAs(UnmanagedType.LPWStr)] string wszRanges, - [MarshalAs(UnmanagedType.LPWStr)] string wszMetadata); - - [PreserveSig] - HRESULT GetAdditionalRestores(out bool pbAdditionalRestores); - - // get a paraticular alternative location mapping - [PreserveSig] - HRESULT GetAlternateLocationMapping([In] uint iMapping, out IVssWMFiledesc ppFiledesc); - - // get altermative location mapping count - [PreserveSig] - HRESULT GetAlternateLocationMappingCount(out uint pcMappings); - - // get the backup metadata for a component - [PreserveSig] - HRESULT GetBackupMetadata([MarshalAs(UnmanagedType.BStr)] out string pbstrData); - - // obtain backup options for the writer - [PreserveSig] - HRESULT GetBackupOptions([MarshalAs(UnmanagedType.BStr)] out string pbstrBackupOptions); - - // obtain the stamp of the backup - [PreserveSig] - HRESULT GetBackupStamp([MarshalAs(UnmanagedType.BStr)] out string pbstrBackupStamp); - - // determine whether the component was successfully backed up. - [PreserveSig] - HRESULT GetBackupSucceeded(out bool pbSucceeded); - - [PreserveSig] - HRESULT GetComponentName([MarshalAs(UnmanagedType.BStr)] out string pbstrName); - - /// - /// The GetComponentType method returns the type of this component in terms of the VSS_COMPONENT_TYPE enumeration. - /// Either a writer or a requester can call this method. - /// - /// - /// The address of a caller-allocated variable that receives a VSS_COMPONENT_TYPE enumeration value that specifies the type of - /// the component. - /// - /// - /// The following are the valid return codes for this method. - /// - /// - /// Value - /// Meaning - /// - /// - /// S_OK - /// Successfully returned the attribute value. - /// - /// - /// E_INVALIDARG - /// One of the parameter values is not valid. - /// - /// - /// E_OUTOFMEMORY - /// The caller is out of memory or other system resources. - /// - /// - /// 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. - /// - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getcomponenttype HRESULT - // GetComponentType( [out] VSS_COMPONENT_TYPE *pct ); - [PreserveSig] - HRESULT GetComponentType(out VSS_COMPONENT_TYPE pct); - - [PreserveSig] - HRESULT GetDifferencedFile(uint iDifferencedFile, - [MarshalAs(UnmanagedType.BStr)] out string pbstrPath, - [MarshalAs(UnmanagedType.BStr)] out string pbstrFilespec, - [MarshalAs(UnmanagedType.Bool)] out bool pbRecursive, - [MarshalAs(UnmanagedType.BStr)] out string pbstrLsnString, - out FILETIME pftLastModifyTime); - - [PreserveSig] - HRESULT GetDifferencedFilesCount(out uint pcDifferencedFiles); - - // obtain a particular directed target specification - [PreserveSig] - HRESULT GetDirectedTarget(uint iDirectedTarget, - [MarshalAs(UnmanagedType.BStr)] out string pbstrSourcePath, - [MarshalAs(UnmanagedType.BStr)] out string pbstrSourceFileName, - [MarshalAs(UnmanagedType.BStr)] out string pbstrSourceRangeList, - [MarshalAs(UnmanagedType.BStr)] out string pbstrDestinationPath, - [MarshalAs(UnmanagedType.BStr)] out string pbstrDestinationFilename, - [MarshalAs(UnmanagedType.BStr)] out string pbstrDestinationRangeList); - - // get count of directed target specifications - [PreserveSig] - HRESULT GetDirectedTargetCount(out uint pcDirectedTarget); - - // obtain whether files were successfully restored - [PreserveSig] - HRESULT GetFileRestoreStatus(out VSS_FILE_RESTORE_STATUS pStatus); - - /// - /// The GetLogicalPath method returns the logical path of this component. - /// Either a writer or a requester can call this method. - /// - /// Pointer to a string containing the logical path of the component. - /// - /// The following are the valid return codes for this method. - /// - /// - /// Value - /// Meaning - /// - /// - /// S_OK - /// Successfully returned the attribute value. - /// - /// - /// S_FALSE - /// This component has no logical path. - /// - /// - /// E_INVALIDARG - /// One of the parameter values is not valid. - /// - /// - /// E_OUTOFMEMORY - /// The caller is out of memory or other system resources. - /// - /// - /// 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. - /// - /// - /// - /// - /// - /// The caller should free the memory held by the pbstrPath parameter by calling SysFreeString. - /// Logical paths are not required of components. A component without a logical path will return S_FALSE. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getlogicalpath HRESULT GetLogicalPath( - // [out] BSTR *pbstrPath ); - [PreserveSig] - HRESULT GetLogicalPath([MarshalAs(UnmanagedType.BStr)] out string pbstrPath); - - [PreserveSig] - HRESULT GetNewTarget(uint iNewTarget, out IVssWMFiledesc ppFiledesc); - - // get count of new target specifications - [PreserveSig] - HRESULT GetNewTargetCount(out uint pcNewTarget); - - // get a partial file declaration - [PreserveSig] - HRESULT GetPartialFile(uint iPartialFile, - [MarshalAs(UnmanagedType.BStr)] out string pbstrPath, - [MarshalAs(UnmanagedType.BStr)] out string pbstrFilename, - [MarshalAs(UnmanagedType.BStr)] out string pbstrRange, - [MarshalAs(UnmanagedType.BStr)] out string pbstrMetadata); - - // get count of partial file declarations - [PreserveSig] - HRESULT GetPartialFileCount(out uint pcPartialFiles); - - // obtain the failure message set during the post restore event - [PreserveSig] - HRESULT GetPostRestoreFailureMsg([MarshalAs(UnmanagedType.BStr)] out string pbstrPostRestoreFailureMsg); - - // obtain failure message during pre restore event - [PreserveSig] - HRESULT GetPreRestoreFailureMsg([MarshalAs(UnmanagedType.BStr)] out string pbstrPreRestoreFailureMsg); - - // obtain the backup stamp that the differential or incremental backup is baed on - [PreserveSig] - HRESULT GetPreviousBackupStamp([MarshalAs(UnmanagedType.BStr)] out string pbstrBackupStamp); - - // obtain restore metadata associated with the component - [PreserveSig] - HRESULT GetRestoreMetadata([MarshalAs(UnmanagedType.BStr)] out string pbstrRestoreMetadata); - - // obtain the restore options - [PreserveSig] - HRESULT GetRestoreOptions([MarshalAs(UnmanagedType.BStr)] out string pbstrRestoreOptions); - - // obtain a particular subcomponent to be restored - [PreserveSig] - HRESULT GetRestoreSubcomponent(uint iComponent, [MarshalAs(UnmanagedType.BStr)] out string pbstrLogicalPath, - [MarshalAs(UnmanagedType.BStr)] out string pbstrComponentName, out bool pbRepair); - - // obtain count of subcomponents to be restored - [PreserveSig] - HRESULT GetRestoreSubcomponentCount(out uint pcRestoreSubcomponent); - - // obtain the restore target - [PreserveSig] - HRESULT GetRestoreTarget(out VSS_RESTORE_TARGET pTarget); - - // determine if the component is selected to be restored - [PreserveSig] - HRESULT IsSelectedForRestore(out bool pbSelectedForRestore); - - // set the backup metadata for a component - [PreserveSig] - HRESULT SetBackupMetadata([MarshalAs(UnmanagedType.LPWStr)] string wszData); - - // set the backup stamp of the backup - [PreserveSig] - HRESULT SetBackupStamp([MarshalAs(UnmanagedType.LPWStr)] string wszBackupStamp); - - // set the failure message during the post restore event - [PreserveSig] - HRESULT SetPostRestoreFailureMsg([MarshalAs(UnmanagedType.LPWStr)] string wszPostRestoreFailureMsg); - - // set failure message during pre restore event - [PreserveSig] - HRESULT SetPreRestoreFailureMsg([MarshalAs(UnmanagedType.LPWStr)] string wszPreRestoreFailureMsg); - - // set restore metadata associated with the component - [PreserveSig] - HRESULT SetRestoreMetadata([MarshalAs(UnmanagedType.LPWStr)] string wszRestoreMetadata); - - // set the restore target - [PreserveSig] - HRESULT SetRestoreTarget(VSS_RESTORE_TARGET target); - } - - /// - /// - /// Defines additional methods for examining and modifying information about components contained in a requester's Backup Components Document. - /// - /// The IVssComponentEx interface is a C++ (not COM) interface. - /// - /// To obtain an instance of the IVssComponentEx interface, call the QueryInterface method of the IVssComponent interface, - /// and pass the IID_IVssComponentEx constant as the interface identifier (IID) parameter. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nl-vswriter-ivsscomponentex - [PInvokeData("vswriter.h", MSDNShortId = "NL:vswriter.IVssComponentEx")] - private interface IVssComponentEx - { } - - /// - /// Defines additional methods for reporting and retrieving component-level writer errors. - /// The IVssComponentEx2 interface is a C++ (not COM) interface. - /// - /// To obtain an instance of the IVssComponentEx2 interface, call the QueryInterface method of the IVssComponent interface - /// and pass the IID_IVssComponentEx2 constant as the interface identifier (IID) parameter. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nl-vswriter-ivsscomponentex2 - [PInvokeData("vswriter.h", MSDNShortId = "NL:vswriter.IVssComponentEx2")] - private interface IVssComponentEx2 - { } - - /// - /// - /// The IVssCreateExpressWriterMetadata interface is a COM interface containing methods to construct the Writer Metadata - /// Document for an express writer. - /// - /// - /// After it is constructed, the Writer Metadata Document is a read-only object that requesters query for information about a writer - /// and its components. - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nl-vswriter-ivsscreateexpresswritermetadata - [PInvokeData("vswriter.h", MSDNShortId = "NL:vswriter.IVssCreateExpressWriterMetadata")] - private interface IVssCreateExpressWriterMetadata - { } - - /// - /// - /// The IVssCreateWriterMetadata interface is a C++ (not COM) interface containing methods to construct the Writer Metadata - /// Document in response to an Identify event. It is used only in the CVssWriter::OnIdentify method. - /// - /// The addition and specification of components by a writer is managed through this interface. - /// - /// After it is constructed, the Writer Metadata Document is a read-only object that requesters query for information about a writer - /// and its components. - /// - /// IVssCreateWriterMetadata defines the following methods. - /// - /// - /// Method - /// Description - /// - /// - /// AddAlternateLocationMapping - /// Creates an alternate location mapping. - /// - /// - /// AddComponent - /// Adds a database or file group as a component to be backed up. - /// - /// - /// AddComponentDependency /// - /// Indicates that a component participates in a backup or restore only if specified components managed by other writers also participate. + /// Members of the current component or, if the component defines a component set, members of its subcomponents that were added to + /// the component using IVssCreateWriterMetadata::AddFilesToFileGroup, IVssCreateWriterMetadata::AddDatabaseFiles, or IVssCreateWriterMetadata::AddDatabaseLogFiles /// /// /// - /// AddDatabaseFiles - /// Indicates the physical files that are associated with a database to be backed up, as well as their location. - /// - /// - /// AddDatabaseLogFiles - /// Indicates the log files that are associated with a database to be backed up, as well as their location. - /// - /// - /// AddExcludeFiles - /// Specifies the files that will be excluded from the backup. - /// - /// - /// AddFilesToFileGroup - /// Adds the specified file or files to the specified file group. - /// - /// - /// AddIncludeFiles - /// Reserved for system use. - /// - /// - /// GetDocument - /// Reserved for system use. - /// - /// - /// SaveAsXML - /// Saves a text string containing the Writer Metadata Document. - /// - /// - /// SetBackupSchema - /// Sets the backup schema (how a backup is to be executed) to be used when processing a writer's files. - /// - /// - /// SetRestoreMethod - /// Indicates how writer data is to be restored. + /// New files added to the component by IVssComponent::AddDifferencedFilesByLastModifyTime /// /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nl-vswriter-ivsscreatewritermetadata - [PInvokeData("vswriter.h", MSDNShortId = "NL:vswriter.IVssCreateWriterMetadata")] - private interface IVssCreateWriterMetadata - { } + /// + /// When referring to a file set that is already part of the component, the combination of path, file specification, and recursion + /// flag (wszPath, wszFileSpec, and bRecursive, respectively) used when calling GetDifferencedFile should match that of a + /// file set already in the component, or one of its subcomponents (if the component defines a component set). + /// + /// + /// When GetDifferencedFile returns a differenced new file, that file's path (pbstrPath) should match or be beneath a path + /// already in the component, or one of its subcomponents (if the component defines a component set). + /// + /// In addition, the files returned by GetDifferencedFile should not already be managed by component or writer. + /// If any of these criteria are violated, they constitute an error on the part of the writer and should be reported. + /// + /// There is no method in the IVssComponent interface that allows for changing or adding an alternate location mapping for new files + /// returned by GetDifferencedFilesByLastModifyTime. If an alternate location mapping corresponds to the new file, then that + /// alternate location will be used. + /// + /// + IAppendOnlyList DifferencedFiles { get; } /// /// - /// The IVssCreateWriterMetadataEx interface is a C++ (not COM) interface that defines a method to report any file sets that - /// will be explicitly excluded when a shadow copy is created. This interface is used only in the CVssWriterEx::OnIdentifyEx method. + /// The DirectedTargets property returns 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. /// - /// The IVssCreateWriterMetadataEx interface inherits from the IVssCreateWriterMetadata interface and IUnknown. - /// IVssCreateWriterMetadataEx defines the following method. - /// - /// - /// Method - /// Description - /// - /// - /// AddExcludeFilesFromSnapshot - /// Reports any file sets that will be explicitly excluded by the writer when a shadow copy is created. - /// - /// + /// Either a writer or a requester can call this method. /// - // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nl-vswriter-ivsscreatewritermetadataex - [PInvokeData("vswriter.h", MSDNShortId = "NL:vswriter.IVssCreateWriterMetadataEx")] - private interface IVssCreateWriterMetadataEx - { } - - /// Defines methods to manage metadata for a VSS express writer. - // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nl-vswriter-ivssexpresswriter - [PInvokeData("vswriter.h", MSDNShortId = "NL:vswriter.IVssExpressWriter")] - private interface IVssExpressWriter - { } + /// + /// + /// A requester will use the directed target information stored in the Backup Components Document only if the restore target is VSS_RT_DIRECTED. + /// + /// + /// 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. + /// + /// + /// Files whose directed targets are returned by GetDirectedTarget may be members of the files of the current component or + /// any subcomponent it defines. + /// + /// + /// 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. + /// + /// + /// The requester will need to check if the directed target source file was backed up as a partial file to correctly implement the + /// restore. If this is the case, the requester uses the directed target information in conjunction with the partial file + /// information (IVssComponent::GetPartialFile) to implement the remapping of the backed-up data during restore. + /// + /// + IAppendOnlyList DirectedTargets { get; } /// /// - /// The IVssWMDependency is a C++ (not COM) interface returned by the IVssWMComponent interface and used by applications when - /// backing up or restoring a component that has an explicit writer-component dependency on a component managed by another writer. - /// (Dependencies must be between writers, not within writers.) - /// - /// - /// IVssWMDependency is used to determine the writer ID, logical path, and component name of components that must be restored - /// or backed up along with the target component. - /// - /// - /// Dependencies are created by writers while handling Identify events (CVssWriter::OnIdentify) using the - /// IVssCreateWriterMetadata::AddComponentDependency method. - /// - /// - /// Calling applications are responsible for calling IUnknown::Release to release resources held by a returned - /// IVssWMDependency object when it is no longer needed. - /// - /// The IVssWMComponent::GetDependency method returns an IVssWMDependency interface. - /// - /// Note that a dependency does not indicate an order of preference between the component with the documented dependencies and the - /// components it depends on. A dependency merely indicates that the component and the components it depends on must always be - /// backed up or restored together. + /// The GetFileRestoreStatus method returns the status of a completed attempt to restore all the files of a selected + /// component or component set as a VSS_FILE_RESTORE_STATUS enumeration. (See Working with Selectability and Logical Paths for + /// information on selecting components.) /// + /// Either a writer or a requester can call this method. /// - // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nl-vswriter-ivsswmdependency - [PInvokeData("vswriter.h", MSDNShortId = "NL:vswriter.IVssWMDependency")] - private interface IVssWMDependency - { } - - /// - /// - /// The IVssWMFiledesc interface is a C++ (not COM) interface returned to a calling application by a number of query methods. - /// It provides detailed information about a file or set of files (a file set). - /// - /// - /// The calling application is responsible for calling IUnknown::Release to release the resources held by the returned - /// IVssWMFiledesc interface when it is no longer needed. - /// - /// The following methods return an IVssWMFiledesc interface: - /// - /// - /// IVssComponent::GetAlternateLocationMapping - /// - /// - /// IVssComponent::GetNewTarget - /// - /// - /// IVssExamineWriterMetadata::GetExcludeFile - /// - /// - /// IVssExamineWriterMetadata::GetAlternateLocationMapping - /// - /// - /// IVssWMComponent::GetFile - /// - /// - /// IVssWMComponent::GetDatabaseFile - /// - /// - /// IVssWMComponent::GetDatabaseLogFile - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nl-vswriter-ivsswmfiledesc - [PInvokeData("vswriter.h", MSDNShortId = "NL:vswriter.IVssWMFiledesc")] - [ComVisible(true), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] - private interface IVssWMFiledesc - { - /// The GetAlternateLocation method obtains an alternate location for a file set. - /// - /// The address of a caller-allocated variable that receives a string specifying the alternate backup location. The path of this - /// location can be a local path or the UNC path of a remote file share. If there is no alternate location, the pointer is NULL. - /// - /// - /// The following are the valid return codes for this method. - /// - /// - /// Value - /// Meaning - /// - /// - /// S_OK - /// Successfully returned the alternate location information. - /// - /// - /// S_FALSE - /// The requested information could not be found. - /// - /// - /// E_INVALIDARG - /// One of the parameter values is not valid. - /// - /// - /// E_OUTOFMEMORY - /// The caller is out of memory or other system resources. - /// - /// - /// 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_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. - /// - /// - /// - /// - /// - /// - /// 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 caller must call SysFreeString to free the memory held by the pbstrAlternateLocation parameter. - /// - /// The interpretation of the alternate location returned by GetAlternateLocation differs depending on the method used to - /// retrieve the IVssWMFiledesc object. - /// - /// - /// - /// IVssExamineWriterMetadata::GetExcludeFile - /// - /// - /// IVssWMComponent::GetDatabaseFile - /// - /// - /// IVssWMComponent::GetDatabaseLogFile - /// - /// - /// IVssWMComponent::GetFile - /// - /// - /// - /// The value returned by GetAlternateLocation refers to an alternate location mapping when returned by the - /// IVssExamineWriterMetadata::GetAlternateLocationMapping method. - /// - /// - /// During backup operations, this is the alternate location from which to back up a file. During a restore, it is the alternate - /// location to which to restore a file. - /// - /// For more information, see Non-Default Backup And Restore Locations. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsswmfiledesc-getalternatelocation HRESULT - // GetAlternateLocation( [out] BSTR *pbstrAlternateLocation ); - [PreserveSig] - HRESULT GetAlternateLocation([MarshalAs(UnmanagedType.BStr)] out string pbstrAlternateLocation); - - /// - /// The GetBackupTypeMask method returns the file backup specification for the files specified by the current file - /// descriptor as a bit mask (or bitwise OR) of VSS_FILE_SPEC_BACKUP_TYPE values. This information indicates if the files are to - /// be evaluated by their writer for participation in various specific types of backup operations (or if they will participate - /// in an incremental or differential backups). - /// - /// - /// Pointer to a DWORD containing a bit mask (or bitwise OR) of VSS_FILE_SPEC_BACKUP_TYPE values indicating the file - /// backup specification for the file or file set described by the current IVssWMFiledesc interface. - /// - /// - /// The following are the valid return codes for this method. - /// - /// - /// Value - /// Meaning - /// - /// - /// S_OK - /// Successfully returned the filespec information. - /// - /// - /// E_INVALIDARG - /// The pdwTypeMask variable points to a NULL region of memory. - /// - /// - /// E_OUTOFMEMORY - /// The caller is out of memory or other system resources. - /// - /// - /// 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_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. - /// - /// - /// - /// - /// - /// A file backup specification is specified by a writer when it adds a file specification to a component using the - /// IVssCreateWriterMetadata::AddFilesToFileGroup, IVssCreateWriterMetadata::AddDatabaseFiles, or - /// IVssCreateWriterMetadata::AddDatabaseLogFiles method. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsswmfiledesc-getbackuptypemask HRESULT - // GetBackupTypeMask( DWORD *pdwTypeMask ); - [PreserveSig] - HRESULT GetBackupTypeMask(out uint pdwTypeMask); - - /// - /// - /// The GetFilespec method returns the file specification used to obtain the list of files that the current - /// IVssWMFiledesc object is a member of. - /// - /// A querying method used a path and this file specification to return the current IVssWMFiledesc object. - /// - /// - /// The address of a caller-allocated variable that receives a string specifying the returned file specification. - /// - /// A file specification cannot contain directory specifications (for example, no backslashes) but can contain the ? and * - /// wildcard characters. - /// - /// - /// - /// The following are the valid return codes for this method. - /// - /// - /// Value - /// Meaning - /// - /// - /// S_OK - /// Successfully returned the filespec information. - /// - /// - /// E_INVALIDARG - /// One of the parameter values is not valid. - /// - /// - /// E_OUTOFMEMORY - /// The caller is out of memory or other system resources. - /// - /// - /// 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_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. - /// - /// - /// - /// - /// The caller must call SysFreeString to free the memory held by the pbstrFilespec parameter. - // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsswmfiledesc-getfilespec HRESULT GetFilespec( [out] - // BSTR *pbstrFilespec ); - [PreserveSig] - HRESULT GetFilespec([MarshalAs(UnmanagedType.BStr)] out string pbstrFilespec); - - /// - /// - /// The GetPath method obtains the fully qualified directory path or the UNC path of the remote file share to obtain the - /// list of files described in the current IVssWMFiledesc object. - /// - /// A querying method used this path and a file specification to return the current IVssWMFiledesc object. - /// - /// - /// - /// The address of a caller-allocated variable that receives a NULL-terminated wide character string specifying the fully - /// qualified directory path or the UNC path of the remote file share directory. - /// - /// The path can be a long or short file name and can use the prefix "\?". For more information, see Naming a File. - /// Users of this method need to check to determine whether this path ends with a backslash (""). - /// - /// - /// The following are the valid return codes for this method. - /// - /// - /// Value - /// Meaning - /// - /// - /// S_OK - /// Successfully returned the path information. - /// - /// - /// E_INVALIDARG - /// One of the parameter values is not valid. - /// - /// - /// E_OUTOFMEMORY - /// The caller is out of memory or other system resources. - /// - /// - /// 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_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. - /// - /// - /// - /// - /// - /// - /// 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 caller must call SysFreeString to free the memory held by the pbstrPath parameter. - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsswmfiledesc-getpath HRESULT GetPath( [out] BSTR - // *pbstrPath ); - [PreserveSig] - HRESULT GetPath([MarshalAs(UnmanagedType.BStr)] out string pbstrPath); - - /// - /// The GetRecursive method indicates whether the list of files described in a IVssWMFiledesc object with a root - /// directory returned by IVssWMFiledesc::GetPath contains only files in that directory or whether the file list contains files - /// from the directory hierarchy as well. - /// - /// - /// - /// A pointer to a Boolean value specifying whether the value returned by IVssWMFiledesc::GetPath identifies only a single - /// directory or if it indicates a hierarchy of directories to be traversed recursively. The Boolean value receives true - /// if the path is treated as a hierarchy of directories to be traversed recursively, or false if not. - /// - /// For information on traversing over mounted folders, see Working with Mounted Folders and Reparse Points. - /// - /// - /// The following are the valid return codes for this method. - /// - /// - /// Value - /// Meaning - /// - /// - /// S_OK - /// Successfully returned the recursive information. - /// - /// - /// E_INVALIDARG - /// One of the parameter values is not valid. - /// - /// - /// E_OUTOFMEMORY - /// The caller is out of memory or other system resources. - /// - /// - /// 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. - /// - /// - /// - /// 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. - /// - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsswmfiledesc-getrecursive HRESULT GetRecursive( - // [out] bool *pbRecursive ); - [PreserveSig] - HRESULT GetRecursive(out bool pbRecursive); - } - - /// - /// - /// The IVssWriterComponents interface is a C++ (not COM) interface that contains methods used to obtain and modify component - /// information (in the form of IVssComponent objects) associated with a given writer but stored in a requester's Backup Components Document. - /// - /// - /// The CVssWriter base class is responsible for passing an instance of the IVssWriterComponents interface to the following - /// event handlers: - /// - /// - /// - /// CVssWriter::OnPrepareBackup - /// - /// - /// CVssWriter::OnBackupComplete - /// - /// - /// CVssWriter::OnPreRestore - /// - /// - /// CVssWriter::OnPostRestore - /// - /// - /// CVssWriter::OnPostSnapshot - /// - /// - /// - /// In addition, an instance of the IVssWriterComponentsExt interface, which implements a requester-side version of the - /// IVssWriterComponents interface, is returned by IVssBackupComponents::GetWriterComponents. - /// - /// IVssWriterComponents defines the following methods. - /// - /// - /// Method - /// Description - /// - /// - /// GetComponent - /// Returns the components belonging to a given writer instance. - /// - /// - /// GetComponentCount - /// Returns the number of components belonging to a given writer instance. - /// - /// - /// GetWriterInfo - /// Returns the instance and class identifier of the writer responsible for the components. - /// - /// - /// - // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nl-vswriter-ivsswritercomponents - [PInvokeData("vswriter.h", MSDNShortId = "NL:vswriter.IVssWriterComponents")] - private interface IVssWriterComponents - { } - - /// Creates an IVssExpressWriter interface object and returns a pointer to it. - /// Doubly indirect pointer to the newly created IVssExpressWriter object. /// + /// The address of a caller-allocated variable that receives a VSS_FILE_RESTORE_STATUS enumeration value that specifies whether all + /// files were successfully restored. + /// + /// + /// This method should be called only following a PostRestore event. /// - /// The return values listed here are in addition to the normal COM HRESULT values that may be returned at any time from the function. + /// The status returned is undefined if this method is applied to a component that has not been selected for restore by being added + /// to the Backup Components via IVssBackupComponents::AddComponent. /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getfilerestorestatus HRESULT + // GetFileRestoreStatus( [out] VSS_FILE_RESTORE_STATUS *pStatus ); + VSS_FILE_RESTORE_STATUS FileRestoreStatus { get; } + + /// + /// The IsSelectedForRestore method determines whether the current component has been selected to be restored. + /// Either a writer or a requester can call this method. + /// + /// + /// The address of a caller-allocated variable that receives true if the component has been selected to be restored, or + /// false otherwise. + /// + /// + /// IsSelectedForRestore is relevant only under component mode. + /// If the component defines a component set, IsSelectedForRestore refers both to the component and all of its subcomponents. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-isselectedforrestore HRESULT + // IsSelectedForRestore( [out] bool *pbSelectedForRestore ); + bool IsSelectedForRestore { get; } + + /// + /// The GetLogicalPath method returns the logical path of this component. + /// Either a writer or a requester can call this method. + /// + /// Pointer to a string containing the logical path of the component. + /// + /// The caller should free the memory held by the pbstrPath parameter by calling SysFreeString. + /// Logical paths are not required of components. A component without a logical path will return S_FALSE. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getlogicalpath HRESULT GetLogicalPath( + // [out] BSTR *pbstrPath ); + string LogicalPath { get; } + + /// + /// + /// The NewTargets property returns the new file restoration locations. (See Working with Selectability and Logical Paths for + /// information on selecting components.) + /// + /// Either a writer or a requester can call this method. + /// + /// List of IVssWMFiledesc objects containing the new target restore locations information. + /// + /// New targets returned by NewTargets may be those not only of files in the current component but to files in any of its + /// nonselectable subcomponents. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getnewtarget HRESULT GetNewTarget( [in] + // UINT iNewTarget, [out] IVssWMFiledesc **ppFiledesc ); + IReadOnlyList NewTargets { get; } + + /// The PartialFiles property returns information on the partial files associated with this component. + /// + /// A range indicates a subsection of a given file that is to be backed up, independent of the rest of the file. + /// + /// The syntax of the range listing (pbstrRanges) 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. + /// + /// + /// If pbstrRanges refers to a file containing all the offsets and lengths (a ranges file), pbstrRanges should contain the full path + /// to the file. + /// + /// + /// If wszRange refers to a file containing all the offsets and lengths (a ranges file), wszRange should contain the full path to + /// the file. + /// + /// A ranges file must be a binary file with the following format: + /// + /// + /// A 64-bit integer indicating the number of distinct file ranges that need to be backed up. + /// + /// + /// + /// Each range expressed as a pair of 64-bit integers: the offset into the file being backed up, in bytes, and the length of data + /// starting from that offset to be backed up. + /// + /// + /// + /// + /// A ranges file should have been backed up along with the partial file and typically is restored to the same location that it was + /// backed up from. + /// + /// + /// However, the location to which a ranges file is restored might be altered by the requester, which uses + /// IVssBackupComponents::SetRangesFilePath to indicate this and to update the Backup Components Document so that pbstrRanges + /// indicates the correct ranges file. + /// + /// + /// A requester would use the ranges information returned by GetPartialFile to restore the backed-up sections to the + /// appropriate location within the copy of the file on disk at restore time. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getpartialfile HRESULT GetPartialFile( [in] + // UINT iPartialFile, [out] BSTR *pbstrPath, [out] BSTR *pbstrFilename, [out] BSTR *pbstrRange, [out] BSTR *pbstrMetadata ); + IAppendOnlyList PartialFiles { get; } + + /// + /// + /// The GetPostRestoreFailureMsg method returns the failure message generated by a writer while handling the PostRestore + /// event, if IVssComponent::SetPostRestoreFailureMsg set one. + /// + /// Either a writer or a requester can call this method. + /// + /// + /// Pointer to a string containing the failure message that describes an error that occurred while processing the PostRestore event. + /// + /// + /// The caller should free the memory held by the pbstrPostRestoreFailureMsg parameter by calling SysFreeString. + /// If SetPostRestoreFailureMsg was not used to set a PostRestore failure message, GetPreRestoreFailureMsg returns S_FALSE. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getpostrestorefailuremsg HRESULT + // GetPostRestoreFailureMsg( [out] BSTR *pbstrPostRestoreFailureMsg ); + string PostRestoreFailureMsg { get; set; } + + /// + /// Returns the PostSnapshot failure message string that a writer has set for a given component. + /// + /// Both writers and requesters can call this method. Writers should call this method after the IVssBackupComponents::DoSnapshotSet + /// asynchronous operation has completed. + /// + /// + /// + /// A pointer to a null-terminated wide character string containing the failure message that describes an error that occurred while + /// processing a PostSnapshot event. + /// + /// + /// The caller is responsible for freeing the string that the pbstrFailureMsg parameter points to by calling the SysFreeString function. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponentex-getpostsnapshotfailuremsg HRESULT + // GetPostSnapshotFailureMsg( [out] BSTR *pbstrFailureMsg ); + string PostSnapshotFailureMsg { get; set; } + + /// + /// Returns the PrepareForBackup failure message string that a writer has set for a given component. + /// Both writers and requesters can call this method. + /// + /// + /// A pointer to a null-terminated wide character string containing the failure message that describes an error that occurred while + /// processing a PrepareForBackup event. + /// + /// + /// + /// The caller is responsible for freeing the string that the pbstrFailureMsg parameter points to by calling the SysFreeString function. + /// + /// Examples + /// + /// #include <windows.h> #include "vss.h" #include "vsmgmt.h" #define CHKARG_ASSERT(EXPR) do { if(! ( EXPR ) ) { assert(FALSE); hr = E_INVALIDARG; goto exit; } } while ( FALSE, FALSE ); #define CHK(HR) do { hr = ( HR ) ; if(FAILED(HR)) { hr = HR; goto exit; } } while ( FALSE, FALSE ); STDMETHODIMP CheckAsrBackupErrorMsg ( IVssBackupComponents *pBackup, const WCHAR *pwszWriterName ) { CComPtr<IVssWriterComponentsExt> spWriter; CComPtr<IVssComponent> spComponent; CComPtr<IVssComponentEx> spComponentEx; UINT cWriterComponents = 0; UINT iWriterComponent = 0; UINT cComponents = 0; UINT iComponent = 0; VSS_ID idWriter; VSS_ID idInstance; CComBSTR bstrFailureMsg; HRESULT hr = S_OK; CHKARG_ASSERT( pBackup ); CHKARG_ASSERT( pwszWriterName ); CHK( pBackup->GetWriterComponentsCount( &cWriterComponents ) ); for( iWriterComponent = 0; iWriterComponent < cWriterComponents; iWriterComponent++ ) { spWriter.Release(); CHK( pBackup->GetWriterComponents( iWriterComponent, &spWriter ) ); CHK( spWriter->GetWriterInfo(&idInstance, &idWriter) ); if( idWriter != c_ASRWriterId ) { continue; } CHK( spWriter->GetComponentCount(&cComponents) ); for( iComponent = 0; iComponent < cComponents; iComponent++ ) { spComponent.Release(); spComponentEx.Release(); CHK( spWriter->GetComponent(iComponent, &spComponent) ); CHK( spComponent->QueryInterface(__uuidof(IVssComponentEx), (void**)&spComponentEx) ); bstrFailureMsg.Empty(); CHK( spComponentEx->GetPrepareForBackupFailureMsg(&bstrFailureMsg) ); if( ::SysStringLen(bstrFailureMsg) != 0 ) { // Write into the event log. Log_SPP_ERROR_WRITER( &ft, __LINE__, pwszWriterName, bstrFailureMsg ); // The ASR writer writes the same message to all components. // Log the message once. break; } } } exit: return hr; } + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponentex-getprepareforbackupfailuremsg HRESULT + // GetPrepareForBackupFailureMsg( [out] BSTR *pbstrFailureMsg ); + string PrepareForBackupFailureMsg { get; set; } + + /// + /// + /// The GetPreRestoreFailureMsg method retrieves the error message generated by a writer while handling the PreRestore event, + /// if IVssComponent::SetPreRestoreFailureMsg set one. + /// + /// Either a writer or a requester can call this method. + /// + /// String containing the failure message that describes an error that occurred while processing the PreRestore event. + /// + /// The caller should free the memory held by the pbstrPreRestoreFailureMsg parameter by calling SysFreeString. + /// If SetPreRestoreFailureMsg was not used to set a PreRestore failure message, GetPreRestoreFailureMsg returns S_FALSE. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getprerestorefailuremsg HRESULT + // GetPreRestoreFailureMsg( [out] BSTR *pbstrPreRestoreFailureMsg ); + string PreRestoreFailureMsg { get; set; } + + /// + /// + /// The GetPreviousBackupStamp method returns 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. + /// + /// Either a writer or a requester can call this method. + /// + /// + /// Pointer to a string containing the time stamp of a previous backup so that a differential or incremental backup can be correctly implemented. + /// + /// + /// + /// For more information about backup stamps, see Writer Role in Backing Up Complex Stores and Requester Role in Backing Up Complex Stores. + /// + /// The caller should free the memory held by the pbstrBackupStamp parameter by calling SysFreeString. + /// If there is no previous backup time stamp, GetPreviousBackupStamp returns S_FALSE. + /// The string returned refers to all files in the component and any nonselectable subcomponents it has. + /// The backup stamp retrieved by GetPreviousBackupStamp is set by a requester using IVssBackupComponents::SetPreviousBackupStamp. + /// + /// Typically, the string used to set the value found by GetPreviousBackupStamp was retrieved from a stored Backup Components + /// Document or was stored by the requester as part of its own internal records. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getpreviousbackupstamp HRESULT + // GetPreviousBackupStamp( [out] BSTR *pbstrBackupStamp ); + string PreviousBackupStamp { get; } + + /// + /// + /// The GetRestoreMetadata method retrieves private, writer-specific restore metadata that might have been set during a + /// PreRestore event by CVssWriter::OnPreRestore using IVssComponent::SetRestoreMetadata. + /// + /// Only a writer can call this method. + /// + /// A string containing the restore metadata. + /// + /// This method can be called at any time depending on the logic of a given writer. + /// The caller should free the memory held by the pbstrRestoreMetadata parameter by calling SysFreeString. + /// If no backup metadata has been set, GetBackupMetadata returns S_FALSE. + /// + /// A writer setting the restore method to VSS_RME_RESTORE_TO_ALTERNATE_LOCATION without defining an alternate location mapping + /// constitutes a writer error. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getrestoremetadata HRESULT + // GetRestoreMetadata( [out] BSTR *pbstrRestoreMetadata ); + string RestoreMetadata { get; set; } + + /// Obtains the logical name assigned to a component that is being restored. + /// + /// The address of a caller-allocated variable that receives a null-terminated wide character string containing the restore name for + /// the component. + /// + /// + /// The GetRestoreName method can only be called during a restore operation. + /// + /// If the call to GetRestoreName is successful, the caller is responsible for freeing the string that is returned in the pbstrName + /// parameter by calling the SysFreeString function. + /// + /// + /// A writer indicates that it supports this method by setting the VSS_BS_RESTORE_RENAME flag in its backup schema mask. + /// + /// For more information, see Setting VSS Restore Options. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponentex-getrestorename HRESULT GetRestoreName( + // [out] BSTR *pbstrName ); + string RestoreName { get; } + + /// + /// The GetRestoreOptions method gets the restore options specified to the current writer by a requester using IVssBackupComponents::SetRestoreOptions. + /// Either a writer or a requester can call this method. + /// + /// String containing the restore options of the writer. + /// + /// The caller should free the memory held by the pbstrRestoreOptions parameter by calling SysFreeString. + /// If no restore options have been set, S_FALSE is returned. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getrestoreoptions HRESULT + // GetRestoreOptions( [out] BSTR *pbstrRestoreOptions ); + string RestoreOptions { get; } + + /// + /// The RestoreSubcomponents property returns the subcomponents associated with a given component. + /// Either a writer or a requester can call this method. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getrestoresubcomponent HRESULT + // GetRestoreSubcomponent( [in] UINT iComponent, [out] BSTR *pbstrLogicalPath, [out] BSTR *pbstrComponentName, [out] bool *pbRepair ); + IReadOnlyList RestoreSubcomponents { get; } + + /// + /// + /// The GetRestoreTarget method returns the restore target (in terms of the VSS_RESTORE_TARGET enumeration) for the current component. + /// + /// Either a writer or a requester can call this method. It can be called only during a restore operation. + /// + /// + /// The address of a caller-allocated variable that receives a VSS_RESTORE_TARGET enumeration value that specifies the restore target. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponent-getrestoretarget HRESULT GetRestoreTarget( + // [out] VSS_RESTORE_TARGET *pTarget ); + VSS_RESTORE_TARGET RestoreTarget { get; set; } + + /// VSS requesters call this method to retrieve component-level errors reported by writers. + /// + /// + /// The address of a caller-allocated variable that receives the HRESULT failure code that the writer passed for the hr parameter of + /// the IVssComponentEx2::SetFailure method. This parameter is required and cannot be NULL. + /// + /// The following are the supported values. /// /// /// Value @@ -1625,22 +1405,1875 @@ namespace Vanara.PInvoke /// /// /// S_OK - /// Successfully returned a pointer to an IVssExpressWriter interface. + /// The writer was successful. /// /// - /// E_ACCESSDENIED - /// The caller does not have sufficient privileges. + /// VSS_E_WRITERERROR_INCONSISTENTSNAPSHOT + /// The shadow copy contains only a subset of the volumes needed by the writer to correctly back up the application component. /// /// - /// E_INVALIDARG - /// One of the parameters is not valid. + /// VSS_E_WRITERERROR_OUTOFRESOURCES + /// + /// The writer ran out of memory or other system resources. The recommended way to handle this error code is to wait ten minutes and + /// then repeat the operation, up to three times. + /// + /// + /// + /// VSS_E_WRITERERROR_TIMEOUT + /// + /// The writer operation failed because of a time-out between the Freeze and Thaw events. The recommended way to handle this error + /// code is to wait ten minutes and then repeat the operation, up to three times. + /// + /// + /// + /// VSS_E_WRITERERROR_RETRYABLE + /// + /// The writer failed due to an error that would likely not occur if the entire backup, restore, or shadow copy creation process was + /// restarted. The recommended way to handle this error code is to wait ten minutes and then repeat the operation, up to three times. + /// + /// + /// + /// VSS_E_WRITERERROR_NONRETRYABLE + /// + /// The writer operation failed because of an error that might recur if another shadow copy is created. For more information, see + /// Event and Error Handling Under VSS. + /// + /// + /// + /// VSS_E_WRITER_NOT_RESPONDING + /// The writer is not responding. + /// + /// + /// VSS_E_WRITER_STATUS_NOT_AVAILABLE + /// + /// The writer status is not available for one or more writers. A writer may have reached the maximum number of available backup and + /// restore sessions. + /// /// /// + /// + /// + /// The address of a caller-allocated variable that receives the return code that the writer passed for the hrApplication parameter + /// of the SetFailure method. This parameter is required and cannot be NULL. + /// + /// + /// The address of a caller-allocated variable that receives the application failure message that the writer passed for the + /// wszApplicationMessage parameter of the SetFailure method. This parameter is required and cannot be NULL. + /// + /// + /// When the caller has finished accessing the status information returned by this method, it should call SysFreeString to free the + /// memory held by the pbstrApplicationMessage parameter. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponentex2-getfailure HRESULT GetFailure( [out] + // HRESULT *phr, [out] HRESULT *phrApplication, [out] BSTR *pbstrApplicationMessage, [out] DWORD *pdwReserved ); + void GetFailure(out HRESULT phr, out HRESULT phrApplication, out string pbstrApplicationMessage); + + /// + /// Obtains the roll-forward operation type for a component and obtains the restore point for a partial roll-forward operation. + /// + /// A VSS_ROLLFORWARD_TYPE enumeration value indicating the type of roll-forward operation to be performed. + /// + /// The address of a caller-allocated variable that receives a null-terminated wide character string specifying the roll-forward + /// restore point. + /// + /// + /// The GetRollForward method can be called only during a restore operation. + /// + /// If the call to GetRollForward is successful, the caller is responsible for freeing the string that is returned in the + /// pRollType parameter by calling the SysFreeString function. + /// + /// + /// A writer indicates that it supports this method by setting the VSS_BS_ROLLFORWARD_RESTORE flag in its backup schema mask. + /// + /// For more information, see Setting VSS Restore Options. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponentex-getrollforward HRESULT GetRollForward( + // [out] VSS_ROLLFORWARD_TYPE *pRollType, [out] BSTR *pbstrPoint ); + void GetRollForward(out VSS_ROLLFORWARD_TYPE pRollType, out string pbstrPoint); + + /// VSS writers call this method to report errors at the component level. + /// + /// The error code to be returned to the requester that calls the IVssComponentEx2::GetFailure method. + /// The following are the error codes that this method can set. + /// + /// + /// Value + /// Meaning + /// + /// + /// S_OK + /// The writer was successful. + /// + /// + /// VSS_E_WRITERERROR_INCONSISTENTSNAPSHOT + /// The shadow copy contains only a subset of the volumes needed by the writer to correctly back up the application component. + /// + /// + /// VSS_E_WRITERERROR_OUTOFRESOURCES + /// + /// The writer ran out of memory or other system resources. The recommended way to handle this error code is to wait ten minutes and + /// then repeat the operation, up to three times. + /// + /// + /// + /// VSS_E_WRITERERROR_TIMEOUT + /// + /// The writer operation failed because of a time-out between the Freeze and Thaw events. The recommended way to handle this error + /// code is to wait ten minutes and then repeat the operation, up to three times. + /// + /// + /// + /// VSS_E_WRITERERROR_RETRYABLE + /// + /// The writer failed due to an error that would likely not occur if the entire backup, restore, or shadow copy creation process was + /// restarted. The recommended way to handle this error code is to wait ten minutes and then repeat the operation, up to three times. + /// + /// + /// + /// VSS_E_WRITERERROR_NONRETRYABLE + /// + /// The writer operation failed because of an error that might recur if another shadow copy is created. For more information, see + /// Event and Error Handling Under VSS. + /// + /// + /// + /// + /// An additional error code to be returned to the requester. This parameter is optional. + /// + /// A string containing an error message for the requester to display to the end user. The writer is responsible for localizing this + /// string if necessary before using it in this method. This parameter is optional and can be NULL or an empty string. + /// + /// + /// + /// In addition to calling this method, use the CVssWriterEx2::SetWriterFailureEx method to report that a partial writer failure has occurred. + /// + /// This method cannot be called from CVssWriter::OnIdentify or CVssWriterEx::OnIdentifyEx. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscomponentex2-setfailure HRESULT SetFailure( [in] + // HRESULT hr, [in] HRESULT hrApplication, [in] LPCWSTR wszApplicationMessage, [in] DWORD dwReserved ); + void SetFailure(HRESULT hr, HRESULT hrApplication, [Optional] string wszApplicationMessage); + } + + /// + /// + /// The IVssCreateExpressWriterMetadata interface is a COM interface containing methods to construct the Writer Metadata Document + /// for an express writer. + /// + /// + /// After it is constructed, the Writer Metadata Document is a read-only object that requesters query for information about a writer and + /// its components. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nl-vswriter-ivsscreateexpresswritermetadata + [PInvokeData("vswriter.h", MSDNShortId = "NL:vswriter.IVssCreateExpressWriterMetadata")] + [ComImport, Guid("9c772e77-b26e-427f-92dd-c996f41ea5e3"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IVssCreateExpressWriterMetadata + { + /// + /// Excludes a file set (a specified file or files) that might otherwise be implicitly included when a component of an express + /// writer is backed up. + /// + /// + /// A pointer to a null-terminated wide character string containing the root directory under which files are to be excluded. + /// The path can contain environment variables (for example, %SystemRoot%) but cannot contain wildcard characters. + /// + /// There is no requirement that the path end with a backslash (\). It is up to applications that retrieve this information to check. + /// + /// + /// + /// A pointer to a null-terminated wide character string containing the file specification of the files to be excluded. + /// + /// A file specification cannot contain directory specifications (for example, no backslashes) but can contain the ? and * wildcard characters. + /// + /// + /// + /// + /// A Boolean value specifying whether the path specified by the wszPath parameter identifies only a single directory or if it + /// indicates a hierarchy of directories to be traversed recursively. This parameter should be set to true if the path is + /// treated as a hierarchy of directories to be recursed through, or false otherwise. + /// + /// For information on traversing over mounted folders, see Working with Mounted Folders and Reparse Points. + /// + /// + /// + /// Express writers support only local resources—sets of files whose absolute path starts with a valid local volume specification + /// and cannot be a mapped network drive. Therefore, path inputs (wszPath) to AddExcludeFiles (after the resolution of any + /// environment variables) must be in this format. For example, it is often convenient to define a component to include all files in + /// a specified directory and then use AddExcludeFiles to explicitly remove some files (for instance, temporary files) from a backup. + /// + /// For more information on excluding files, see Exclude File List Specification. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreateexpresswritermetadata-addexcludefiles HRESULT + // AddExcludeFiles( [in] LPCWSTR wszPath, [in] LPCWSTR wszFilespec, [in] bool bRecursive ); + void AddExcludeFiles([MarshalAs(UnmanagedType.LPWStr)] string wszPath, [MarshalAs(UnmanagedType.LPWStr)] string wszFilespec, bool bRecursive); + + /// Adds a file group to an express writer's set of components to be backed up. + /// + /// A VSS_COMPONENT_TYPE enumeration value that specifies the type of the component. Only VSS_CT_FILEGROUP is supported for + /// this parameter. + /// + /// + /// + /// A pointer to a null-terminated wide character string containing the logical path of the database or file group. For more + /// information, see Logical Pathing of Components. + /// + /// This parameter is optional and can be NULL. + /// + /// + /// A pointer to a null-terminated wide character string containing the name of the component. This string is not localized. + /// This parameter is required and cannot be NULL. The string cannot contain backslashes. + /// + /// + /// + /// A pointer to a null-terminated wide character string containing a description (also called a "friendly name") for the + /// component. This string might be localized, and therefore requesters must assume that it is localized. + /// + /// This parameter is optional and can be NULL. The string can contain backslashes. + /// + /// + /// + /// A pointer to a bitmap of the icon representing the database, to be displayed in a user interface. The size, in bytes, of the + /// buffer is specified by the cbIcon parameter. + /// + /// This parameter is optional and can be NULL. + /// + /// The number of bytes in . + /// This parameter is reserved for future use and should always be set to false. + /// This parameter is reserved for future use and should always be set to false. + /// + /// A Boolean value that indicates whether the component can be optionally backed up (which means it can be excluded from the + /// backup) or is always backed up when any of the writer's components is backed up. This parameter should be set to true if + /// the component can be selectively backed up, or false if the component is backed up when any of the components is backed up. + /// + /// + /// + /// A Boolean value that determines whether a component can be individually restored when it has not been explicitly included in the + /// backup document. If the component was explicitly added to the backup document, it can always be individually selected for + /// restore; in this case, this flag has no meaning. + /// + /// + /// When this parameter is true, the component can be restored by itself; when false, the component can be restored + /// only if the entire component set is being restored. (For more information, see VSS_COMPONENTINFO and Working with Selectability + /// and Logical Paths.) + /// + /// The default value for this parameter is false. + /// + /// + /// + /// A bitmask of VSS_COMPONENT_FLAGS enumeration values indicating the features that this component supports. This bitmask cannot + /// include VSS_CF_APP_ROLLBACK_RECOVERY or VSS_CF_BACKUP_RECOVERY. + /// + /// The default value for this parameter is zero. + /// + /// + /// This method can be called multiple times to add several components to an express writer's metadata. + /// + /// The combination of logical path and name for each component of a specified instance of a specified class of writer must be + /// unique. Attempting to call AddComponent twice with the same values of wszLogicalPath and wszComponentName results in a + /// VSS_E_OBJECT_ALREADY_EXISTS error. + /// + /// + /// AddComponent can be used to add subcomponents—components in which all member files are backed up as a group but which + /// contain files that can be restored individually. For more information, see Working with Selectability for Restore and Subcomponents. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreateexpresswritermetadata-addcomponent HRESULT + // AddComponent( [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] LPCWSTR wszComponentName, [in] LPCWSTR wszCaption, + // [in] const BYTE *pbIcon, [in] UINT cbIcon, [in] bool bRestoreMetadata, [in] bool bNotifyOnBackupComplete, [in] bool bSelectable, + // [in] bool bSelectableForRestore, [in] DWORD dwComponentFlags ); + void AddComponent(VSS_COMPONENT_TYPE ct, [MarshalAs(UnmanagedType.LPWStr)] string wszLogicalPath, + [MarshalAs(UnmanagedType.LPWStr)] string wszComponentName, [MarshalAs(UnmanagedType.LPWStr)] string wszCaption, + IntPtr pbIcon, uint cbIcon, bool bRestoreMetadata, bool bNotifyOnBackupComplete, bool bSelectable, bool bSelectableForRestore = false, + VSS_COMPONENT_FLAGS dwComponentFlags = 0); + + /// Adds a file set (a specified file or files) to a specified file group component for an express writer. + /// + /// A pointer to a null-terminated wide character string containing the logical path (which may be NULL) of the + /// component to which to add the files. For more information, see Logical Pathing of Components. + /// + /// + /// A pointer to a null-terminated wide character string containing the name of the file group component. The type of this + /// component must be VSS_CT_FILEGROUP; otherwise, the method will return an error. + /// + /// + /// A pointer to a null-terminated wide character string containing the default root directory of the files to be added. + /// The path can contain environment variables (for example, %SystemRoot%) but cannot contain wildcard characters. + /// + /// There is no requirement that the path end with a backslash (\). It is up to applications that retrieve this information to check. + /// + /// + /// + /// A pointer to a null-terminated wide character string containing the file specification of the files to be included. + /// + /// A file specification cannot contain directory specifications (for example, no backslashes) but can contain the ? and * wildcard characters. + /// + /// + /// + /// + /// A Boolean value specifying whether the path specified by the wszPath parameter identifies only a single directory or if it + /// indicates a hierarchy of directories to be traversed recursively. This parameter should be set to true if the path is + /// treated as a hierarchy of directories to be recursed through, or false otherwise. + /// + /// For information on traversing over mounted folders, see Working with Mounted Folders and Reparse Points. + /// + /// This parameter is reserved and must be NULL. + /// + /// + /// A bitmask of VSS_FILE_SPEC_BACKUP_TYPE enumeration values to indicate if a writer should evaluate the file for participation in + /// a certain type of backup operations. + /// + /// + /// This parameter cannot include VSS_FSBT_DIFFERENTIAL_BACKUP_REQUIRED, VSS_FSBT_INCREMENTAL_BACKUP_REQUIRED, or VSS_FSBT_LOG_BACKUP_REQUIRED. + /// + /// The default value for this argument is (VSS_FSBT_ALL_BACKUP_REQUIRED | VSS_FSBT_ALL_SNAPSHOT_REQUIRED). + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreateexpresswritermetadata-addfilestofilegroup + // HRESULT AddFilesToFileGroup( [in] LPCWSTR wszLogicalPath, [in] LPCWSTR wszGroupName, [in] LPCWSTR wszPath, [in] LPCWSTR + // wszFilespec, [in] bool bRecursive, [in] LPCWSTR wszAlternateLocation, [in] DWORD dwBackupTypeMask ); + void AddFilesToFileGroup([MarshalAs(UnmanagedType.LPWStr)] string wszLogicalPath, [MarshalAs(UnmanagedType.LPWStr)] string wszGroupName, + [MarshalAs(UnmanagedType.LPWStr)] string wszPath, [MarshalAs(UnmanagedType.LPWStr)] string wszFilespec, bool bRecursive, + [MarshalAs(UnmanagedType.LPWStr)] string wszAlternateLocation, + VSS_FILE_SPEC_BACKUP_TYPE dwBackupTypeMask = VSS_FILE_SPEC_BACKUP_TYPE.VSS_FSBT_ALL_BACKUP_REQUIRED | VSS_FILE_SPEC_BACKUP_TYPE.VSS_FSBT_ALL_SNAPSHOT_REQUIRED); + + /// Specifies how an express writer's data is to be restored. + /// + /// A VSS_RESTOREMETHOD_ENUM enumeration value specifying the restore method to be used in the restore operation. This parameter is + /// required and cannot be VSS_RME_UNDEFINED, VSS_RME_RESTORE_TO_ALTERNATE_LOCATION, or VSS_RME_CUSTOM. + /// + /// + /// + /// A pointer to a wide character string containing the name of a service that must be stopped prior to a restore operation and then + /// started after the restore operation takes place, if the value of method is VSS_RME_STOP_RESTORE_START or VSS_RME_RESTORE_STOP_START. + /// + /// + /// If the value of method is not VSS_RME_STOP_RESTORE_START or VSS_RME_RESTORE_STOP_START, this parameter is not used + /// and should be set to NULL. + /// + /// + /// Reserved for future use. The value of this parameter should always be set to NULL. + /// + /// A VSS_WRITERRESTORE_ENUM enumeration value specifying whether the writer will be involved in restoring its data. This parameter + /// must be set to VSS_WRE_NEVER. + /// + /// A Boolean value indicating whether a reboot will be required after the restore operation is complete. + /// + /// + /// An express writer can define only one restore method. If the restore method is not overridden, all of the express writer's + /// components will be restored using the same method. + /// + /// + /// Express writers override the restore method on a component-by-component basis by setting a restore target, typically while + /// handling a PreRestore event (CVssWriter::OnPreRestore). + /// + /// + /// It is important to note that despite the fact that restore methods are applied on a per-writer basis, methods are implemented on + /// a per-component basis. For example, if the method specified by the method parameter is VSS_RME_RESTORE_IF_CAN_REPLACE, + /// then all of the files in the component are restored to their original location if they can all be replaced without an error + /// occurring. Otherwise, they are restored to their alternate location if one is specified. + /// + /// A file can be restored to an alternate location mapping if either of the following is true: + /// + /// + /// The restore method is VSS_RME_RESTORE_IF_NOT_THERE, and a version of the file is already present on disk. + /// + /// + /// + /// The restore method is VSS_RME_RESTORE_IF_CAN_REPLACE, and a version of the file is present on disk and cannot be replaced. + /// + /// + /// + /// If no valid alternate location mapping is defined, this is a writer error. + /// For more information about restore methods, see Setting VSS Restore Methods. + /// + /// If the restore method is VSS_RME_STOP_RESTORE_START or VSS_RME_RESTORE_STOP_START, then the correct name of the service must be + /// provided as the wszService argument. For information on writer participation in stopping and restarting services during a + /// restore operation, see Stopping Services for Restore by Requesters. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreateexpresswritermetadata-setrestoremethod HRESULT + // SetRestoreMethod( [in] VSS_RESTOREMETHOD_ENUM method, [in] LPCWSTR wszService, [in] LPCWSTR wszUserProcedure, [in] + // VSS_WRITERRESTORE_ENUM writerRestore, [in] bool bRebootRequired ); + void SetRestoreMethod(VSS_RESTOREMETHOD_ENUM method, [MarshalAs(UnmanagedType.LPWStr)] string wszService, + [MarshalAs(UnmanagedType.LPWStr)] string wszUserProcedure, VSS_WRITERRESTORE_ENUM writerRestore, bool bRebootRequired); + + /// + /// Allows an express writer to indicate that a component it manages has an explicit writer-component dependency; that is, another + /// component (possibly managed by another writer) must be backed up and restored with it. + /// + /// + /// A null-terminated wide character string containing the logical path of the component (managed by the express writer) that + /// requires a dependency. + /// + /// + /// A null-terminated wide character string containing the component (managed by the express writer) that requires a dependency. + /// + /// + /// A VSS_ID (GUID) value that specifies the writer class of the express writer managing the component on which the current + /// component depends. + /// + /// + /// The logical path of the component (managed by the express writer identified by onWriterId) on which the current component depends. + /// + /// + /// The name of the component (managed by the express writer identified by onWriterId) on which the current component depends. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreateexpresswritermetadata-addcomponentdependency + // HRESULT AddComponentDependency( [in] LPCWSTR wszForLogicalPath, [in] LPCWSTR wszForComponentName, [in] VSS_ID onWriterId, [in] + // LPCWSTR wszOnLogicalPath, [in] LPCWSTR wszOnComponentName ); + void AddComponentDependency([MarshalAs(UnmanagedType.LPWStr)] string wszForLogicalPath, [MarshalAs(UnmanagedType.LPWStr)] string wszForComponentName, + Guid onWriterId, [MarshalAs(UnmanagedType.LPWStr)] string wszOnLogicalPath, [MarshalAs(UnmanagedType.LPWStr)] string wszOnComponentName); + + /// + /// Used by an express writer to indicate in its Writer Metadata Document the types of backup operations it can participate in. + /// + /// + /// A bitmask of VSS_BACKUP_SCHEMA enumeration values that specify the types of backup operations this writer supports. + /// + /// + /// + /// If no schema is explicitly set by SetBackupSchema, the express writer will be assigned the default value of + /// VSS_BS_UNDEFINED. VSS_BS_UNDEFINED means that the writer supports only simple full backup and restoration of + /// entire files (as defined by VSS_BT_FULL), there is no support for incremental or differential backups, and partial files + /// are not supported. Only the VSS_BS_UNDEFINED, VSS_BS_COPY and VSS_BS_INDEPENDENT_SYSTEM_STATE backup schema + /// types are supported by express writers. + /// + /// Requesters call IVssExamineWriterMetadata::GetBackupSchema to retrieve a writer's backup schemas as set by SetBackupSchema. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreateexpresswritermetadata-setbackupschema HRESULT + // SetBackupSchema( [in] DWORD dwSchemaMask ); + void SetBackupSchema(VSS_BACKUP_SCHEMA dwSchemaMask); + + /// Stores the Writer Metadata Document that contains an express writer's state information into a specified string. + /// A pointer to a string to be used to store the Writer Metadata Document that contains a writer's state information. + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreateexpresswritermetadata-saveasxml HRESULT + // SaveAsXML( [in] BSTR *pbstrXML ); + [return: MarshalAs(UnmanagedType.BStr)] + string SaveAsXML(); + } + + /// + /// + /// The IVssCreateWriterMetadata interface is a C++ (not COM) interface containing methods to construct the Writer Metadata + /// Document in response to an Identify event. It is used only in the CVssWriter::OnIdentify method. + /// + /// The addition and specification of components by a writer is managed through this interface. + /// + /// After it is constructed, the Writer Metadata Document is a read-only object that requesters query for information about a writer and + /// its components. + /// + /// IVssCreateWriterMetadata defines the following methods. + /// + /// + /// Method + /// Description + /// + /// + /// AddAlternateLocationMapping + /// Creates an alternate location mapping. + /// + /// + /// AddComponent + /// Adds a database or file group as a component to be backed up. + /// + /// + /// AddComponentDependency + /// + /// Indicates that a component participates in a backup or restore only if specified components managed by other writers also participate. + /// + /// + /// + /// AddDatabaseFiles + /// Indicates the physical files that are associated with a database to be backed up, as well as their location. + /// + /// + /// AddDatabaseLogFiles + /// Indicates the log files that are associated with a database to be backed up, as well as their location. + /// + /// + /// AddExcludeFiles + /// Specifies the files that will be excluded from the backup. + /// + /// + /// AddFilesToFileGroup + /// Adds the specified file or files to the specified file group. + /// + /// + /// AddIncludeFiles + /// Reserved for system use. + /// + /// + /// GetDocument + /// Reserved for system use. + /// + /// + /// SaveAsXML + /// Saves a text string containing the Writer Metadata Document. + /// + /// + /// SetBackupSchema + /// Sets the backup schema (how a backup is to be executed) to be used when processing a writer's files. + /// + /// + /// SetRestoreMethod + /// Indicates how writer data is to be restored. + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nl-vswriter-ivsscreatewritermetadata + [PInvokeData("vswriter.h", MSDNShortId = "NL:vswriter.IVssCreateWriterMetadata")] + public interface IVssCreateWriterMetadata + { + /// The AddAlternateLocationMapping method creates an alternate location mapping for a file set. + /// + /// String containing the name of the directory or directory hierarchy containing the files to be mapped. + /// 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. + /// + /// There is no requirement that the path end with a backslash (""). It is up to applications that retrieve this information to check. + /// + /// + /// + /// String containing the file specification of the files to be mapped. + /// + /// A file specification cannot contain directory specifications (for example, no backslashes) but can contain the ? and * wildcard characters. + /// + /// + /// + /// + /// A Boolean value specifying whether the path specified by the wszPath parameter identifies only a single directory or if it + /// indicates a hierarchy of directories to be traversed recursively. This parameter should be set to true if the path is + /// treated as a hierarchy of directories to be traversed recursively, or false if not. + /// + /// For information on traversing mounted folders, see Working with Mounted Folders and Reparse Points. + /// + /// + /// String containing the fully qualified path to the directory where the files will be relocated. + /// 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. + /// + /// + /// + /// 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. Writers support only local resources—sets of files whose + /// absolute path starts with a valid local volume specification and cannot be a mapped network drive. Therefore, path inputs + /// (wszPath and wszDestination) to AddAlternateLocationMapping (after the resolution of any environment variables) must be + /// in this format. + /// + /// This method can be called multiple times to add mapping for multiple files. + /// + /// The combination of path, file specification, and recursion flag (wszPath, wszFileSpec, and bRecursive, respectively) provided to + /// AddAlternateLocationMapping to be mapped must match that of one of the file sets added to one of the writer's components + /// using IVssCreateWriterMetadata::AddFilesToFileGroup, IVssCreateWriterMetadata::AddDatabaseFiles, or IVssCreateWriterMetadata::AddDatabaseLogFiles. + /// + /// + /// The AddAlternateLocationMapping method should be called only after IVssCreateWriterMetadata::SetRestoreMethod is called. + /// + /// A file should always be restored to its alternate location mapping if either of the following is true: + /// + /// + /// The restore method (set at backup time) is VSS_RME_RESTORE_TO_ALTERNATE_LOCATION. + /// + /// + /// Its restore target was set (at restore time) to VSS_RT_ALTERNATE. + /// + /// + /// In either case, if no valid alternate location mapping is defined, this constitutes a writer error. + /// A file can be restored to an alternate location mapping if either of the following is true: + /// + /// + /// The restore method is VSS_RME_RESTORE_IF_NOT_THERE and a version of the file is already present on disk. + /// + /// + /// The restore method is VSS_RME_RESTORE_IF_CAN_REPLACE and a version of the file is present on disk and cannot be replaced. + /// + /// + /// Again, if no valid alternate location mapping is defined, this constitutes a writer error. + /// + /// An alternate location mapping is used only during a restore operation and should not be confused with an alternate path, which + /// is used only during a backup operation. + /// + /// For more information on backup and restore file locations under VSS, see Non-Default Backup And Restore Locations. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreatewritermetadata-addalternatelocationmapping + // HRESULT AddAlternateLocationMapping( [in] LPCWSTR wszSourcePath, [in] LPCWSTR wszSourceFilespec, [in] bool bRecursive, [in] + // LPCWSTR wszDestination ); + void AddAlternateLocationMapping(string wszSourcePath, string wszSourceFilespec, bool bRecursive, string wszDestination); + + /// The AddComponent method adds a database or file group as a component to be backed up. + /// + /// A VSS_COMPONENT_TYPE enumeration value specifying the type of the component. + /// + /// Windows Server 2003 and Windows XP: Before Windows Server 2003 with SP1, this parameter is reserved for system use, and + /// the caller should not override the default value. + /// + /// + /// + /// + /// A pointer to a null-terminated wide character string containing the logical path of the database or file group. For more + /// information, see Logical Pathing of Components. + /// + /// A logical path is optional and can be NULL. + /// + /// + /// A pointer to a null-terminated wide character string containing the name of the component. This string is not localized. + /// This parameter is required and cannot be NULL. The string cannot contain backslashes. + /// + /// + /// + /// A pointer to a null-terminated wide character string containing a description (also called a "friendly name") for the + /// component. This string might be localized, and therefore requesters must assume that it is localized. + /// + /// This parameter is optional and can be NULL. The string can contain backslashes. + /// + /// + /// + /// A pointer to a bitmap of the icon representing the database, to be displayed in a user interface. The size, in bytes, of the + /// buffer is specified by the cbIcon parameter. + /// + /// If the writer does not want to specify an icon, pbIcon should be set to NULL. + /// + /// This parameter is reserved for future use and should always be set to false. + /// This parameter is reserved for future use and should always be set to false. + /// + /// A Boolean that indicates whether the component can be optionally backed up (which means it can be excluded from the backup) or + /// is always backed up when any of the writer's component is backed up. The Boolean is true if the component can be + /// selectively backed up and false if it is backed up when any of the components is backed up. + /// + /// + /// + /// A Boolean that determines whether a component can be individually restored when it has not been explicitly included in the + /// backup document. If the component was explicitly added to the backup document, it can always be individually selected for + /// restore; in this case, this flag has no meaning. + /// + /// + /// When true, the component can be restored by itself; when false, the component can be restored only if the entire + /// component set is being restored. (See VSS_COMPONENTINFO and Working with Selectability and Logical Paths for more information). + /// + /// The default value for this parameter is false. + /// + /// + /// + /// A bit mask (or bitwise OR) of members of the VSS_COMPONENT_FLAGS enumeration indicating the features that this component supports. + /// + /// The default value for this argument is zero. + /// + /// + /// This method can be called multiple times to add several components to a writer's metadata. + /// + /// The combination of logical path and name for each component of a given instance of a given class of writer must be unique. + /// Attempting to call AddComponent twice with the same values of wszLogicalPath and wszComponentName results in a + /// VSS_E_OBJECT_ALREADY_EXISTS error. + /// + /// + /// AddComponent can be used to add subcomponents—components in which all member files are backed up as a group, but which + /// contain files that can be restored individually. See Working with Selectability for Restore and Subcomponents for more information. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreatewritermetadata-addcomponent HRESULT + // AddComponent( [in] VSS_COMPONENT_TYPE ct, [in] LPCWSTR wszLogicalPath, [in] LPCWSTR wszComponentName, [in] LPCWSTR wszCaption, + // [in] const BYTE *pbIcon, [in] UINT cbIcon, [in] bool bRestoreMetadata, [in] bool bNotifyOnBackupComplete, [in] bool bSelectable, + // [in] bool bSelectableForRestore, [in] DWORD dwComponentFlags ); + void AddComponent(VSS_COMPONENT_TYPE ct, [Optional] string wszLogicalPath, string wszComponentName, [Optional] string wszCaption, byte[] pbIcon, + bool bRestoreMetadata, bool bNotifyOnBackupComplete, bool bSelectable, bool bSelectableForRestore = false, + VSS_COMPONENT_FLAGS dwComponentFlags = 0); + + /// + /// The AddComponentDependency method allows a writer to indicate that a component it manages has an explicit + /// writer-component dependency; that is, another component in another writer must be backed up and restored with it. + /// + /// + /// A null-terminated wide character string containing the logical path of the component (managed by the current writer) that + /// requires a dependency. + /// + /// + /// A null-terminated wide character string containing the component (managed by the current writer) that requires a dependency. + /// + /// + /// The class ID or VSS_ID (GUID) of the writer managing the component on which the current component depends. + /// + /// + /// The logical path of the component (managed by the writer identified by onWriterId) on which the current component depends. + /// + /// + /// The name of the component (managed by the writer identified by onWriterId) on which the current component depends. + /// + /// + /// Dependencies upon components managed by the current writer are not permitted. + /// + /// A dependency requires that both the target of the dependency and the component that depends on the target be restored and backed + /// up together. It does not indicate a priority between the components, although a requester may choose to implement that. + /// + /// + /// Because the combination of logical name and component name must be unique across all instances of a writer class, the fact that + /// several writers may have the same class ID is not a problem. + /// + /// + /// This method can be used to declare remote dependencies. A writer can declare a remote dependency by prepending + /// "\\RemoteComputerName", where RemoteComputerName is the name of the computer where the remote component resides, to the logical + /// path in the wszOnLogicalPath parameter. The value of RemoteComputerName can be an IP address or a computer name returned by the + /// GetComputerNameEx function. + /// + /// + /// If the remote component resides on a cluster, the writer must report the virtual name for the cluster, and it is the requester's + /// responsibility to map the virtual name to the physical name of a cluster node before a volume shadow copy can be created. + /// + /// + /// To determine whether a dependency is local or remote, the requester must examine the component name returned in the + /// pbstrComponentName parameter. If the component name begins with "\", the requester must assume that it specifies a remote + /// dependency and that the first component following "\" is the RemoteComputerName that was specified by the writer. If the + /// component name does not begin with "\", the requester should assume that it specifies a local dependency. + /// + /// + /// Windows Server 2003: This method cannot be used to declare remote dependencies until Windows Server 2003 with Service + /// Pack 1 (SP1). + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreatewritermetadata-addcomponentdependency HRESULT + // AddComponentDependency( [in] LPCWSTR wszForLogicalPath, [in] LPCWSTR wszForComponentName, [in] VSS_ID onWriterId, [in] LPCWSTR + // wszOnLogicalPath, [in] LPCWSTR wszOnComponentName ); + void AddComponentDependency(string wszForLogicalPath, string wszForComponentName, Guid onWriterId, string wszOnLogicalPath, + string wszOnComponentName); + + /// + /// The AddDatabaseFiles method indicates the file set (the specified file or files) that make up the database component to + /// be backed up. + /// + /// + /// + /// Pointer to a null-terminated wide character string containing the logical path of the component to which the database + /// will be added. + /// + /// For more information, see Logical Pathing of Components. + /// A logical path is not required and can be NULL. + /// + /// + /// Pointer to a null-terminated wide character string containing the name of the database. + /// This name is required and must match the name of the component to which the database is being added. + /// + /// + /// + /// Pointer to a null-terminated wide character string containing the path of the directory containing the database file. + /// + /// 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. + /// + /// + /// + /// + /// Pointer to a null-terminated wide character string containing the file specification of the file or files associated with + /// the database. + /// + /// + /// A file specification cannot contain directory specifications (for example, no backslashes) but can contain the ? and * wildcard characters. + /// + /// + /// + /// + /// A bit mask (or bitwise OR) of VSS_FILE_SPEC_BACKUP_TYPE enumeration values to indicate whether a writer should evaluate the file + /// for participation in certain types of backup operations. + /// + /// The default value for this argument is (VSS_FSBT_ALL_BACKUP_REQUIRED | VSS_FSBT_ALL_SNAPSHOT_REQUIRED). + /// + /// + /// + /// 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. Writers support only local resources—sets of files whose + /// absolute path starts with a valid local volume specification and cannot be a mapped network drive. Therefore, path inputs + /// (wszPath) to AddDatabaseFiles (after the resolution of any environment variables) must be in this format. + /// + /// + /// This method can be called multiple times for a particular database. This is done when the database exists on files stored on + /// separate volumes, as is possible with Microsoft SQL Server. + /// + /// + /// The values of the wszLogicalPath and wszDatabaseName parameters should match those of one of the database components previously + /// added with the IVssCreateWriterMetadata::AddComponent method. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreatewritermetadata-adddatabasefiles HRESULT + // AddDatabaseFiles( [in] LPCWSTR wszLogicalPath, [in] LPCWSTR wszDatabaseName, [in] LPCWSTR wszPath, [in] LPCWSTR wszFilespec, [in] + // DWORD dwBackupTypeMask ); + void AddDatabaseFiles([Optional] string wszLogicalPath, string wszDatabaseName, string wszPath, string wszFilespec, + VSS_FILE_SPEC_BACKUP_TYPE dwBackupTypeMask = VSS_FILE_SPEC_BACKUP_TYPE.VSS_FSBT_ALL_BACKUP_REQUIRED | VSS_FILE_SPEC_BACKUP_TYPE.VSS_FSBT_ALL_SNAPSHOT_REQUIRED); + + /// + /// The AddDatabaseLogFiles method indicates the log files that are associated with a database to be backed up, as well as + /// their location. + /// + /// + /// + /// Pointer to a null-terminated wide character string containing the logical path of the database component to which the log + /// files will be added. + /// + /// For more information, see Logical Pathing of Components. + /// A logical path is not required, and can be NULL. + /// + /// + /// Pointer to a null-terminated wide character string containing the name of the database component associated with the log + /// files. The type of this component must be VSS_CT_DATABASE; otherwise, the method will return an error. + /// + /// + /// Pointer to a null-terminated wide character string containing the path of the directory containing the log files. + /// 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. + /// The path can contain environment variables (for example, %SystemRoot%) but cannot contain wildcard characters. + /// + /// There is no requirement that the path end with a backslash (""). It is up to applications that retrieve this information to check. + /// + /// + /// + /// + /// Pointer to a null-terminated wide character string containing the file specification of the log file(s) associated with + /// the database. + /// + /// + /// A file specification cannot contain directory specifications (for example, no backslashes) but can contain the ? and * wildcard characters. + /// + /// + /// + /// + /// A bit mask (or bitwise OR) of VSS_FILE_SPEC_BACKUP_TYPE enumeration values to indicate if a writer should evaluate the file for + /// participation in a certain type of backup operations. + /// + /// The default value for this argument is (VSS_FSBT_ALL_BACKUP_REQUIRED | VSS_FSBT_ALL_SNAPSHOT_REQUIRED). + /// + /// + /// + /// 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. Writers support only local resources—sets of files whose + /// absolute path starts with a valid local volume specification and cannot be a mapped network drive. Therefore, path inputs + /// (wszPath) to AddDatabaseLogFiles (after the resolution of any environment variables) must be in this format. + /// + /// + /// This method can be called multiple times for a particular database component, which might be needed when several log files are + /// stored on separate volumes. + /// + /// + /// The values of the wszLogicalPath and wszDatabaseName parameters should match those of one of the database components previously + /// added with the IVssCreateWriterMetadata::AddComponent method. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreatewritermetadata-adddatabaselogfiles HRESULT + // AddDatabaseLogFiles( [in] LPCWSTR wszLogicalPath, [in] LPCWSTR wszDatabaseName, [in] LPCWSTR wszPath, [in] LPCWSTR wszFilespec, + // [in] DWORD dwBackupTypeMask ); + void AddDatabaseLogFiles([Optional] string wszLogicalPath, string wszDatabaseName, string wszPath, string wszFilespec, + VSS_FILE_SPEC_BACKUP_TYPE dwBackupTypeMask = VSS_FILE_SPEC_BACKUP_TYPE.VSS_FSBT_ALL_BACKUP_REQUIRED | VSS_FILE_SPEC_BACKUP_TYPE.VSS_FSBT_ALL_SNAPSHOT_REQUIRED); + + /// + /// The AddExcludeFiles method is used to explicitly exclude a file set (a specified file or files) that might otherwise be + /// implicitly included when a component of the current writer is backed up. + /// + /// + /// Pointer to a null-terminated wide character string containing the root directory under which files are to be excluded. + /// 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. + /// The path can contain environment variables (for example, %SystemRoot%) but cannot contain wildcard characters. + /// + /// There is no requirement that the path end with a backslash (""). It is up to applications that retrieve this information to check. + /// + /// + /// + /// Pointer to a null-terminated wide character string containing the file specification of the files to be excluded. + /// + /// A file specification cannot contain directory specifications (for example, no backslashes) but can contain the ? and * wildcard characters. + /// + /// + /// + /// + /// A Boolean value specifying whether the path specified by the wszPath parameter identifies only a single directory or if it + /// indicates a hierarchy of directories to be traversed recursively. This parameter should be set to true if the path is + /// treated as a hierarchy of directories to be recursed through, or false otherwise. + /// + /// For information on traversing over mounted folders, see Working with Mounted Folders and Reparse Points. + /// + /// + /// + /// 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. Writers support only local resources—sets of files whose + /// absolute path starts with a valid local volume specification and cannot be a mapped network drive. Therefore, path inputs + /// (wszPath) to AddExcludeFiles (after the resolution of any environment variables) must be in this format. + /// + /// + /// For example, it is often convenient to define a component to include all files in a given directory and then use + /// AddExcludeFiles to explicitly remove some files (for instance, temporary files) from a backup. + /// + /// For more information on excluding files, see Exclude File List Specification. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreatewritermetadata-addexcludefiles HRESULT + // AddExcludeFiles( [in] LPCWSTR wszPath, [in] LPCWSTR wszFilespec, [in] bool bRecursive ); + void AddExcludeFiles(string wszPath, string wszFilespec, bool bRecursive); + + /// The AddFilesToFileGroup method adds a file set (a specified file or files) to a specified file group component. + /// + /// Pointer to a null-terminated wide character string containing the logical path (which may be NULL) of the + /// component to which to add the files. For more information, see Logical Pathing of Components. + /// + /// + /// Pointer to a null-terminated wide character string containing the name of the file group component. The type of this + /// component must be VSS_CT_FILEGROUP; otherwise, the method will return an error. + /// + /// + /// Pointer to a null-terminated wide character string containing the default root directory of the files to be added. + /// 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. + /// The path can contain environment variables (for example, %SystemRoot%) but cannot contain wildcard characters. + /// + /// There is no requirement that the path end with a backslash (""). It is up to applications that retrieve this information to check. + /// + /// + /// + /// Pointer to a null-terminated wide character string containing the file specification of the files to be included. + /// + /// A file specification cannot contain directory specifications (for example, no backslashes) but can contain the ? and * wildcard characters. + /// + /// + /// + /// + /// A Boolean value specifying whether the path specified by the wszPath parameter identifies only a single directory or if it + /// indicates a hierarchy of directories to be traversed recursively. This parameter should be set to true if the path is + /// treated as a hierarchy of directories to be recursed through, or false otherwise. + /// + /// For information on traversing over mounted folders, see Working with Mounted Folders and Reparse Points. + /// + /// + /// + /// Pointer to a null-terminated wide character string containing the alternate path, which actually contains the files to be + /// backed up with this component. + /// + /// 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. + /// Specifying an alternate path is optional; if no alternate path is needed, wszAlternatePath should be NULL. + /// An alternate path should not be confused with an alternate location mapping. + /// + /// + /// + /// A bitmask of VSS_FILE_SPEC_BACKUP_TYPE enumeration values to indicate if a writer should evaluate the file for participation in + /// a certain type of backup operations. + /// + /// The default value for this argument is (VSS_FSBT_ALL_BACKUP_REQUIRED | VSS_FSBT_ALL_SNAPSHOT_REQUIRED). + /// + /// + /// + /// 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. Writers support only local resources—sets of files whose + /// absolute path starts with a valid local volume specification and cannot be a mapped network drive. Therefore, path inputs + /// (wszPath and wszAlternatePath) to AddFilesToFileGroup (after the resolution of any environment variables) must be in this format. + /// + /// + /// A writer can call this method multiple times to add several sets of files to its file group component. However, you should make + /// sure that the file specifications do not overlap, because a particular file can be specified only once. + /// + /// + /// The locations from which files are backed up and to which they are restored depends on the values for the root directory defined + /// by wszPath and the alternate path defined by wszAlternatePath. + /// + /// Note the following when using path information provided by AddFilesToFileGroup: + /// + /// + /// + /// Restore operations should (if possible) restore files added to a component by AddFilesToFileGroup under the default root + /// directory defined by wszPath. + /// + /// + /// + /// + /// If an alternate path is not specified (if wszAlternatePath is NULL), the files added to the component will be backed up + /// from the default root directory and restored to the default root directory indicated by wszPath. + /// + /// + /// + /// + /// If an alternate path is specified (if wszAlternatePath is non- NULL), files added to the component are backed up from the + /// alternate path specified by wszAlternatePath. However, requesters will still use wszPath as the default restoration location. + /// + /// + /// + /// + /// If the alternate path is defined (wszAlternatePath is non- NULL) and there are files matching the file specification + /// (wszFilespec) in both the alternate path and the default root directory (wszPath), then a backup operation should back up files + /// located under the alternate path, not files located under the default root directory. + /// + /// + /// + /// + /// Files should be restored to the directory indicated by wszPath unless an alternate location mapping was set by + /// IVssCreateWriterMetadata::AddAlternateLocationMapping and the restore method or restore target requires it. + /// + /// + /// + /// For more information on backup and restore file locations under VSS, see Non-Default Backup And Restore Locations. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreatewritermetadata-addfilestofilegroup HRESULT + // AddFilesToFileGroup( [in] LPCWSTR wszLogicalPath, [in] LPCWSTR wszGroupName, [in] LPCWSTR wszPath, [in] LPCWSTR wszFilespec, [in] + // bool bRecursive, [in] LPCWSTR wszAlternateLocation, [in] DWORD dwBackupTypeMask ); + void AddFilesToFileGroup([Optional] string wszLogicalPath, string wszGroupName, string wszPath, string wszFilespec, bool bRecursive, + [Optional] string wszAlternateLocation, + VSS_FILE_SPEC_BACKUP_TYPE dwBackupTypeMask = VSS_FILE_SPEC_BACKUP_TYPE.VSS_FSBT_ALL_BACKUP_REQUIRED | VSS_FILE_SPEC_BACKUP_TYPE.VSS_FSBT_ALL_SNAPSHOT_REQUIRED); + + /// + /// The SaveAsXML method saves the Writer Metadata Document that contains a writer's state information to a specified string. + /// + /// Pointer to a string to be used to store the Writer Metadata Document that contains a writer's state information. + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreatewritermetadata-saveasxml HRESULT SaveAsXML( + // [in] BSTR *pbstrXML ); + string SaveAsXML(); + + /// + /// The SetBackupSchema method is used by a writer to indicate in its Writer Metadata Document the types of backup operations + /// it can participate in. + /// + /// + /// The types of backup operations this writer supports expressed as a bitmask of VSS_BACKUP_SCHEMA enumeration values. + /// + /// For express writers, only the VSS_BS_UNDEFINED, VSS_BS_COPY, and VSS_BS_INDEPENDENT_SYSTEM_STATE values are supported. + /// + /// + /// + /// + /// If no schema is explicitly set by SetBackupSchema, the writer will be assigned the default value of VSS_BS_UNDEFINED: the + /// writer supports only simple full backup and restoration of entire files (as defined by VSS_BT_FULL), there is no support for + /// incremental or differential backups, and partial files are not supported. + /// + /// Requesters call IVssExamineWriterMetadata::GetBackupSchema to retrieve a writer's backup schemas as set by SetBackupSchema. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreatewritermetadata-setbackupschema HRESULT + // SetBackupSchema( [in] DWORD dwSchemaMask ); + void SetBackupSchema(VSS_BACKUP_SCHEMA dwSchemaMask); + + /// The SetRestoreMethod method indicates how the writer's data is to be restored. + /// VSS_RESTOREMETHOD_ENUM value specifying the method that will be used in the restore operation. + /// + /// + /// A pointer to a wide character string containing the name of a service that must be stopped prior to a restore operation and then + /// started after the restore operation takes place, if the value of method is VSS_RME_STOP_RESTORE_START or VSS_RME_RESTORE_STOP_START. + /// + /// + /// If the value of method is not VSS_RME_STOP_RESTORE_START or VSS_RME_RESTORE_STOP_START, this argument is not used and should be + /// set to NULL. + /// + /// + /// Reserved for future use. The value of this parameter should always be set to NULL. + /// + /// VSS_WRITERRESTORE_ENUM value specifying whether the writer will be involved in restoring its data. + /// Express writers must set this parameter to VSS_WRE_NEVER. + /// + /// Boolean indicating whether a reboot will be required after the restore operation is complete. + /// + /// + /// There is a single restore method defined for a writer. If the restore method is not overridden, all of the writer's components + /// will be restored using the same method. + /// + /// + /// Writers override the restore method on a component-by-component basis by setting a restore target, typically while handling a + /// PreRestore event (CVssWriter::OnPreRestore). + /// + /// + /// It is important to note that despite the fact that restore methods are applied writer-wide, methods are implemented on a + /// per-component basis. For example, if the method specified by the method parameter is VSS_RME_RESTORE_IF_CAN_REPLACE, then all of + /// the files in the component are restored to their original location if they can all be replaced without an error occurring. + /// Otherwise, they are restored to their alternate location if one is specified. + /// + /// A file should always be restored to its alternate location mapping if either of the following is true: + /// + /// + /// The restore method (set at backup time) is VSS_RME_RESTORE_TO_ALTERNATE_LOCATION. + /// + /// + /// Its restore target was set (at restore time) to VSS_RT_ALTERNATE. + /// + /// + /// In either case, if no valid alternate location mapping is defined, this constitutes a writer error. + /// A file can be restored to an alternate location mapping if either of the following is true: + /// + /// + /// The restore method is VSS_RME_RESTORE_IF_NOT_THERE and a version of the file is already present on disk. + /// + /// + /// The restore method is VSS_RME_RESTORE_IF_CAN_REPLACE and a version of the file is present on disk and cannot be replaced. + /// + /// + /// Again, if no valid alternate location mapping is defined, this constitutes a writer error. + /// + /// An alternate location mapping is used only during a restore operation and should not be confused with an alternate path, which + /// is used only during a backup operation. + /// + /// For more information about restore methods, see Setting VSS Restore Methods. + /// + /// If the restore method is VSS_RME_STOP_RESTORE_START or VSS_RME_RESTORE_STOP_START, then the correct name of the service must be + /// provided as the wszService argument. For information on writer participation in stopping and restarting services during a + /// restore operation, see Stopping Services for Restore by Requesters. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreatewritermetadata-setrestoremethod HRESULT + // SetRestoreMethod( [in] VSS_RESTOREMETHOD_ENUM method, [in] LPCWSTR wszService, [in] LPCWSTR wszUserProcedure, [in] + // VSS_WRITERRESTORE_ENUM writerRestore, [in] bool bRebootRequired ); + void SetRestoreMethod(VSS_RESTOREMETHOD_ENUM method, [Optional] string wszService, [Optional] string wszUserProcedure, + VSS_WRITERRESTORE_ENUM writerRestore, bool bRebootRequired); + } + + /// + /// + /// The IVssCreateWriterMetadataEx interface is a C++ (not COM) interface that defines a method to report any file sets that will + /// be explicitly excluded when a shadow copy is created. This interface is used only in the CVssWriterEx::OnIdentifyEx method. + /// + /// The IVssCreateWriterMetadataEx interface inherits from the IVssCreateWriterMetadata interface and IUnknown. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nl-vswriter-ivsscreatewritermetadataex + [PInvokeData("vswriter.h", MSDNShortId = "NL:vswriter.IVssCreateWriterMetadataEx")] + public interface IVssCreateWriterMetadataEx : IVssCreateWriterMetadata + { + /// + /// Reports any file sets that will be explicitly excluded by the writer when a shadow copy is created. + /// + /// Calling this method does not cause the files to be excluded. The writer is responsible for deleting the files from the shadow + /// copy in its CVssWriter::OnPostSnapshot method. + /// + /// + /// + /// A pointer to a null-terminated wide character string containing the root directory under which files are to be excluded. + /// 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. + /// The path can contain environment variables (for example, %SystemRoot%) but cannot contain wildcard characters. + /// + /// There is no requirement that the path end with a backslash (""). It is up to applications that retrieve this information to + /// check whether the path ends with a backslash. + /// + /// + /// + /// A pointer to a null-terminated wide character string containing the file specification of the files to be excluded. + /// + /// A file specification cannot contain directory specifications (for example, no backslashes) but can contain the ? and * wildcard characters. + /// + /// + /// + /// + /// A Boolean value specifying whether the path specified by the wszPath parameter identifies only a single directory or if it + /// indicates a hierarchy of directories to be traversed recursively. This parameter should be set to true if the path is + /// treated as a hierarchy of directories to be recursed through, or false otherwise. + /// + /// For information on traversing over mounted folders, see Working with Mounted Folders and Reparse Points. + /// + /// + /// + /// 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 use of the AddExcludeFilesFromSnapshot method is optional. Writers should use this method only for large files that + /// change significantly between shadow copy operations. + /// + /// + /// This method is not a substitute for the IVssCreateWriterMetadata::AddExcludeFiles method. Writers should continue to use the + /// AddExcludeFiles method to report which file sets are excluded from backup. + /// + /// + /// The caller is responsible for calling the IUnknown::Release method to release the resources of the returned IVssWMFiledesc object. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsscreatewritermetadataex-addexcludefilesfromsnapshot + // HRESULT AddExcludeFilesFromSnapshot( [in] LPCWSTR wszPath, [in] LPCWSTR wszFilespec, [in] bool bRecursive ); + void AddExcludeFilesFromSnapshot(string wszPath, string wszFilespec, bool bRecursive); + } + + /// Defines methods to manage metadata for a VSS express writer. + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nl-vswriter-ivssexpresswriter + [PInvokeData("vswriter.h", MSDNShortId = "NL:vswriter.IVssExpressWriter")] + public interface IVssExpressWriter + { + /// Creates an express writer metadata object and returns an IVssCreateExpressWriterMetadata interface pointer to it. + /// The globally unique identifier (GUID) of the writer class. + /// + /// A null-terminated wide character string that contains the name of the writer class. This string is not localized. + /// + /// + /// A VSS_USAGE_TYPE enumeration value that indicates how the data that is managed by the writer is used on the host system. The + /// only valid values for this parameter are VSS_UT_BOOTABLESYSTEMSTATE, VSS_UT_SYSTEMSERVICE, and VSS_UT_USERDATA. + /// + /// The major version of the writer application. For more information, see the Remarks section. + /// The minor version of the writer application. For more information, see the Remarks section. + /// + /// A pointer to a variable that receives an IVssCreateExpressWriterMetadata interface pointer to the newly created express writer metadata. /// - // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-createvssexpresswriter HRESULT CreateVssExpressWriter( - // [out] IVssExpressWriter **ppWriter ); - [DllImport(Lib_VssApi, SetLastError = false, CharSet = CharSet.Unicode, EntryPoint = "CreateVssExpressWriterInternal")] - [PInvokeData("vswriter.h", MSDNShortId = "NF:vswriter.CreateVssExpressWriter")] - public static extern HRESULT CreateVssExpressWriter(out /*IVssExpressWriter*/ IntPtr ppWriter); + /// + /// + /// The versionMajor and versionMajor parameters are used to specify the writer's major and minor version numbers according to the + /// following VSS conventions: + /// + /// + /// + /// + /// A writer's minor version number should be incremented by one whenever a released version of the writer contains minor changes + /// that affect the writer's interaction with requesters. For example, a correction to a file specification in a writer QFE or + /// service pack would justify incrementing the minor version number. However, a change between beta or release candidate versions + /// of a writer would not justify the changing of the minor version number. + /// + /// + /// + /// + /// A writer's major version number should be incremented by one whenever a released version of the writer contains a significant + /// change. For example, if data that is backed up with a new version of a writer cannot be restored using the previous version of + /// the writer, the new writer's major version number should be incremented. + /// + /// + /// + /// Whenever the major version number is incremented, the minor version number should be reset to zero. + /// + /// + /// If a writer does not specify a version number, VSS will assign a default version number of 0.0. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivssexpresswriter-createmetadata HRESULT CreateMetadata( + // [in] VSS_ID writerId, [in] LPCWSTR writerName, [in] VSS_USAGE_TYPE usageType, [in] DWORD versionMajor, [in] DWORD versionMinor, + // [in] DWORD reserved, [out] IVssCreateExpressWriterMetadata **ppMetadata ); + IVssCreateExpressWriterMetadata CreateMetadata(Guid writerId, string writerName, VSS_USAGE_TYPE usageType, uint versionMajor, uint versionMinor); + + /// Causes VSS to load the writer's metadata from a string instead of the express writer metadata store. + /// A null-terminated wide character string that contains the writer's metadata. + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivssexpresswriter-loadmetadata HRESULT LoadMetadata( [in] + // LPCWSTR metadata, [in] DWORD reserved ); + void LoadMetadata(string metadata); + + /// Causes VSS to store the writer's metadata in the express writer metadata store. + /// + /// Before using this method, the caller must have either used the LoadMetadata method to load the writer's metadata directly or + /// used the CreateMetadata method to create a writer metadata object. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivssexpresswriter-register HRESULT Register(); + void Register(); + + /// Causes VSS to delete the writer's metadata from the express writer metadata store. + /// The globally unique identifier (GUID) of the writer class. + /// Before using this method, the caller must have used the CreateMetadata method to create a writer metadata object. + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivssexpresswriter-unregister HRESULT Unregister( [in] + // VSS_ID writerId ); + void Unregister(Guid writerId); + } + + /// + /// + /// The IVssWMDependency is a C++ (not COM) interface returned by the IVssWMComponent interface and used by applications when + /// backing up or restoring a component that has an explicit writer-component dependency on a component managed by another writer. + /// (Dependencies must be between writers, not within writers.) + /// + /// + /// IVssWMDependency is used to determine the writer ID, logical path, and component name of components that must be restored or + /// backed up along with the target component. + /// + /// + /// Dependencies are created by writers while handling Identify events (CVssWriter::OnIdentify) using the + /// IVssCreateWriterMetadata::AddComponentDependency method. + /// + /// + /// Calling applications are responsible for calling IUnknown::Release to release resources held by a returned IVssWMDependency + /// object when it is no longer needed. + /// + /// The IVssWMComponent::GetDependency method returns an IVssWMDependency interface. + /// + /// Note that a dependency does not indicate an order of preference between the component with the documented dependencies and the + /// components it depends on. A dependency merely indicates that the component and the components it depends on must always be backed up + /// or restored together. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nl-vswriter-ivsswmdependency + [PInvokeData("vswriter.h", MSDNShortId = "NL:vswriter.IVssWMDependency")] + public interface IVssWMDependency + { + /// + /// The GetComponentName method retrieves the name of a component that the current component depends on in an explicit + /// writer-component dependency. + /// + /// + /// The address of a caller-allocated variable that receives a NULL-terminated wide character string containing the name of + /// the component that the current component depends on. + /// + /// + /// The caller must free the memory used by the returned string by calling SysFreeString. + /// + /// A dependency does not indicate an order of preference between the component with the documented dependencies and the components + /// it depends on. A dependency merely indicates that the component and the components it depends on must always be backed up or + /// restored together. + /// + /// + /// It is possible to have multiple instances of a given writer class; however, any component's logical path and name should be unique. + /// + /// + /// If there are multiple instances of a writer class, it will be necessary to use logical path and component name information to + /// identify the instance managing the component that the current component depends on. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsswmdependency-getcomponentname HRESULT + // GetComponentName( BSTR *pbstrComponentName ); + string ComponentName { get; } + + /// + /// The GetLogicalPath method retrieves the logical path of a component that the current component depends on in explicit + /// writer-component dependency. + /// + /// + /// The address of a caller-allocated variable that receives a NULL-terminated wide character string containing the logical + /// path of the component that the current component depends on. + /// + /// + /// The caller must free the memory used by the returned string by calling SysFreeString. + /// + /// A dependency does not indicate an order of preference between the component with the documented dependencies and the components + /// it depends on. A dependency merely indicates that the component and the components it depends on must always be backed up or + /// restored together. + /// + /// + /// It is possible to have multiple instances of a given writer class; however, any component's logical path and name should be unique. + /// + /// + /// If there are multiple instances of a writer class, it will be necessary to use logical path and component name information to + /// identify the instance managing the component that the current component depends on. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsswmdependency-getlogicalpath HRESULT GetLogicalPath( + // [out] BSTR *pbstrLogicalPath ); + string LogicalPath { get; } + + /// + /// The GetWriterId method retrieves the class ID of a writer containing a component that the current component depends on in + /// an explicit writer-component dependency. + /// + /// The class ID of a writer that manages a component on which the current component depends. + /// + /// + /// A dependency does not indicate an order of preference between the component with the documented dependencies and the components + /// it depends on. A dependency merely indicates that the component and the components it depends on must always be backed up or + /// restored together. + /// + /// + /// It is possible to have multiple instances of a given writer class; however, any component's logical path and name should be unique. + /// + /// + /// If there are multiple instances of a writer class, it will be necessary to use logical path and component name information to + /// identify the instance managing the component that the current component depends on. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsswmdependency-getwriterid HRESULT GetWriterId( VSS_ID + // *pWriterId ); + Guid WriterId { get; } + } + + /// + /// + /// The IVssWMFiledesc interface is a C++ (not COM) interface returned to a calling application by a number of query methods. It + /// provides detailed information about a file or set of files (a file set). + /// + /// + /// The calling application is responsible for calling IUnknown::Release to release the resources held by the returned + /// IVssWMFiledesc interface when it is no longer needed. + /// + /// The following methods return an IVssWMFiledesc interface: + /// + /// + /// IVssComponent::GetAlternateLocationMapping + /// + /// + /// IVssComponent::GetNewTarget + /// + /// + /// IVssExamineWriterMetadata::GetExcludeFile + /// + /// + /// IVssExamineWriterMetadata::GetAlternateLocationMapping + /// + /// + /// IVssWMComponent::GetFile + /// + /// + /// IVssWMComponent::GetDatabaseFile + /// + /// + /// IVssWMComponent::GetDatabaseLogFile + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nl-vswriter-ivsswmfiledesc + [PInvokeData("vswriter.h", MSDNShortId = "NL:vswriter.IVssWMFiledesc")] + public interface IVssWMFiledesc + { + /// The GetAlternateLocation method obtains an alternate location for a file set. + /// + /// The address of a caller-allocated variable that receives a string specifying the alternate backup location. The path of this + /// location can be a local path or the UNC path of a remote file share. If there is no alternate location, the pointer is NULL. + /// + /// + /// + /// 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 caller must call SysFreeString to free the memory held by the pbstrAlternateLocation parameter. + /// + /// The interpretation of the alternate location returned by GetAlternateLocation differs depending on the method used to + /// retrieve the IVssWMFiledesc object. + /// + /// + /// + /// IVssExamineWriterMetadata::GetExcludeFile + /// + /// + /// IVssWMComponent::GetDatabaseFile + /// + /// + /// IVssWMComponent::GetDatabaseLogFile + /// + /// + /// IVssWMComponent::GetFile + /// + /// + /// + /// The value returned by GetAlternateLocation refers to an alternate location mapping when returned by the + /// IVssExamineWriterMetadata::GetAlternateLocationMapping method. + /// + /// + /// During backup operations, this is the alternate location from which to back up a file. During a restore, it is the alternate + /// location to which to restore a file. + /// + /// For more information, see Non-Default Backup And Restore Locations. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsswmfiledesc-getalternatelocation HRESULT + // GetAlternateLocation( [out] BSTR *pbstrAlternateLocation ); + string AlternateLocation { get; } + + /// + /// The GetBackupTypeMask method returns the file backup specification for the files specified by the current file descriptor + /// as a bit mask (or bitwise OR) of VSS_FILE_SPEC_BACKUP_TYPE values. This information indicates if the files are to be evaluated + /// by their writer for participation in various specific types of backup operations (or if they will participate in an incremental + /// or differential backups). + /// + /// + /// Pointer to a DWORD containing a bit mask (or bitwise OR) of VSS_FILE_SPEC_BACKUP_TYPE values indicating the file backup + /// specification for the file or file set described by the current IVssWMFiledesc interface. + /// + /// + /// A file backup specification is specified by a writer when it adds a file specification to a component using the + /// IVssCreateWriterMetadata::AddFilesToFileGroup, IVssCreateWriterMetadata::AddDatabaseFiles, or + /// IVssCreateWriterMetadata::AddDatabaseLogFiles method. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsswmfiledesc-getbackuptypemask HRESULT + // GetBackupTypeMask( DWORD *pdwTypeMask ); + VSS_FILE_SPEC_BACKUP_TYPE BackupTypeMask { get; } + + /// + /// + /// The GetFilespec method returns the file specification used to obtain the list of files that the current IVssWMFiledesc + /// object is a member of. + /// + /// A querying method used a path and this file specification to return the current IVssWMFiledesc object. + /// + /// + /// The address of a caller-allocated variable that receives a string specifying the returned file specification. + /// + /// A file specification cannot contain directory specifications (for example, no backslashes) but can contain the ? and * wildcard characters. + /// + /// + /// The caller must call SysFreeString to free the memory held by the pbstrFilespec parameter. + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsswmfiledesc-getfilespec HRESULT GetFilespec( [out] + // BSTR *pbstrFilespec ); + string FileSpec { get; } + + /// + /// + /// The GetPath method obtains the fully qualified directory path or the UNC path of the remote file share to obtain the list + /// of files described in the current IVssWMFiledesc object. + /// + /// A querying method used this path and a file specification to return the current IVssWMFiledesc object. + /// + /// + /// + /// The address of a caller-allocated variable that receives a NULL-terminated wide character string specifying the fully + /// qualified directory path or the UNC path of the remote file share directory. + /// + /// The path can be a long or short file name and can use the prefix "\?". For more information, see Naming a File. + /// Users of this method need to check to determine whether this path ends with a backslash (""). + /// + /// + /// + /// 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 caller must call SysFreeString to free the memory held by the pbstrPath parameter. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsswmfiledesc-getpath HRESULT GetPath( [out] BSTR + // *pbstrPath ); + string Path { get; } + + /// + /// The GetRecursive method indicates whether the list of files described in a IVssWMFiledesc object with a root directory + /// returned by IVssWMFiledesc::GetPath contains only files in that directory or whether the file list contains files from the + /// directory hierarchy as well. + /// + /// + /// + /// A pointer to a Boolean value specifying whether the value returned by IVssWMFiledesc::GetPath identifies only a single directory + /// or if it indicates a hierarchy of directories to be traversed recursively. The Boolean value receives true if the path is + /// treated as a hierarchy of directories to be traversed recursively, or false if not. + /// + /// For information on traversing over mounted folders, see Working with Mounted Folders and Reparse Points. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsswmfiledesc-getrecursive HRESULT GetRecursive( [out] + // bool *pbRecursive ); + bool Recursive { get; } + } + + /// + /// + /// The IVssWriterComponents interface is a C++ (not COM) interface that contains methods used to obtain and modify component + /// information (in the form of IVssComponent objects) associated with a given writer but stored in a requester's Backup Components Document. + /// + /// + /// The CVssWriter base class is responsible for passing an instance of the IVssWriterComponents interface to the following event handlers: + /// + /// + /// + /// CVssWriter::OnPrepareBackup + /// + /// + /// CVssWriter::OnBackupComplete + /// + /// + /// CVssWriter::OnPreRestore + /// + /// + /// CVssWriter::OnPostRestore + /// + /// + /// CVssWriter::OnPostSnapshot + /// + /// + /// + /// In addition, an instance of the IVssWriterComponentsExt interface, which implements a requester-side version of the + /// IVssWriterComponents interface, is returned by IVssBackupComponents::GetWriterComponents. + /// + /// IVssWriterComponents defines the following methods. + /// + /// + /// Method + /// Description + /// + /// + /// GetComponent + /// Returns the components belonging to a given writer instance. + /// + /// + /// GetComponentCount + /// Returns the number of components belonging to a given writer instance. + /// + /// + /// GetWriterInfo + /// Returns the instance and class identifier of the writer responsible for the components. + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nl-vswriter-ivsswritercomponents + [PInvokeData("vswriter.h", MSDNShortId = "NL:vswriter.IVssWriterComponents")] + public interface IVssWriterComponents + { + /// + /// The GetComponent method returns an IVssComponent interface to one of a given writer's components explicitly stored in the + /// Backup Components Document. + /// + /// List of IVssComponent objects that contain component information. + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsswritercomponents-getcomponent HRESULT GetComponent( + // [in] UINT iComponent, [out] IVssComponent **ppComponent ); + IReadOnlyList Components { get; } + + /// The GetWriterInfo method gets the instance and class identifier of the writer responsible for the components. + /// Identifier of the writer instance. + /// Identifier of the writer class. + // https://docs.microsoft.com/en-us/windows/win32/api/vswriter/nf-vswriter-ivsswritercomponents-getwriterinfo HRESULT GetWriterInfo( + // [out] VSS_ID *pidInstance, [out] VSS_ID *pidWriter ); + void GetWriterInfo(out Guid pidInstance, out Guid pidWriter); + } + + /// + /// + /// The GetDifferencedFile method returns information about a file set (a 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). + /// + /// This method can be called by a requester or a writer during backup or restore operations. + /// + /// + /// GetDifferencedFile can be called by a requester or a writer during backup or restore operations. + /// + /// If the call to GetDifferencedFile is successful, the caller is responsible for freeing the string that is returned in the + /// pbstrPath and pbstrFilespec parameters by calling the SysFreeString function. + /// + /// + /// As writers can indicate differenced files with calls to IVssComponent::AddDifferencedFilesByLastModifyTime at any time prior to the + /// actual backing up of files, typically while handling a PostSnapshot event (CVssWriter::OnPostSnapshot), during backups + /// GetDifferencedFile is not usefully called prior to the return of IVssBackupComponents::DoSnapshotSet has successfully returned. + /// + /// + /// The time stamp returned by GetDifferencedFile applies to all files that match the returned path (pbstrPath) and file + /// specification (pbstrFilespec). + /// + /// + /// If the time-stamp value returned by GetDifferencedFile (pftLastModifyTime) is nonzero, a requester must respect this value + /// regardless of its own records and file system information and use it to determine whether the differenced file should be included in + /// a differential or incremental backup. + /// + /// + /// If the time stamp returned by GetDifferencedFile is zero, the requester can use file system information and its own records + /// to determine whether the differenced files should be included in a differential or incremental backup. + /// + /// Differenced files can be either of the following: + /// + /// + /// + /// Members of the current component or, if the component defines a component set, members of its subcomponents that were added to the + /// component using IVssCreateWriterMetadata::AddFilesToFileGroup, IVssCreateWriterMetadata::AddDatabaseFiles, or IVssCreateWriterMetadata::AddDatabaseLogFiles + /// + /// + /// + /// New files added to the component by IVssComponent::AddDifferencedFilesByLastModifyTime + /// + /// + /// + /// When referring to a file set that is already part of the component, the combination of path, file specification, and recursion flag + /// (wszPath, wszFileSpec, and bRecursive, respectively) used when calling GetDifferencedFile should match that of a file set + /// already in the component, or one of its subcomponents (if the component defines a component set). + /// + /// + /// When GetDifferencedFile returns a differenced new file, that file's path (pbstrPath) should match or be beneath a path + /// already in the component, or one of its subcomponents (if the component defines a component set). + /// + /// In addition, the files returned by GetDifferencedFile should not already be managed by component or writer. + /// If any of these criteria are violated, they constitute an error on the part of the writer and should be reported. + /// + /// There is no method in the IVssComponent interface that allows for changing or adding an alternate location mapping for new files + /// returned by GetDifferencedFilesByLastModifyTime. If an alternate location mapping corresponds to the new file, then that + /// alternate location will be used. + /// + /// + public struct VssDifferencedFile + { + /// + /// String containing the file specification of the files to be mapped. + /// + /// A file specification cannot contain directory specifications (for example, no backslashes) but can contain the ? and * wildcard characters. + /// + /// + public string FileSpec; + + /// + /// The writer specification of the time of last modification for the difference files. + /// The last-modify time is always given in Greenwich Mean Time. + /// + public DateTime LastModifyTime; + + /// + /// String containing the name of the directory or directory hierarchy containing the files to be mapped. + /// The path can contain environment variables (for example, %SystemRoot%) but cannot contain wildcard characters. + /// + /// There is no requirement that the path end with a backslash (""). It is up to applications that retrieve this information to check. + /// + /// + public string Path; + + /// + /// + /// A Boolean value specifying whether the path specified by the wszPath parameter identifies only a single directory or if it + /// indicates a hierarchy of directories to be traversed recursively. This parameter should be set to true if the path is + /// treated as a hierarchy of directories to be traversed recursively, or false if not. + /// + /// For information on traversing mounted folders, see Working with Mounted Folders and Reparse Points. + /// + public bool Recursive; + } + + /// + /// + /// 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. + /// + /// + /// + /// 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. + /// + /// + public struct VssDirectedTarget + { + /// + /// 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 ?). + /// + public string DestinationFilename; + + /// String containing the path to which source file data will be remapped at restore time. + public string DestinationPath; + + /// + /// + /// 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. + /// + public string DestinationRangeList; + + /// + /// 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). + /// + public string SourceFilename; + + /// + /// 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). + /// + public string SourcePath; + + /// + /// + /// 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. + /// + public string SourceRangeList; + } + + /// + /// + /// The AddPartialFile method indicates that only portions of a given file are to be backed up and which portions those are. + /// + /// Only a writer can call this method, and only during a backup operation. + /// + /// + /// Only a writer can call this method, and the writer cannot call this method during a restore operation. + /// + /// The syntax of the range listing (wszRanges) 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. + /// + /// + /// If wszRange refers to a file containing all the offsets and lengths (a ranges file), wszRange will contain only the full path to the file. + /// + /// A ranges file must be a binary file with the following format: + /// + /// + /// A 64-bit integer indicating the number of distinct file ranges that need to be backed up + /// + /// + /// + /// Each range expressed as a pair of 64-bit integers: the offset into the file being backed up in bytes, and the length of data + /// starting from that offset to be backed up + /// + /// + /// + /// In either case, a range indicates a subsection of a given file that is to be backed up, independent of the rest of the file. + /// + /// Requesters can retrieve the partial file information using IVssComponent::GetPartialFile and use the offset and length information + /// returned by GetPartialFile to restore backed-up sections to the appropriate location within the copy of the file on disk at + /// restore time. + /// + /// + /// AddPartialFile can be applied to a file already managed by the component (or one of its subcomponents if the component + /// defines a component set), or it can add a new file to the component and indicate that it will participate in partial file operations. + /// + /// + /// When indicating that the file to participate is a new file, that file must exist on a shadow-copied volume and its path (wszPath) + /// should match or be beneath a path already in the component (or one of its subcomponents if the component defines a component set). + /// However, the file's file specification (wszFileSpec) should not match one in the components. + /// + /// Any newly added files will not support alternate location mappings. + /// + public struct VssPartialFile + { + /// + /// String containing the name of the file involved in partial file operations. The name of the file (wszFilename) cannot contain + /// wildcard characters (* or ?) and must be consistent with the file specification of a file set containing the source path (wszPath). + /// + public string Filename; + + /// + /// + /// String containing any additional metadata required by a writer to validate a partial file restore operation. The information in + /// this metadata string will be opaque to requesters. + /// + /// If additional metadata is not required, this value can be NULL. + /// + public string Metadata; + + /// + /// String containing the path of the file involved in partial file operations. + /// The path can contain environment variables (for example, %SystemRoot%) but cannot contain wildcard characters. + /// + /// There is no requirement that the path end with a backslash (""). It is up to applications that retrieve this information to check. + /// + /// + /// 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). + /// + /// + public string Path; + + /// + /// + /// String containing either a listing of file offsets and lengths that make up the partial file support range (the sections of the + /// file to actually be backed up), or the name of a file containing such a list. + /// + /// Specifying the partial file support range is required, and this value cannot be NULL. + /// + public string Ranges; + } + + /// + /// The GetRestoreSubcomponent method returns the specified subcomponent associated with a given component. + /// Either a writer or a requester can call this method. + /// + /// The caller should free the memory held by the pbstrLogicalPath and pbstrComponentName parameters by calling SysFreeString. + public struct VssRestoreSubcomponent + { + /// Reserved for future use. + public bool Repair; + + /// Pointer to a string containing the name of the subcomponent. The string cannot be empty. + public string ComponentName; + + /// + /// Pointer to a string containing the logical path of the subcomponent. The logical path cannot be empty when working with subcomponents. + /// + public string LogicalPath; } } \ No newline at end of file