|
|
/*++
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_
|