CDataRecoveryHandler Class
The CDataRecoveryHandler
autosaves documents and restores them if an application unexpectedly exits.
Syntax
class CDataRecoveryHandler : public CObject
Members
Constructors
Name | Description |
---|---|
CDataRecoveryHandler::CDataRecoveryHandler | Constructs a CDataRecoveryHandler object. |
Methods
Name | Description |
---|---|
CDataRecoveryHandler::AutosaveAllDocumentInfo | Autosaves each file registered with the CDataRecoveryHandler class. |
CDataRecoveryHandler::AutosaveDocumentInfo | Autosaves the specified document. |
CDataRecoveryHandler::CreateDocumentInfo | Adds a document to the list of open documents. |
CDataRecoveryHandler::DeleteAllAutosavedFiles | Deletes all the current autosaved files. |
CDataRecoveryHandler::DeleteAutosavedFile | Deletes the specified autosaved file. |
CDataRecoveryHandler::GenerateAutosaveFileName | Generates the name for an autosave file associated with the supplied document file name. |
CDataRecoveryHandler::GetAutosaveInterval | Returns the interval between autosave tries. |
CDataRecoveryHandler::GetAutosavePath | Returns the path of the autosaved files. |
CDataRecoveryHandler::GetDocumentListName | Retrieves the document name from a CDocument object. |
CDataRecoveryHandler::GetNormalDocumentTitle | Retrieves the normal title for the specified document. |
CDataRecoveryHandler::GetRecoveredDocumentTitle | Creates and returns the title for the recovered document. |
CDataRecoveryHandler::GetRestartIdentifier | Retrieves the unique restart identifier for the application. |
CDataRecoveryHandler::GetSaveDocumentInfoOnIdle | Indicates whether the CDataRecoveryHandler performs an autosave on the current idle loop. |
CDataRecoveryHandler::GetShutdownByRestartManager | Indicates whether the restart manager caused the application to exit. |
CDataRecoveryHandler::Initialize | Initializes the CDataRecoveryHandler . |
CDataRecoveryHandler::QueryRestoreAutosavedDocuments | Displays a dialog box to the user for each document that the CDataRecoveryHandler autosaved. The dialog box determines whether the user wants to restore the autosaved document. |
CDataRecoveryHandler::ReadOpenDocumentList | Loads the open document list from the registry. |
CDataRecoveryHandler::RemoveDocumentInfo | Removes the supplied document from the open document list. |
CDataRecoveryHandler::ReopenPreviousDocuments | Opens the previously open documents. |
CDataRecoveryHandler::RestoreAutosavedDocuments | Restores the autosaved documents based on user input. |
CDataRecoveryHandler::SaveOpenDocumentList | Saves the current list of open documents to the Windows registry. |
CDataRecoveryHandler::SetAutosaveInterval | Sets the time between autosave cycles in milliseconds. |
CDataRecoveryHandler::SetAutosavePath | Sets the directory where autosaved files are stored. |
CDataRecoveryHandler::SetRestartIdentifier | Sets the unique restart identifier for this instance of the CDataRecoveryHandler . |
CDataRecoveryHandler::SetSaveDocumentInfoOnIdle | Sets whether the CDataRecoveryHandler saves the open document information to the Windows registry during the current idle cycle. |
CDataRecoveryHandler::SetShutdownByRestartManager | Sets whether the previous exit of the application was caused by the restart manager. |
CDataRecoveryHandler::UpdateDocumentInfo | Updates the information for a document because the user saved it. |
Data Members
Name | Description |
---|---|
m_bRestoringPreviousOpenDocs | Indicates whether the data recovery handler reopens previously open documents. |
m_bSaveDocumentInfoOnIdle | Indicates whether the data recovery handler autosaves documents on the next idle loop. |
m_bShutdownByRestartManager | Indicates whether the restart manager causes the application to exit. |
m_dwRestartManagerSupportFlags | Flags that indicate what support the restart manager provides for the application. |
m_lstAutosavesToDelete | A list of autosaved files that were not deleted when the original documents were closed. When the application exits, the restart manager retries deleting the files. |
m_mapDocNameToAutosaveName | A map of the document names to the autosaved file names. |
m_mapDocNameToDocumentPtr | A map of the document names to the CDocument pointers. |
m_mapDocNameToRestoreBool | A map of the document names to a Boolean parameter that indicates whether to restore the autosaved document. |
m_mapDocumentPtrToDocName | A map of the CDocument pointers to the document names. |
m_mapDocumentPtrToDocTitle | A map of the CDocument pointers to the document titles. These titles are used for saving files. |
m_nAutosaveInterval | Time in milliseconds between autosaves. |
m_nTimerID | The identifier for the autosave timer. |
m_strAutosavePath | The location where the autosaved documents are stored. |
m_strRestartIdentifier | The string representation of a GUID for the restart manager. |
Remarks
The restart manager uses the CDataRecoveryHandler
class to keep track of all open documents and to autosave them as necessary. To enable autosave, use the CDataRecoveryHandler::SetSaveDocumentInfoOnIdle method. This method directs the CDataRecoveryHandler
to perform an autosave on the next idle loop. The restart manager calls SetSaveDocumentInfoOnIdle
when the CDataRecoveryHandler
should perform an autosave.
All of the methods of the CDataRecoveryHandler
class are virtual. Override the methods in this class to create your own custom data recovery handler. Unless you create your own data recovery handler or restart manager, do not instantiate a CDataRecoveryHandler. The CWinApp Class creates a CDataRecoveryHandler
object as it is required.
Before you can use a CDataRecoveryHandler
object, you must call CDataRecoveryHandler::Initialize.
Because the CDataRecoveryHandler
class is closely connected to the restart manager, CDataRecoveryHandler
depends on the global parameter m_dwRestartManagerSupportFlags
. This parameter determines what permissions the restart manager has and how it interacts with your application. To incorporate the restart manager into an existing application, you have to assign m_dwRestartManagerSupportFlags
the appropriate value in the constructor of your main application. For more information about how to use the restart manager, see How to: Add Restart Manager Support.
Requirements
Header: afxdatarecovery.h
CDataRecoveryHandler::AutosaveAllDocumentInfo
Autosaves each file registered with the CDataRecoveryHandler
class.
virtual BOOL AutosaveAllDocumentInfo();
Return Value
TRUE if the CDataRecoveryHandler
saved all the documents; FALSE if any document was not saved.
Remarks
This method returns TRUE if there are no documents that must be saved. It also returns TRUE without saving any documents if retrieving the CWinApp
or CDocManager
for the application generates an error.
To use this method, either AFX_RESTART_MANAGER_AUTOSAVE_AT_RESTART or AFX_RESTART_MANAGER_AUTOSAVE_AT_INTERVAL must be set in m_dwRestartManagerSupportFlags
. For more information, see How to: Add Restart Manager Support.
CDataRecoveryHandler::AutosaveDocumentInfo
Autosaves the specified document.
virtual BOOL AutosaveDocumentInfo(
CDocument* pDocument,
BOOL bResetModifiedFlag = TRUE);
Parameters
pDocument
[in] A pointer to the CDocument
to save.
bResetModifiedFlag
[in] TRUE indicates that the CDataRecoveryHandler
considers pDocument to be modified; FALSE indicates that the framework considers pDocument to be unmodified. See the Remarks section for more information about the effect of this flag.
Return Value
TRUE if the appropriate flags are set and pDocument is a valid CDocument
object.
Remarks
Each CDocument
object has a flag that indicates if it has changed since the last save. Use CDocument::IsModified to determine the state of this flag. If a CDocument
has not changed since the last save, AutosaveDocumentInfo
deletes any autosaved files for that document. If a document has changed since the last save, closing it prompts the user to save the document before closing.
Note
Using bResetModifiedFlag to change the state of the document to unmodified may cause the user to lose unsaved data. If the framework considers a document unmodified, closing it does not prompt the user to save.
This method throws an exception with the ASSERT macro if pDocument is not a valid CDocument
object.
To use this method, either AFX_RESTART_MANAGER_AUTOSAVE_AT_RESTART or AFX_RESTARTMANAGER_AUTOSAVE_AT_INTERVAL must be set in m_dwRestartManagerSupportFlags.
CDataRecoveryHandler::CDataRecoveryHandler
Constructs a CDataRecoveryHandler
object.
CDataRecoveryHandler(
DWORD dwRestartManagerSupportFlags,
int nAutosaveInterval);
Parameters
dwRestartManagerSupportFlags
[in] Indicates which options of the restart manager are supported.
nAutosaveInterval
[in] The time between autosaves. This parameter is in milliseconds.
Remarks
The MFC framework automatically creates a CDataRecoveryHandler
object for your application when you use the New Project wizard. Unless you are customizing the data recovery behavior or the restart manager, you should not create a CDataRecoveryHandler
object.
CDataRecoveryHandler::CreateDocumentInfo
Adds a document to the list of open documents.
virtual BOOL CreateDocumentInfo(CDocument* pDocument);
Parameters
pDocument
[in] A pointer to a CDocument
. This method creates the document information for this CDocument
.
Return Value
The default implementation returns TRUE.
Remarks
This method checks if pDocument is already in the list of documents before it adds the document. If pDocument is already in the list, this method deletes the autosaved file associated with pDocument.
To use this method, either AFX_RESTART_MANAGER_AUTOSAVE_AT_RESTART or AFX_RESTARTMANAGER_AUTOSAVE_AT_INTERVAL must be set in m_dwRestartManagerSupportFlags.
CDataRecoveryHandler::DeleteAllAutosavedFiles
Deletes all the current autosaved files.
virtual BOOL DeleteAllAutosavedFiles();
Return Value
The default implementation always returns TRUE.
CDataRecoveryHandler::DeleteAutosavedFile
Deletes the specified autosaved file.
virtual BOOL DeleteAutosavedFile(const CString& strAutosavedFile);
Parameters
strAutosavedFile
[in] A string that contains the autosaved file name.
Return Value
The default implementation always return TRUE.
Remarks
If this method cannot delete the autosaved file, it saves the name of the file in a list. The destructor for the CDataRecoveryHandler
tries to delete each autosaved file specified in that list.
CDataRecoveryHandler::GenerateAutosaveFileName
Generates the name for an autosave file associated with the supplied document file name.
virtual CString GenerateAutosaveFileName(const CString& strDocumentName) const;
Parameters
strDocumentName
[in] A string that contains the document name. GenerateAutosaveFileName
uses this document name to generate a corresponding autosave file name.
Return Value
The autosave file name generated from strDocumentName.
Remarks
Each document name has a one-to-one mapping with an autosave file name.
CDataRecoveryHandler::GetAutosaveInterval
Returns the interval between autosave tries.
virtual int GetAutosaveInterval() const;
Return Value
The number of milliseconds between autosave tries.
CDataRecoveryHandler::GetAutosavePath
Returns the path of the autosaved files.
virtual CString GetAutosavePath() const;
Return Value
The location where the autosaved documents are stored.
CDataRecoveryHandler::GetDocumentListName
Retrieves the document name from a CDocument
object.
virtual CString GetDocumentListName(CDocument* pDocument) const;
Parameters
pDocument
[in] A pointer to a CDocument
. GetDocumentListName
retrieves the document name from this CDocument
.
Return Value
The document name from pDocument.
Remarks
The CDataRecoveryHandler
uses the document name as the key in m_mapDocNameToAutosaveName, m_mapDocNameToDocumentPtr, and m_mapDocNameToRestoreBool. These parameter enable the CDataRecoveryHandler
to monitor CDocument
objects, the autosave file name, and the autosave settings.
CDataRecoveryHandler::GetNormalDocumentTitle
Retrieves the normal title for the specified document.
virtual CString GetNormalDocumentTitle(CDocument* pDocument);
Parameters
pDocument
[in] A pointer to a CDocument
.
Return Value
The normal title for the specified document.
Remarks
The normal title of a document is usually the file name of the document without the path. This is the title in the File name field of the Save As dialog box.
CDataRecoveryHandler::GetRecoveredDocumentTitle
Creates and returns the title for the recovered document.
virtual CString GetRecoveredDocumentTitle(const CString& strDocumentTitle) const;
Parameters
strDocumentTitle
[in] The normal title for the document.
Return Value
The recovered document title.
Remarks
By default, the recovered title of a document is the normal title with [recovered] appended to it. The recovered title is displayed to the user when the CDataRecoveryHandler
queries the user to restore autosaved documents.
CDataRecoveryHandler::GetRestartIdentifier
Retrieves the unique restart identifier for the application.
virtual CString GetRestartIdentifier() const;
Return Value
The unique restart identifier.
Remarks
The restart identifier is unique for each execution of the application.
The CDataRecoveryHandler
stores information in the registry about the currently open documents. When the restart manager exits an application and restarts it, it supplies the restart identifier to the CDataRecoveryHandler
. The CDataRecoveryHandler
uses the restart identifier to retrieve the list of previously open documents. This enables the CDataRecoveryHandler
to try to find and restore autosaved files.
CDataRecoveryHandler::GetSaveDocumentInfoOnIdle
Indicates whether the CDataRecoveryHandler
performs an autosave on the current idle loop.
virtual BOOL GetSaveDocumentInfoOnIdle() const;
Return Value
TRUE indicates the CDataRecoveryHandler
autosaves on the current idle loop; FALSE indicates it does not.
CDataRecoveryHandler::GetShutdownByRestartManager
Indicates whether the restart manager caused the application to exit.
virtual BOOL GetShutdownByRestartManager() const;
Return Value
TRUE indicates the restart manager caused the application to exit; FALSE indicates it did not.
CDataRecoveryHandler::Initialize
Initializes the CDataRecoveryHandler
.
virtual BOOL Initialize();
Return Value
TRUE if the initialization is successful; otherwise FALSE.
Remarks
The initialization process loads the path for storing autosave files from the registry. If the Initialize
method cannot find this directory or if the path is NULL, Initialize
fails and returns FALSE
.
Use CDataRecoveryHandler::SetAutosavePath to change the autosave path after your application initializes the CDataRecoveryHandler
.
The Initialize
method also starts a timer to monitor when the next autosave occurs. Use CDataRecoveryHandler::SetAutosaveInterval to change the autosave interval after your application initializes the CDataRecoveryHandler
.
CDataRecoveryHandler::QueryRestoreAutosavedDocuments
Displays a dialog box to the user for each document that the CDataRecoveryHandler
autosaved. The dialog box determines whether the user wants to restore the autosaved document.
virtual void QueryRestoreAutosavedDocuments();
Remarks
If your application is Unicode, this method displays a CTaskDialog to the user. Otherwise, the framework uses AfxMessageBox to query the user.
After QueryRestoreAutosavedDocuments
gathers all the responses from the user, it stores the information in the member variable m_mapDocNameToRestoreBool. This method does not restore the autosaved documents.
CDataRecoveryHandler::ReadOpenDocumentList
Loads the open document list from the registry.
virtual BOOL ReadOpenDocumentList();
Return Value
TRUE indicates that ReadOpenDocumentList
loaded the information for at least one document from the registry; FALSE indicates no document information was loaded.
Remarks
This function loads the open document information from the registry and stores it in the member variable m_mapDocNameToAutosaveName.
After ReadOpenDocumentList
loads all the data, it deletes the document information from the registry.
CDataRecoveryHandler::RemoveDocumentInfo
Removes the supplied document from the open document list.
virtual BOOL RemoveDocumentInfo(CDocument* pDocument);
Parameters
pDocument
[in] A pointer to the document to remove.
Return Value
TRUE if pDocument was removed from the list; FALSE if an error occurred.
Remarks
When the user closes a document, the framework uses this method to remove it from the list of open documents.
If RemoveDocumentInfo
cannot find pDocument in the list of open documents, it does nothing and returns TRUE.
To use this method, AFX_RESTART_MANAGER_REOPEN_PREVIOUS_FILES must be set in m_dwRestartManagerSupportFlags.
CDataRecoveryHandler::ReopenPreviousDocuments
Opens the previously open documents.
virtual BOOL ReopenPreviousDocuments();
Return Value
TRUE if at least one document was opened; otherwise FALSE.
Remarks
This method opens the most recent save of the previously open documents. If a document was not saved or autosaved, ReopenPreviousDocuments
opens a blank document based on the template for that file type.
To use this method, AFX_RESTART_MANAGER_REOPEN_PREVIOUS_FILES must be set in m_dwRestartManagerSupportFlags. If this parameter is not set, ReopenPreviousDocuments
does nothing and returns FALSE.
If there are no documents stored in the list of previously open documents, ReopenPreviousDocuments
does nothing and returns FALSE.
CDataRecoveryHandler::RestoreAutosavedDocuments
Restores the autosaved documents based on user input.
virtual BOOL RestoreAutosavedDocuments();
Return Value
TRUE if this method successfully restores the documents.
Remarks
This method calls CDataRecoveryHandler::QueryRestoreAutosavedDocuments to determine which documents the user wants to restore. If a user decides not to restore an autosaved document, RestoreAutosavedDocuments
deletes the autosave file. Otherwise, RestoreAutosavedDocuments
replaces the open document with the autosaved version.
To use this method, either AFX_RESTART_MANAGER_REOPEN_PREVIOUS_FILES or AFX_RESTART_MANAGER_RESTORE_AUTOSAVED_FILES must be set in m_dwRestartManagerSupportFlags
.
CDataRecoveryHandler::SaveOpenDocumentList
Saves the current list of open documents to the Windows registry.
virtual BOOL SaveOpenDocumentList();
Return Value
TRUE if there are no open documents to save or if they were saved successfully. FALSE if there are documents to save to the registry, but they were not saved because an error occurred.
Remarks
The restart manager calls SaveOpenDocumentList
when the application exits unexpectedly or when it exits for an upgrade. When the application restarts, it uses CDataRecoveryHandler::ReadOpenDocumentList to retrieve the list of open documents.
This method saves only the list of open documents. The method CDataRecoveryHandler::AutosaveDocumentInfo is responsible for saving the documents themselves.
CDataRecoveryHandler::SetAutosaveInterval
Sets the time between autosave cycles in milliseconds.
Virtual void SetAutosaveInterval(int nAutosaveInterval);
Parameters
nAutosaveInterval
[in] The new autosave interval in milliseconds.
CDataRecoveryHandler::SetAutosavePath
Sets the directory where autosaved files are stored.
virtual void SetAutosavePath(const CString& strAutosavePath);
Parameters
strAutosavePath
[in] The path where autosave files are stored.
Remarks
Changing the autosave directory does not move currently autosaved files.
CDataRecoveryHandler::SetRestartIdentifier
Sets the unique restart identifier for this instance of the CDataRecoveryHandler
.
virtual void SetRestartIdentifier(const CString& strRestartIdentifier);
Parameters
strRestartIdentifier
[in] The unique identifier for the restart manager.
Remarks
The restart manager records information about the open documents in the registry. This information is stored with the unique restart identifier as the key. Because the restart identifier is unique for each instance of an application, multiple instances of an application may exit unexpectedly and the restart manager can recover each of them.
CDataRecoveryHandler::SetSaveDocumentInfoOnIdle
Sets whether the CDataRecoveryHandler
saves the open document information to the Windows registry during the current idle cycle.
virtual void SetSaveDocumentInfoOnIdle(BOOL bSaveOnIdle);
Parameters
bSaveOnIdle
[in] TRUE to save document information during the current idle cycle; FALSE to not perform a save.
CDataRecoveryHandler::SetShutdownByRestartManager
Sets whether the previous exit of the application was caused by the restart manager.
virtual void SetShutdownByRestartManager(BOOL bShutdownByRestartManager);
Parameters
bShutdownByRestartManager
[in] TRUE to indicate that the restart manager caused the application to exit; FALSE to indicate that the application exited for another reason.
Remarks
The framework behaves differently based on whether the previous exit was unexpected or whether it was initiated by the restart manager.
CDataRecoveryHandler::UpdateDocumentInfo
Updates the information for a document because the user saved it.
virtual BOOL UpdateDocumentInfo(CDocument* pDocument);
Parameters
pDocument
[in] A pointer to the saved document.
Return Value
TRUE if this method deleted the autosaved document and updated the document information; FALSE if an error occurred.
Remarks
When a user saves a document, the application removes the autosaved file because it is no longer needed. UpdateDocumentInfo
deletes the autosaved file by calling CDataRecoveryHandler::RemoveDocumentInfo. UpdateDocumentInfo
then adds the information from pDocument to the list of currently open documents because RemoveDocumentInfo
deletes that information, but the saved document is still open.
To use this method, AFX_RESTART_MANAGER_REOPEN_PREVIOUS_FILES must be set in m_dwRestartManagerSupportFlags.
See also
Classes
Hierarchy Chart
CObject Class
How to: Add Restart Manager Support
Σχόλια
https://aka.ms/ContentUserFeedback.
Σύντομα διαθέσιμα: Καθ' όλη τη διάρκεια του 2024 θα καταργήσουμε σταδιακά τα ζητήματα GitHub ως μηχανισμό ανάδρασης για το περιεχόμενο και θα το αντικαταστήσουμε με ένα νέο σύστημα ανάδρασης. Για περισσότερες πληροφορίες, ανατρέξτε στο θέμα:Υποβολή και προβολή σχολίων για