///////////////////////////////////////////////////////////////////////////////
//
//  vsmgmt.idl - Interfaces for Snapshots management exposed by VSS and/or providers
//
//  Copyright (c) 2000  Microsoft Corporation
//


///////////////////////////////////////////////////////////////////////////////
//  Imports
//

cpp_quote("#include <winapifamily.h>")

#pragma region Desktop Family
cpp_quote("#if WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_DESKTOP)")

import "oaidl.idl";
import "ocidl.idl";

import "vss.idl";


///////////////////////////////////////////////////////////////////////////////
// Constants
//


// Types of returned objects in a Query
typedef enum _VSS_MGMT_OBJECT_TYPE {
    VSS_MGMT_OBJECT_UNKNOWN = 0,                            
    VSS_MGMT_OBJECT_VOLUME,             // Refers to a volume to be snapshotted                 
    VSS_MGMT_OBJECT_DIFF_VOLUME,        // Refers to a volume to hold a diff area
    VSS_MGMT_OBJECT_DIFF_AREA,          // Refers to an association between the two objects above.
} VSS_MGMT_OBJECT_TYPE, *PVSS_MGMT_OBJECT_TYPE;


// Denotes that no maximum space is specified in AddDiffArea or ChangeDiffAreaMaximumSize
const LONGLONG VSS_ASSOC_NO_MAX_SPACE = -1;

// If this constant is specified in ChangeDiffAreaMaximumSize then the association is removed
const LONGLONG VSS_ASSOC_REMOVE = 0;


///////////////////////////////////////////////////////////////////////////////
// Typedefs and structures
//


// Structure containing the properties of a volume as being a volume to be snapshotted.
typedef struct _VSS_VOLUME_PROP {
    VSS_PWSZ    m_pwszVolumeName;           // The volume name, in \\?\Volume{GUID} format.
    VSS_PWSZ    m_pwszVolumeDisplayName;    // The shortest mount point (for example C:\)
} VSS_VOLUME_PROP, *PVSS_VOLUME_PROP;               


// Structure containing the properties of a volume that can be used to keep a diff area
typedef struct _VSS_DIFF_VOLUME_PROP {
    VSS_PWSZ    m_pwszVolumeName;           // The volume name, in \\?\Volume{GUID} format.
    VSS_PWSZ    m_pwszVolumeDisplayName;    // Represents the shortest mount point (for example C:\)
    LONGLONG    m_llVolumeFreeSpace;        // Free space on that volume
    LONGLONG    m_llVolumeTotalSpace;       // Total space on that volume
} VSS_DIFF_VOLUME_PROP, *PVSS_DIFF_VOLUME_PROP;             


// Structure containing the properties of a diff area association between
// a volume to be snapshotted and a diff volume.
typedef struct _VSS_DIFF_AREA_PROP {
    VSS_PWSZ  m_pwszVolumeName;             // The original volume name
    VSS_PWSZ  m_pwszDiffAreaVolumeName;     // The diff area volume name
    LONGLONG  m_llMaximumDiffSpace;         // Maximum space that on the diff area volume in this association.
    LONGLONG  m_llAllocatedDiffSpace;       // Allocated space on the diff area volume by this association.
    LONGLONG  m_llUsedDiffSpace;            // Used space from the allocated area above.
} VSS_DIFF_AREA_PROP, *PVSS_DIFF_AREA_PROP;             


// General-purpose union containing the properties of a volume or diff area
[ switch_type(VSS_MGMT_OBJECT_TYPE) ]
typedef union {                     
    [case(VSS_MGMT_OBJECT_VOLUME)]      VSS_VOLUME_PROP         Vol;
    [case(VSS_MGMT_OBJECT_DIFF_VOLUME)] VSS_DIFF_VOLUME_PROP    DiffVol;
    [case(VSS_MGMT_OBJECT_DIFF_AREA)]   VSS_DIFF_AREA_PROP      DiffArea;
    [default];
} VSS_MGMT_OBJECT_UNION, *PVSS_MGMT_OBJECT_UNION;


typedef struct _VSS_MGMT_OBJECT_PROP {
    VSS_MGMT_OBJECT_TYPE Type;                          
    [ switch_is(Type) ] VSS_MGMT_OBJECT_UNION Obj;      
} VSS_MGMT_OBJECT_PROP, *PVSS_MGMT_OBJECT_PROP;

// Snapshot protection levels
typedef enum _VSS_PROTECTION_LEVEL {
    VSS_PROTECTION_LEVEL_ORIGINAL_VOLUME = 0,  // protection mode off - writes to the original volume succeed at the cost of snapshots                   
    VSS_PROTECTION_LEVEL_SNAPSHOT,             // protection mode on - snapshots are retained at the cost of failed IO on the original volume
} VSS_PROTECTION_LEVEL, *PVSS_PROTECTION_LEVEL;

typedef enum _VSS_PROTECTION_FAULT {
    VSS_PROTECTION_FAULT_NONE = 0,                            
    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;

typedef struct _VSS_VOLUME_PROTECTION_INFO {
    VSS_PROTECTION_LEVEL   m_protectionLevel;               // Target protection level for the volume
    BOOL                   m_volumeIsOfflineForProtection;  // The volume is offline due to a protection violation
    VSS_PROTECTION_FAULT   m_protectionFault;               // The protection fault that caused the volume to go offline
    LONG                   m_failureStatus;                 // The internal failure status code
    BOOL                   m_volumeHasUnusedDiffArea;       // The volume has unused diff area files
    DWORD                  m_reserved;
} VSS_VOLUME_PROTECTION_INFO, *PVSS_VOLUME_PROTECTION_INFO;


///////////////////////////////////////////////////////////////////////////////
//  Forward declarations
//

interface IVssSnapshotMgmt;
interface IVssDifferentialSoftwareSnapshotMgmt;
interface IVssEnumMgmtObject;


///////////////////////////////////////////////////////////////////////////////
//  Interfaces
//


// Used to manage diff areas remotely for Software-based snapshots (using hte copy-on-write mechanism).
// Implemented by VSS and each provider.
[
    object,
    uuid(FA7DF749-66E7-4986-A27F-E2F04AE53772),
    helpstring("IVssSnapshotMgmt interface"),
    pointer_default(unique)
]
interface IVssSnapshotMgmt: IUnknown
{
    // Returns an interface to further configure a snapshot provider
    HRESULT GetProviderMgmtInterface(                           
        [in]    VSS_ID      ProviderId,     //  It might be a software or a system provider.
        [in]    REFIID      InterfaceId,    //  Might be IID_IVssDifferentialSoftwareSnapshotMgmt
        [out, iid_is(InterfaceId)]
                IUnknown**  ppItf
        );                                              

    //
    //  Queries
    //

    // Query volumes that support snapshots
    HRESULT QueryVolumesSupportedForSnapshots(
        [in]    VSS_ID      ProviderId,
        [in]    LONG        lContext,
        [out]   IVssEnumMgmtObject **ppEnum
        );                                              

    // Query snapshots on the given volume.
    HRESULT QuerySnapshotsByVolume(
        [in]    VSS_PWSZ    pwszVolumeName,
        [in]    VSS_ID      ProviderId,
        [out]   IVssEnumObject **ppEnum
        );                                              
};



// More APIs to manage diff areas remotely for Software-based snapshots (using hte copy-on-write mechanism).
// Implemented by VSS 
[
    object,
    uuid(0f61ec39-fe82-45f2-a3f0-768b5d427102),
    helpstring("IVssSnapshotMgmt2 interface"),
    pointer_default(unique)
]
interface IVssSnapshotMgmt2: IUnknown
{
    // Returns an interface to further configure a snapshot provider
    HRESULT GetMinDiffAreaSize(                            
        [out]    LONGLONG *   pllMinDiffAreaSize
        );                                                
};



// Used to manage diff areas remotely for Software-based
// snapshots (using the copy-on-write mechanism).
// This is implemented by a Snapshot/System provider and
// returned by IVssSnapshotMgmt::GetProviderMgmtInterface
[
    object,
    uuid(214A0F28-B737-4026-B847-4F9E37D79529),
    helpstring("IVssDifferentialSoftwareSnapshotMgmt interface"),
    pointer_default(unique)
]
interface IVssDifferentialSoftwareSnapshotMgmt: IUnknown
{
    //
    //  Diff area management
    //

    // Adds a diff area association for a certain volume.
    // If the association is not supported, an error code will be returned.
    HRESULT AddDiffArea(                            
        [in]    VSS_PWSZ    pwszVolumeName,
        [in]    VSS_PWSZ    pwszDiffAreaVolumeName,
        [in]    LONGLONG    llMaximumDiffSpace
        );                                              

    // Updates the diff area max size for a certain volume.
    // This may not have an immediate effect
    // note that setting llMaximumDiffSpace to 0 will disable the
    // diff area
    HRESULT ChangeDiffAreaMaximumSize(                          
        [in]    VSS_PWSZ    pwszVolumeName,
        [in]    VSS_PWSZ    pwszDiffAreaVolumeName,
        [in]    LONGLONG    llMaximumDiffSpace
        );                                              

    //
    //  Queries
    //

    // Query volumes that support diff areas (including the disabled ones)
    HRESULT QueryVolumesSupportedForDiffAreas(
        [in]    VSS_PWSZ    pwszOriginalVolumeName,
        [out]   IVssEnumMgmtObject **ppEnum
        );                                              

    // Query diff areas that host snapshots on the given (snapshotted) volume
    HRESULT QueryDiffAreasForVolume(
        [in]    VSS_PWSZ    pwszVolumeName,
        [out]   IVssEnumMgmtObject **ppEnum
        );                                              

    // Query diff areas that physically reside on the given volume
    HRESULT QueryDiffAreasOnVolume(
        [in]    VSS_PWSZ    pwszVolumeName,
        [out]   IVssEnumMgmtObject **ppEnum
        );                                              

    // Query diff areas in use by the given snapshot
    HRESULT QueryDiffAreasForSnapshot(
        [in]    VSS_ID      SnapshotId,     
        [out]   IVssEnumMgmtObject **ppEnum
        );                                              
};

[
    object,
    uuid(949d7353-675f-4275-8969-f044c6277815),
    helpstring("IVssDifferentialSoftwareSnapshotMgmt interface2"),
    pointer_default(unique)
]
interface IVssDifferentialSoftwareSnapshotMgmt2 : IVssDifferentialSoftwareSnapshotMgmt
{
    HRESULT ChangeDiffAreaMaximumSizeEx(
            [in]    VSS_PWSZ    pwszVolumeName,
            [in]    VSS_PWSZ    pwszDiffAreaVolumeName,
            [in]    LONGLONG    llMaximumDiffSpace,
            [in]       BOOL          bVolatile
            );

        HRESULT MigrateDiffAreas(
               [in]    VSS_PWSZ    pwszVolumeName,
               [in]    VSS_PWSZ    pwszDiffAreaVolumeName,
               [in]    VSS_PWSZ    pwszNewDiffAreaVolumeName
               );

        HRESULT QueryMigrationStatus(
               [in]    VSS_PWSZ    pwszVolumeName,
               [in]    VSS_PWSZ    pwszDiffAreaVolumeName,              
               [out]   IVssAsync** ppAsync
               );

        HRESULT SetSnapshotPriority(
               [in]    VSS_ID        idSnapshot,
               [in]    BYTE           priority
        );
};

[
    object,
    uuid(383f7e71-a4c5-401f-b27f-f826289f8458),
    helpstring("IVssDifferentialSoftwareSnapshotMgmt interface 3"),
    pointer_default(unique)
]
interface IVssDifferentialSoftwareSnapshotMgmt3 : IVssDifferentialSoftwareSnapshotMgmt2 
{
        // Set the VSS protection level for a volume.
        HRESULT SetVolumeProtectLevel(
            [in] VSS_PWSZ                pwszVolumeName,
            [in] VSS_PROTECTION_LEVEL    protectionLevel
            );

        // Returns the VSS_VOLUME_PROTECTION_INFO structure for the specified volume
        HRESULT GetVolumeProtectLevel(
            [in]  VSS_PWSZ                      pwszVolumeName,
            [out] VSS_VOLUME_PROTECTION_INFO    *protectionLevel
            );

        // Dismount the volume and clear the protection fault to allow normal
        // IO to continue on the volume
        HRESULT ClearVolumeProtectFault (
            [in]  VSS_PWSZ pwszVolumeName
            );                                              

        // Delete all the diff areas that are not currently in use and that exist on the specified volume
        // This is the only way to delete unused diff areas on volume that is in 
        // Snapshot Protection  mode
        HRESULT DeleteUnusedDiffAreas(
            [in] VSS_PWSZ pwszDiffAreaVolumeName
            );

        // Returns a bitmap that represents the delta change between two snapshots.
        // The caller is responsible for freeing memory allocated for the bitmap array. 
        HRESULT QuerySnapshotDeltaBitmap(
            [in] VSS_ID idSnapshotOlder,
            [in] VSS_ID idSnapshotYounger,
            [out] ULONG* pcBlockSizePerBit,
            [out] ULONG* pcBitmapLength,
            [out, size_is(, *pcBitmapLength)] BYTE** ppbBitmap
            );
            
}


// This returns a set of volumes that can be snapshotted by Babbage. Returned by Query.
[
    object,
    uuid(01954E6B-9254-4e6e-808C-C9E05D007696),
    helpstring("IVssEnumMgmtObject Interface"),
    pointer_default(unique)
]
interface IVssEnumMgmtObject : IUnknown
{
    HRESULT Next(                                       
        [in]    ULONG celt,                             
        [out, size_is(celt), length_is(*pceltFetched)]
                VSS_MGMT_OBJECT_PROP *rgelt,                
        [out]   ULONG *pceltFetched                     
        );                                              

    HRESULT Skip(                                       
        [in] ULONG celt                                 
        );                                              

    HRESULT Reset();                                    

    HRESULT Clone(                                      
        [in, out] IVssEnumMgmtObject **ppenum               
        );                                              
};


////////////////////////////////////////////////////////////////////////////////
//  Snapshot Mgmt Type Library
//

[
    uuid(84015C41-291D-49e6-BF7F-DD40AE93632B),
    version(1.0),
    helpstring("Shadow Copy Mgmt 1.0 Type Library")
]
library VSMGMT
{
    importlib("stdole2.tlb");

    [
        uuid(0B5A2C52-3EB9-470a-96E2-6C6D4570E40F),
        helpstring("VssSnapshotMgmt Class")
    ]
    coclass VssSnapshotMgmt
    {
        [default] interface IVssSnapshotMgmt;
        interface IVssSnapshotMgmt2;
    }
}

cpp_quote("#endif /* WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_DESKTOP) */")
#pragma endregion