Leaked source code of windows server 2003
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

812 lines
20 KiB

/*++
Copyright (c) Microsoft Corporation. All rights reserved.
Abstract:
@doc
@module Writer.h | Declaration of Writer
@end
Author:
Adi Oltean [aoltean] 08/18/1999
TBD:
Add comments.
Revision History:
Name Date Comments
aoltean 08/18/1999 Created
brianb 03/28/2000 hid implementation details
mikejohn 09/18/2000 176860: Added calling convention methods where missing
--*/
#ifndef __CVSS_WRITER_H_
#define __CVSS_WRITER_H_
// declaration of how application data is used
typedef enum VSS_USAGE_TYPE
{
VSS_UT_UNDEFINED = 0,
VSS_UT_BOOTABLESYSTEMSTATE, // formerly "system state"
VSS_UT_SYSTEMSERVICE, // system service
VSS_UT_USERDATA, // user data
VSS_UT_OTHER // unclassified
};
typedef enum VSS_SOURCE_TYPE
{
VSS_ST_UNDEFINED = 0,
VSS_ST_TRANSACTEDDB, // transacted db (e.g., SQL Server, JET Blue)
VSS_ST_NONTRANSACTEDDB, // not transacted(e.g., Jet Red)
VSS_ST_OTHER // unclassified
};
typedef enum VSS_RESTOREMETHOD_ENUM
{
VSS_RME_UNDEFINED = 0,
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
};
typedef enum VSS_WRITERRESTORE_ENUM
{
VSS_WRE_UNDEFINED = 0,
VSS_WRE_NEVER,
VSS_WRE_IF_REPLACE_FAILS,
VSS_WRE_ALWAYS
};
typedef enum VSS_COMPONENT_TYPE
{
VSS_CT_UNDEFINED = 0,
VSS_CT_DATABASE,
VSS_CT_FILEGROUP
};
typedef enum VSS_ALTERNATE_WRITER_STATE
{
VSS_AWS_UNDEFINED = 0,
VSS_AWS_NO_ALTERNATE_WRITER,
VSS_AWS_ALTERNATE_WRITER_EXISTS,
VSS_AWS_THIS_IS_ALTERNATE_WRITER
};
// Flags to specify which types of events to receive. Used in Subscribe.
typedef enum VSS_SUBSCRIBE_MASK
{
VSS_SM_POST_SNAPSHOT_FLAG = 0x00000001,
VSS_SM_BACKUP_EVENTS_FLAG = 0x00000002,
VSS_SM_RESTORE_EVENTS_FLAG = 0x00000004,
VSS_SM_IO_THROTTLING_FLAG = 0x00000008,
VSS_SM_ALL_FLAGS = 0xffffffff
};
// enumeration of restore targets
typedef enum VSS_RESTORE_TARGET
{
VSS_RT_UNDEFINED = 0,
VSS_RT_ORIGINAL,
VSS_RT_ALTERNATE,
VSS_RT_DIRECTED
};
// enumeration of file restore status codes
typedef enum VSS_FILE_RESTORE_STATUS
{
VSS_RS_UNDEFINED = 0,
VSS_RS_NONE,
VSS_RS_ALL,
VSS_RS_FAILED
};
typedef enum VSS_COMPONENT_FLAGS
{
VSS_CF_BACKUP_RECOVERY = 0x00000001,
VSS_CF_APP_ROLLBACK_RECOVERY = 0x00000002
};
// file description
class IVssWMFiledesc : public IUnknown
{
public:
// get path to toplevel directory
STDMETHOD(GetPath)(OUT BSTR *pbstrPath) = 0;
// get filespec (may include wildcards)
STDMETHOD(GetFilespec)(OUT BSTR *pbstrFilespec) = 0;
// is path a directory or root of a tree
STDMETHOD(GetRecursive)(OUT bool *pbRecursive) = 0;
// alternate location for files
STDMETHOD(GetAlternateLocation)(OUT BSTR *pbstrAlternateLocation) = 0;
// backup type
STDMETHOD(GetBackupTypeMask)(OUT DWORD *pdwTypeMask) = 0;
};
// dependency description
class IVssWMDependency : public IUnknown
{
public:
STDMETHOD(GetWriterId)(OUT VSS_ID *pWriterId) = 0;
STDMETHOD(GetLogicalPath)(OUT BSTR *pbstrLogicalPath) = 0;
STDMETHOD(GetComponentName)(OUT BSTR *pbstrComponentName) = 0;
};
// backup components interface
class IVssComponent : public IUnknown
{
public:
// obtain logical path of component
STDMETHOD(GetLogicalPath)(OUT BSTR *pbstrPath) = 0;
// obtain component type(VSS_CT_DATABASE or VSS_CT_FILEGROUP)
STDMETHOD(GetComponentType)(VSS_COMPONENT_TYPE *pct) = 0;
// get component name
STDMETHOD(GetComponentName)(OUT BSTR *pbstrName) = 0;
// determine whether the component was successfully backed up.
STDMETHOD(GetBackupSucceeded)(OUT bool *pbSucceeded) = 0;
// get altermative location mapping count
STDMETHOD(GetAlternateLocationMappingCount)
(
OUT UINT *pcMappings
) = 0;
// get a paraticular alternative location mapping
STDMETHOD(GetAlternateLocationMapping)
(
IN UINT iMapping,
OUT IVssWMFiledesc **ppFiledesc
) = 0;
// set the backup metadata for a component
STDMETHOD(SetBackupMetadata)
(
IN LPCWSTR wszData
) = 0;
// get the backup metadata for a component
STDMETHOD(GetBackupMetadata)
(
OUT BSTR *pbstrData
) = 0;
// indicate that only ranges in the file are to be backed up
STDMETHOD(AddPartialFile)
(
IN LPCWSTR wszPath,
IN LPCWSTR wszFilename,
IN LPCWSTR wszRanges,
IN LPCWSTR wszMetadata
) = 0;
// get count of partial file declarations
STDMETHOD(GetPartialFileCount)
(
OUT UINT *pcPartialFiles
) = 0;
// get a partial file declaration
STDMETHOD(GetPartialFile)
(
IN UINT iPartialFile,
OUT BSTR *pbstrPath,
OUT BSTR *pbstrFilename,
OUT BSTR *pbstrRange,
OUT BSTR *pbstrMetadata
) = 0;
// determine if the component is selected to be restored
STDMETHOD(IsSelectedForRestore)
(
OUT bool *pbSelectedForRestore
) = 0;
STDMETHOD(GetAdditionalRestores)
(
OUT bool *pbAdditionalRestores
) = 0;
// get count of new target specifications
STDMETHOD(GetNewTargetCount)
(
OUT UINT *pcNewTarget
) = 0;
STDMETHOD(GetNewTarget)
(
IN UINT iNewTarget,
OUT IVssWMFiledesc **ppFiledesc
) = 0;
// add a directed target specification
STDMETHOD(AddDirectedTarget)
(
IN LPCWSTR wszSourcePath,
IN LPCWSTR wszSourceFilename,
IN LPCWSTR wszSourceRangeList,
IN LPCWSTR wszDestinationPath,
IN LPCWSTR wszDestinationFilename,
IN LPCWSTR wszDestinationRangeList
) = 0;
// get count of directed target specifications
STDMETHOD(GetDirectedTargetCount)
(
OUT UINT *pcDirectedTarget
) = 0;
// obtain a particular directed target specification
STDMETHOD(GetDirectedTarget)
(
IN UINT iDirectedTarget,
OUT BSTR *pbstrSourcePath,
OUT BSTR *pbstrSourceFileName,
OUT BSTR *pbstrSourceRangeList,
OUT BSTR *pbstrDestinationPath,
OUT BSTR *pbstrDestinationFilename,
OUT BSTR *pbstrDestinationRangeList
) = 0;
// set restore metadata associated with the component
STDMETHOD(SetRestoreMetadata)
(
IN LPCWSTR wszRestoreMetadata
) = 0;
// obtain restore metadata associated with the component
STDMETHOD(GetRestoreMetadata)
(
OUT BSTR *pbstrRestoreMetadata
) = 0;
// set the restore target
STDMETHOD(SetRestoreTarget)
(
IN VSS_RESTORE_TARGET target
) = 0;
// obtain the restore target
STDMETHOD(GetRestoreTarget)
(
OUT VSS_RESTORE_TARGET *pTarget
) = 0;
// set failure message during pre restore event
STDMETHOD(SetPreRestoreFailureMsg)
(
IN LPCWSTR wszPreRestoreFailureMsg
) = 0;
// obtain failure message during pre restore event
STDMETHOD(GetPreRestoreFailureMsg)
(
OUT BSTR *pbstrPreRestoreFailureMsg
) = 0;
// set the failure message during the post restore event
STDMETHOD(SetPostRestoreFailureMsg)
(
IN LPCWSTR wszPostRestoreFailureMsg
) = 0;
// obtain the failure message set during the post restore event
STDMETHOD(GetPostRestoreFailureMsg)
(
OUT BSTR *pbstrPostRestoreFailureMsg
) = 0;
// set the backup stamp of the backup
STDMETHOD(SetBackupStamp)
(
IN LPCWSTR wszBackupStamp
) = 0;
// obtain the stamp of the backup
STDMETHOD(GetBackupStamp)
(
OUT BSTR *pbstrBackupStamp
) = 0;
// obtain the backup stamp that the differential or incremental
// backup is baed on
STDMETHOD(GetPreviousBackupStamp)
(
OUT BSTR *pbstrBackupStamp
) = 0;
// obtain backup options for the writer
STDMETHOD(GetBackupOptions)
(
OUT BSTR *pbstrBackupOptions
) = 0;
// obtain the restore options
STDMETHOD(GetRestoreOptions)
(
OUT BSTR *pbstrRestoreOptions
) = 0;
// obtain count of subcomponents to be restored
STDMETHOD(GetRestoreSubcomponentCount)
(
OUT UINT *pcRestoreSubcomponent
) = 0;
// obtain a particular subcomponent to be restored
STDMETHOD(GetRestoreSubcomponent)
(
UINT iComponent,
OUT BSTR *pbstrLogicalPath,
OUT BSTR *pbstrComponentName,
OUT bool *pbRepair
) = 0;
// obtain whether files were successfully restored
STDMETHOD(GetFileRestoreStatus)
(
OUT VSS_FILE_RESTORE_STATUS *pStatus
) = 0;
// add differenced files by last modify time
STDMETHOD(AddDifferencedFilesByLastModifyTime)
(
IN LPCWSTR wszPath,
IN LPCWSTR wszFilespec,
IN BOOL bRecursive,
IN FILETIME ftLastModifyTime
) = 0;
STDMETHOD(AddDifferencedFilesByLastModifyLSN)
(
IN LPCWSTR wszPath,
IN LPCWSTR wszFilespec,
IN BOOL bRecursive,
IN BSTR bstrLsnString
) = 0;
STDMETHOD(GetDifferencedFilesCount)
(
OUT UINT *pcDifferencedFiles
) = 0;
STDMETHOD(GetDifferencedFile)
(
IN UINT iDifferencedFile,
OUT BSTR *pbstrPath,
OUT BSTR *pbstrFilespec,
OUT BOOL *pbRecursive,
OUT BSTR *pbstrLsnString,
OUT FILETIME *pftLastModifyTime
) = 0;
};
// backup writer components interface (i.e., all components for an
// individual writer
class IVssWriterComponents
{
public:
// get count of components
STDMETHOD(GetComponentCount)(OUT UINT *pcComponents) = 0;
// get information about the writer
STDMETHOD(GetWriterInfo)
(
OUT VSS_ID *pidInstance,
OUT VSS_ID *pidWriter
) = 0;
// obtain a specific component
STDMETHOD(GetComponent)
(
IN UINT iComponent,
OUT IVssComponent **ppComponent
) = 0;
};
// create backup metadata interface
class IVssCreateWriterMetadata
{
public:
// add files to include to metadata document
STDMETHOD(AddIncludeFiles)
(
IN LPCWSTR wszPath,
IN LPCWSTR wszFilespec,
IN bool bRecursive,
IN LPCWSTR wszAlternateLocation
) = 0;
// add files to exclude to metadata document
STDMETHOD(AddExcludeFiles)
(
IN LPCWSTR wszPath,
IN LPCWSTR wszFilespec,
IN bool bRecursive
) = 0;
// add component to metadata document
STDMETHOD(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 = false,
IN DWORD dwComponentFlags = 0
) = 0;
// add physical database files to a database component
STDMETHOD(AddDatabaseFiles)
(
IN LPCWSTR wszLogicalPath,
IN LPCWSTR wszDatabaseName,
IN LPCWSTR wszPath,
IN LPCWSTR wszFilespec,
IN DWORD dwBackupTypeMask = (VSS_FSBT_ALL_BACKUP_REQUIRED |
VSS_FSBT_ALL_SNAPSHOT_REQUIRED)
) = 0;
// add log files to a database component
STDMETHOD(AddDatabaseLogFiles)
(
IN LPCWSTR wszLogicalPath,
IN LPCWSTR wszDatabaseName,
IN LPCWSTR wszPath,
IN LPCWSTR wszFilespec,
IN DWORD dwBackupTypeMask = (VSS_FSBT_ALL_BACKUP_REQUIRED |
VSS_FSBT_ALL_SNAPSHOT_REQUIRED)
) = 0;
// add files to a FILE_GROUP component
STDMETHOD(AddFilesToFileGroup)
(
IN LPCWSTR wszLogicalPath,
IN LPCWSTR wszGroupName,
IN LPCWSTR wszPath,
IN LPCWSTR wszFilespec,
IN bool bRecursive,
IN LPCWSTR wszAlternateLocation,
IN DWORD dwBackupTypeMask = (VSS_FSBT_ALL_BACKUP_REQUIRED |
VSS_FSBT_ALL_SNAPSHOT_REQUIRED)
) = 0;
// create a restore method
STDMETHOD(SetRestoreMethod)
(
IN VSS_RESTOREMETHOD_ENUM method,
IN LPCWSTR wszService,
IN LPCWSTR wszUserProcedure,
IN VSS_WRITERRESTORE_ENUM writerRestore,
IN bool bRebootRequired
) = 0;
// add alternative location mappings to the restore method
STDMETHOD(AddAlternateLocationMapping)
(
IN LPCWSTR wszSourcePath,
IN LPCWSTR wszSourceFilespec,
IN bool bRecursive,
IN LPCWSTR wszDestination
) = 0;
// add a dependency to another writer's component
STDMETHOD(AddComponentDependency)
(
IN LPCWSTR wszForLogicalPath,
IN LPCWSTR wszForComponentName,
IN VSS_ID onWriterId,
IN LPCWSTR wszOnLogicalPath,
IN LPCWSTR wszOnComponentName
) = 0;
// Set the schema used during backup
STDMETHOD(SetBackupSchema)
(
IN DWORD dwSchemaMask
) = 0;
// obtain reference to actual XML document
STDMETHOD(GetDocument)(IXMLDOMDocument **pDoc) = 0;
// save document as an XML string
STDMETHOD(SaveAsXML)(BSTR *pbstrXML) = 0;
};
class IVssWriterImpl;
/////////////////////////////////////////////////////////////////////////////
// CVssWriter
class CVssWriter
{
// Constants
public:
// Constructors & Destructors
public:
__declspec(dllexport)
STDMETHODCALLTYPE CVssWriter();
__declspec(dllexport)
virtual STDMETHODCALLTYPE ~CVssWriter();
// Exposed operations
public:
// initialize the writer object
__declspec(dllexport)
HRESULT STDMETHODCALLTYPE Initialize
(
IN VSS_ID WriterID,
IN LPCWSTR wszWriterName,
IN VSS_USAGE_TYPE ut,
IN VSS_SOURCE_TYPE st,
IN VSS_APPLICATION_LEVEL nLevel = VSS_APP_FRONT_END,
IN DWORD dwTimeoutFreeze = 60000, // Maximum milliseconds between Freeze/Thaw
IN VSS_ALTERNATE_WRITER_STATE aws = VSS_AWS_NO_ALTERNATE_WRITER,
IN bool bIOThrottlingOnly = false,
IN LPCWSTR wszReserved = NULL
);
// cause the writer to subscribe to events.
__declspec(dllexport)
HRESULT STDMETHODCALLTYPE Subscribe
(
IN DWORD dwEventFlags = VSS_SM_BACKUP_EVENTS_FLAG | VSS_SM_RESTORE_EVENTS_FLAG
);
// cause the writer to unsubscribe from events
__declspec(dllexport)
HRESULT STDMETHODCALLTYPE Unsubscribe();
// installs an alternative writer
__declspec(dllexport)
HRESULT STDMETHODCALLTYPE InstallAlternateWriter
(
IN VSS_ID writerId,
IN CLSID persistentWriterClassId
);
// Internal properties - accessible from OnXXX methods
protected:
// get array of volume names
__declspec(dllexport)
LPCWSTR* STDMETHODCALLTYPE GetCurrentVolumeArray() const;
// get count of volume names in array
__declspec(dllexport)
UINT STDMETHODCALLTYPE GetCurrentVolumeCount() const;
// get the name of the snapshot device corresponding to a given volume.
__declspec(dllexport)
HRESULT STDMETHODCALLTYPE GetSnapshotDeviceName
(
IN LPCWSTR wszOriginalVolume,
OUT LPCWSTR* ppwszSnapshotDevice
) const;
// current snapshot set GUID
__declspec(dllexport)
VSS_ID STDMETHODCALLTYPE GetCurrentSnapshotSetId() const;
// Current backup context.
__declspec(dllexport)
LONG STDMETHODCALLTYPE GetContext() const;
// current app level (either 1,2,3)
__declspec(dllexport)
VSS_APPLICATION_LEVEL STDMETHODCALLTYPE GetCurrentLevel() const;
// determine if path is in set of volumes being snapshotted
__declspec(dllexport)
bool STDMETHODCALLTYPE IsPathAffected
(
IN LPCWSTR wszPath
) const;
// does the backup include bootable state (formerly system state backup)
__declspec(dllexport)
bool STDMETHODCALLTYPE IsBootableSystemStateBackedUp() const;
// is the backup application smart (i.e., selecting components) or
// dump (i.e., just selecting volumes)
__declspec(dllexport)
bool STDMETHODCALLTYPE AreComponentsSelected() const;
__declspec(dllexport)
VSS_BACKUP_TYPE STDMETHODCALLTYPE GetBackupType() const;
__declspec(dllexport)
VSS_RESTORE_TYPE STDMETHODCALLTYPE GetRestoreType() const;
__declspec(dllexport)
bool STDMETHODCALLTYPE IsPartialFileSupportEnabled() const;
_declspec(dllexport)
HRESULT STDMETHODCALLTYPE SetWriterFailure(HRESULT hr);
// Ovverides
public:
// callback when request for metadata comes in
__declspec(dllexport)
virtual bool STDMETHODCALLTYPE OnIdentify(IN IVssCreateWriterMetadata *pMetadata);
// callback for prepare backup event
__declspec(dllexport)
virtual bool STDMETHODCALLTYPE OnPrepareBackup(
IN IVssWriterComponents *pComponent
);
// callback for prepare snapsot event
virtual bool STDMETHODCALLTYPE OnPrepareSnapshot() = 0;
// callback for freeze event
virtual bool STDMETHODCALLTYPE OnFreeze() = 0;
// callback for thaw event
virtual bool STDMETHODCALLTYPE OnThaw() = 0;
// callback if current sequence is aborted
virtual bool STDMETHODCALLTYPE OnAbort() = 0;
// callback on backup complete event
__declspec(dllexport)
virtual bool STDMETHODCALLTYPE OnBackupComplete
(
IN IVssWriterComponents *pComponent
);
// callback indicating that the backup process has either completed or has shut down
__declspec(dllexport)
virtual bool STDMETHODCALLTYPE OnBackupShutdown
(
IN VSS_ID SnapshotSetId
);
// callback on pre-restore event
__declspec(dllexport)
virtual bool STDMETHODCALLTYPE OnPreRestore
(
IN IVssWriterComponents *pComponent
);
// callback on post-restore event
__declspec(dllexport)
virtual bool STDMETHODCALLTYPE OnPostRestore
(
IN IVssWriterComponents *pComponent
);
// callback on post snapshot event
__declspec(dllexport)
virtual bool STDMETHODCALLTYPE OnPostSnapshot
(
IN IVssWriterComponents *pComponent
);
// callback on back off I/O volume event
__declspec(dllexport)
virtual bool STDMETHODCALLTYPE OnBackOffIOOnVolume
(
IN VSS_PWSZ wszVolumeName,
IN VSS_ID snapshotId,
IN VSS_ID providerId
);
// callback on Continue I/O on volume event
__declspec(dllexport)
virtual bool STDMETHODCALLTYPE OnContinueIOOnVolume
(
IN VSS_PWSZ wszVolumeName,
IN VSS_ID snapshotId,
IN VSS_ID providerId
);
// callback to specify that the volume snaphost service is shutting down. Used
// by alternative writers to signal when to shutdown.
__declspec(dllexport)
virtual bool STDMETHODCALLTYPE OnVSSShutdown();
// callback to an alternative writer when the application writer subscribes. Used to
// signal the alternative writer to shutdown.
__declspec(dllexport)
virtual bool STDMETHODCALLTYPE OnVSSApplicationStartup();
private:
IVssWriterImpl *m_pWrapper;
};
//
// MessageId: VSS_E_WRITERERROR_INCONSISTENTSNAPSHOT
//
// MessageText:
//
// indicates that the snapshot contains only a subset of the
// volumes needed to correctly backup an application component
//
const HRESULT VSS_E_WRITERERROR_INCONSISTENTSNAPSHOT = (0x800423f0L);
//
// MessageId: VSS_E_WRITERERROR_OUTOFRESOURCES
//
// MessageText:
//
// indicates that the writer failed due to an out of memory,
// out of handles, or other resource allocation failure
//
const HRESULT VSS_E_WRITERERROR_OUTOFRESOURCES = (0x800423f1L);
//
// MessageId: VSS_E_WRITERERROR_TIMEOUT
//
// MessageText:
//
// indicates that the writer failed due to a timeout between
// freeze and thaw.
//
const HRESULT VSS_E_WRITERERROR_TIMEOUT = (0x800423f2L);
//
// MessageId: VSS_E_WRITERERROR_RETRYABLE
//
// MessageText:
//
// indicates that the writer failed due to an error
// that might not occur if another snapshot is created
//
const HRESULT VSS_E_WRITERERROR_RETRYABLE = (0x800423f3L);
//
// MessageId: VSS_E_WRITERERROR_NONRETRYABLE
//
// MessageText:
//
// indicates that the writer failed due to an error
// that most likely would occur if another snapshot is created
//
const HRESULT VSS_E_WRITERERROR_NONRETRYABLE = (0x800423f4L);
//
// MessageId: VSS_E_WRITERERROR_RECOVERY_FAILED
//
// MessageText:
//
// indicates that auto recovery of the snapshot volume failed
const HRESULT VSS_E_WRITERERROR_RECOVERY_FAILED = (0x800423f5L);
#endif //__CVSS_WRITER_H_