CDataRecoveryHandler 类
如果应用程序意外退出，则 CDataRecoveryHandler 自动保存并还原文档。
语法
class CDataRecoveryHandler : public CObject
成员
构造函数
| 名称 | 描述 |
|---|---|
| CDataRecoveryHandler::CDataRecoveryHandler | 构造 CDataRecoveryHandler 对象。 |
方法
数据成员
| 名称 | 描述 |
|---|---|
| m_bRestoringPreviousOpenDocs | 指示数据恢复处理程序是否重新打开以前打开的文档。 |
| m_bSaveDocumentInfoOnIdle | 指示数据恢复处理程序是否在下一个空闲循环中自动保存文档。 |
| m_bShutdownByRestartManager | 指示重启管理是否导致应用程序退出。 |
| m_dwRestartManagerSupportFlags | 指示重启管理器为应用程序提供什么支持的标志。 |
| m_lstAutosavesToDelete | 关闭原始文档时未删除的自动保存文件的列表。 当应用程序退出时，重启管理器会重试删除文件。 |
| m_mapDocNameToAutosaveName | 文档名到自动保存的文件名的映射。 |
| m_mapDocNameToDocumentPtr | 文档名到 CDocument 指针的映射。 |
| m_mapDocNameToRestoreBool | 文档名到布尔参数的映射，该参数指示是否还原自动保存的文档。 |
| m_mapDocumentPtrToDocName | CDocument 指针到文档名的映射。 |
| m_mapDocumentPtrToDocTitle | CDocument 指针到文档标题的映射。 这些标题用于保存文件。 |
| m_nAutosaveInterval | 自动保存的时间间隔（毫秒）。 |
| m_nTimerID | 自动保存计时器的标识符。 |
| m_strAutosavePath | 存储自动保存文档的位置。 |
| m_strRestartIdentifier | 重启管理器 GUID 的字符串表示形式。 |
注解
重启管理器使用 CDataRecoveryHandler 类保持跟踪所有打开的文档，并在必要时自动保存它们。 若要启用自动保存，请使用 CDataRecoveryHandler::SetSaveDocumentInfoOnIdle 方法。 此方法指示 CDataRecoveryHandler 在下一个空闲循环中执行自动保存。 当 CDataRecoveryHandler 应该执行自动保存时，重启管理器调用 SetSaveDocumentInfoOnIdle。
CDataRecoveryHandler 类的所有方法都是虚拟的。 替代此类中的方法以创建你自己的自定义数据恢复处理程序。 除非创建你自己的数据恢复处理程序或者重启管理器，否则不要实例化 CDataRecoveryHandler。 CWinApp 类根据需求创建 CDataRecoveryHandler 对象。
必须先调用 CDataRecoveryHandler::Initialize，然后才可使用 CDataRecoveryHandler 对象。
因为 CDataRecoveryHandler 类与重启管理器密切相关，所以 CDataRecoveryHandler 依赖于全局参数 m_dwRestartManagerSupportFlags。 该参数决定了重启管理器拥有的权限及其与应用程序的交互方式。 要将重启管理器合并到现有应用程序中，必须在主应用程序的构造函数中为 m_dwRestartManagerSupportFlags 分配适当的值。 有关如何使用重启管理器的详细信息，请参阅如何：添加重启管理器支持。
要求
标头：afxdatarecovery.h
CDataRecoveryHandler::AutosaveAllDocumentInfo
自动保存使用 CDataRecoveryHandler 类注册的每个文件。
virtual BOOL AutosaveAllDocumentInfo();
返回值
如果 CDataRecoveryHandler 保存了所有文档，则返回 TRUE；如果没有保存任何文档，则返回 FALSE。
备注
如果没有必须保存的文档，此方法返回 TRUE。 如果检索应用程序的 CWinApp 或 CDocManager 生成错误，它也会返回 TRUE 而不保存任何文档。
若要使用此方法，必须在 m_dwRestartManagerSupportFlags 中设置 AFX_RESTART_MANAGER_AUTOSAVE_AT_RESTART 或 AFX_RESTART_MANAGER_AUTOSAVE_AT_INTERVAL。 有关详细信息，请参阅如何：添加重启管理器支持。
CDataRecoveryHandler::AutosaveDocumentInfo
自动保存指定的文档。
virtual BOOL AutosaveDocumentInfo(
CDocument* pDocument,
BOOL bResetModifiedFlag = TRUE);
参数
pDocument
[in] 指向要保存的 CDocument 的指针。
bResetModifiedFlag
[in] TRUE 指示 CDataRecoveryHandler 认为 pDocument 已修改；FALSE 指示框架认为 pDocument 未修改。 有关此标志的效果的详细信息，请参见注解部分。
返回值
如果设置了适当的标志并且 pDocument 是有效的 CDocument 对象，则返回 TRUE。
备注
每个 CDocument 对象都有一个标志，指示其自上次保存后是否发生了更改。 使用 CDocument::IsModified 确定此标志的状态。 如果自上次保存后 CDocument 未更改，则 AutosaveDocumentInfo 会删除该文档的所有自动保存文件。 如果自上次保存后文档已更改，则关闭它会提示用户在关闭之前保存文档。
注意
使用 bResetModifiedFlag 将文档的状态更改为未修改可能会导致用户丢失未保存的数据。 如果框架认为文档未修改，则关闭它不会提示用户保存。
如果 pDocument 不是有效的 CDocument 对象，此方法会引发 ASSERT 宏异常。
要使用此方法，必须在 m_dwRestartManagerSupportFlags 中设置 AFX_RESTART_MANAGER_AUTOSAVE_AT_RESTART 或 AFX_RESTARTMANAGER_AUTOSAVE_AT_INTERVAL。
CDataRecoveryHandler::CDataRecoveryHandler
构造 CDataRecoveryHandler 对象。
CDataRecoveryHandler(
DWORD dwRestartManagerSupportFlags,
int nAutosaveInterval);
参数
dwRestartManagerSupportFlags
[in] 指示支持哪些重启管理器选项。
nAutosaveInterval
[in] 自动保存的时间间隔。 此参数以毫秒为单位。
备注
当使用“新建项目”向导时，MFC 框架为应用程序自动创建 CDataRecoveryHandler 对象。 除非要自定义数据恢复行为或重启管理器，否则不应创建 CDataRecoveryHandler 对象。
CDataRecoveryHandler::CreateDocumentInfo
将文档添加到打开的文档列表。
virtual BOOL CreateDocumentInfo(CDocument* pDocument);
参数
pDocument
[in] 指向 CDocument 的指针。 此方法为 CDocument 创建文档信息。
返回值
默认实现返回 TRUE。
注解
此方法在添加文档之前检查 pDocument 是否已在文档列表中。 如果 pDocument 已在列表中，此方法将删除与 pDocument 关联的自动保存文件。
要使用此方法，必须在 m_dwRestartManagerSupportFlags 中设置 AFX_RESTART_MANAGER_AUTOSAVE_AT_RESTART 或 AFX_RESTARTMANAGER_AUTOSAVE_AT_INTERVAL。
CDataRecoveryHandler::DeleteAllAutosavedFiles
删除所有当前自动保存的文件。
virtual BOOL DeleteAllAutosavedFiles();
返回值
默认实现始终返回 TRUE。
CDataRecoveryHandler::DeleteAutosavedFile
删除指定的自动保存文件。
virtual BOOL DeleteAutosavedFile(const CString& strAutosavedFile);
参数
strAutosavedFile
[in] 包含自动保存文件名的字符串。
返回值
默认实现始终返回 TRUE。
备注
如果此方法无法删除自动保存的文件，则会在列表中保存该文件的名称。 CDataRecoveryHandler 的析构函数尝试删除该列表中指定的每个自动保存文件。
CDataRecoveryHandler::GenerateAutosaveFileName
为与提供的文档文件名关联的自动保存文件生成名称。
virtual CString GenerateAutosaveFileName(const CString& strDocumentName) const;
参数
strDocumentName
[in] 包含文档名的字符串。 GenerateAutosaveFileName 使用此文档名生成相应的自动保存文件名。
返回值
从 strDocumentName 生成的自动保存文件名。
备注
每个文档名都存在与自动保存文件名的一对一映射。
CDataRecoveryHandler::GetAutosaveInterval
返回尝试自动保存的时间间隔。
virtual int GetAutosaveInterval() const;
返回值
尝试自动保存间隔的毫秒数。
CDataRecoveryHandler::GetAutosavePath
返回自动保存文件的路径。
virtual CString GetAutosavePath() const;
返回值
存储自动保存文档的位置。
CDataRecoveryHandler::GetDocumentListName
从 CDocument 对象中检索文档名。
virtual CString GetDocumentListName(CDocument* pDocument) const;
参数
pDocument
[in] 指向 CDocument 的指针。 GetDocumentListName 从此 CDocument 中检索文档名。
返回值
pDocument 中的文档名。
备注
CDataRecoveryHandler 使用文档名作为 m_mapDocNameToAutosaveName、m_mapDocNameToDocumentPtr 和 m_mapDocNameToRestoreBool 中的键。 这些参数使 CDataRecoveryHandler 能够监控 CDocument 对象、自动保存文件名和自动保存设置。
CDataRecoveryHandler::GetNormalDocumentTitle
检索指定文档的普通标题。
virtual CString GetNormalDocumentTitle(CDocument* pDocument);
参数
pDocument
[in] 指向 CDocument 的指针。
返回值
指定文档的普通标题。
备注
文档的普通标题通常是不带路径的文档文件名。 这是“另存为”对话框的“文件名”字段中的标题。
CDataRecoveryHandler::GetRecoveredDocumentTitle
创建并返回恢复的文档的标题。
virtual CString GetRecoveredDocumentTitle(const CString& strDocumentTitle) const;
参数
strDocumentTitle
[in] 文档的普通标题。
返回值
恢复的文档标题。
备注
默认情况下，文档的恢复标题是追加了 [已恢复] 的普通标题。 当 CDataRecoveryHandler 询问用户是否还原自动保存的文档时，系统会向用户显示恢复的标题。
CDataRecoveryHandler::GetRestartIdentifier
检索应用程序的唯一重启标识符。
virtual CString GetRestartIdentifier() const;
返回值
唯一重启标识符。
注解
重启标识符对于应用程序的每次执行都是唯一的。
CDataRecoveryHandler 将有关当前打开文档的信息存储在注册表中。 当重启管理器退出并重启应用程序时，它会将重启标识符提供给 CDataRecoveryHandler。 CDataRecoveryHandler 使用重启标识符来检索以前打开的文档的列表。 这使 CDataRecoveryHandler 能够尝试查找和还原自动保存的文件。
CDataRecoveryHandler::GetSaveDocumentInfoOnIdle
指示 CDataRecoveryHandler 是否对当前空闲循环执行自动保存。
virtual BOOL GetSaveDocumentInfoOnIdle() const;
返回值
TRUE 指示 CDataRecoveryHandler 对当前空闲循环执行自动保存；FALSE 指示不执行。
CDataRecoveryHandler::GetShutdownByRestartManager
指示重启管理器是否导致应用程序退出。
virtual BOOL GetShutdownByRestartManager() const;
返回值
TRUE 指示重启管理器导致应用程序退出；FALSE 指示没有导致退出。
CDataRecoveryHandler::Initialize
初始化 CDataRecoveryHandler。
virtual BOOL Initialize();
返回值
如果初始化成功，则返回 TRUE；否则返回 FALSE。
备注
初始化过程从注册表加载用于存储自动保存文件的路径。 如果 Initialize 方法找不到此目录或路径为 NULL，则 Initialize 失败并返回 FALSE。
在应用程序初始化 CDataRecoveryHandler 后，使用 CDataRecoveryHandler::SetAutosavePath 更改自动保存路径。
Initialize 方法还会启动一个计时器来监视下一次自动保存的时间。 在应用程序初始化 CDataRecoveryHandler 后，使用 CDataRecoveryHandler::SetAutosaveInterval 更改自动保存间隔。
CDataRecoveryHandler::QueryRestoreAutosavedDocuments
针对 CDataRecoveryHandler 自动保存的每个文档向用户显示一个对话框。 该对话框确定用户是否要还原自动保存的文档。
virtual void QueryRestoreAutosavedDocuments();
备注
如果应用程序是 Unicode，此方法会向用户显示一个 CTaskDialog。 否则，框架使用 AfxMessageBox 来查询用户。
QueryRestoreAutosavedDocuments 收集用户的所有响应后，将信息存储在成员变量 m_mapDocNameToRestoreBool中。 此方法不会还原自动保存的文档。
CDataRecoveryHandler::ReadOpenDocumentList
从注册表加载打开的文档列表。
virtual BOOL ReadOpenDocumentList();
返回值
TRUE 指示 ReadOpenDocumentList 从注册表加载了至少一个文档的信息；FALSE 指示没有加载文档信息。
备注
此函数从注册表加载打开的文档信息并将其存储在成员变量 m_mapDocNameToAutosaveName 中。
ReadOpenDocumentList 加载所有数据后，它会从注册表中删除文档信息。
CDataRecoveryHandler::RemoveDocumentInfo
从打开的文档列表删除提供的文档。
virtual BOOL RemoveDocumentInfo(CDocument* pDocument);
参数
pDocument
[in] 指向要删除的文档的指针。
返回值
如果从列表中删除了 pDocument，则返回 TRUE；如果发生了错误，则返回 FALSE。
注解
当用户关闭文档时，框架使用此方法将其从打开的文档列表中删除。
如果 RemoveDocumentInfo 在打开的文档列表中找不到 pDocument，则其不执行任何操作并返回 TRUE。
要使用此方法，必须在 m_dwRestartManagerSupportFlags 中设置 AFX_RESTART_MANAGER_REOPEN_PREVIOUS_FILES。
CDataRecoveryHandler::ReopenPreviousDocuments
打开以前打开的文档。
virtual BOOL ReopenPreviousDocuments();
返回值
如果至少打开了一个文档，则返回 TRUE；否则返回 FALSE。
备注
此方法打开最新保存的以前打开的文档。 如果未保存或未自动保存文档，ReopenPreviousDocuments 会根据该文件类型的模板打开一个空白文档。
要使用此方法，必须在 m_dwRestartManagerSupportFlags 中设置 AFX_RESTART_MANAGER_REOPEN_PREVIOUS_FILES。 如果未设置此参数，ReopenPreviousDocuments 不执行任何操作并返回 FALSE。
如果以前打开的文档列表中没有存储任何文档，则 ReopenPreviousDocuments 不执行任何操作并返回 FALSE。
CDataRecoveryHandler::RestoreAutosavedDocuments
基于用户输入还原自动保存的文档。
virtual BOOL RestoreAutosavedDocuments();
返回值
如果此方法成功还原文档，则返回 TRUE。
备注
此方法调用 CDataRecoveryHandler::QueryRestoreAutosavedDocuments 来确定用户要还原的文档。 如果用户决定不还原自动保存的文档，RestoreAutosavedDocuments 将删除自动保存文件。 否则，RestoreAutosavedDocuments 会将打开的文档替换为自动保存的版本。
要使用此方法，必须在 m_dwRestartManagerSupportFlags 中设置 AFX_RESTART_MANAGER_REOPEN_PREVIOUS_FILES 或 AFX_RESTART_MANAGER_RESTORE_AUTOSAVED_FILES。
CDataRecoveryHandler::SaveOpenDocumentList
将当前打开的文档列表保存到 Windows 注册表。
virtual BOOL SaveOpenDocumentList();
返回值
如果没有要保存的打开文档或它们已成功保存，则返回 TRUE。 如果有文档要保存到注册表，但由于发生错误而未保存，则返回 FALSE。
注解
当应用程序意外退出或退出以进行升级时，重启管理器会调用 SaveOpenDocumentList。 当应用程序重启时，它使用 CDataRecoveryHandler::ReadOpenDocumentList 来检索打开的文档列表。
此方法仅保存打开的文档列表。 CDataRecoveryHandler::AutosaveDocumentInfo 方法负责保存文档本身。
CDataRecoveryHandler::SetAutosaveInterval
设置自动保存周期的时间间隔（毫秒）。
Virtual void SetAutosaveInterval(int nAutosaveInterval);
参数
nAutosaveInterval
[in] 新的自动保存间隔（毫秒）。
CDataRecoveryHandler::SetAutosavePath
设置存储自动保存文件的目录。
virtual void SetAutosavePath(const CString& strAutosavePath);
参数
strAutosavePath
[in] 存储自动保存文件的路径。
备注
更改自动保存目录不会移动当前自动保存的文件。
CDataRecoveryHandler::SetRestartIdentifier
为此 CDataRecoveryHandler 实例设置唯一的重启标识符。
virtual void SetRestartIdentifier(const CString& strRestartIdentifier);
参数
strRestartIdentifier
[in] 重启管理器的唯一标识符。
注解
重启管理器在注册表中记录有关打开的文档的信息。 此信息以唯一的重启标识符作为键存储。 因为每个应用程序实例的重启标识符都是唯一的，所以一个应用程序的多个实例可能会意外退出，并且重启管理器可以恢复其中的每个实例。
CDataRecoveryHandler::SetSaveDocumentInfoOnIdle
设置在当前空闲周期内，CDataRecoveryHandler 是否将打开的文档信息保存到 Windows 注册表。
virtual void SetSaveDocumentInfoOnIdle(BOOL bSaveOnIdle);
参数
bSaveOnIdle
[in] 如果为 TRUE，则在当前空闲周期内保存文档信息；如果为 FALSE，则不执行保存。
CDataRecoveryHandler::SetShutdownByRestartManager
设置先前应用程序退出是否由重启管理器引起。
virtual void SetShutdownByRestartManager(BOOL bShutdownByRestartManager);
参数
bShutdownByRestartManager
[in] 如果为 TRUE，则指示重启管理器导致了应用程序退出；如果为 FALSE，则指示应用程序因其他原因退出。
备注
根据之前的退出是意外退出还是由重启管理器启动，框架的行为会有所不同。
CDataRecoveryHandler::UpdateDocumentInfo
更新文档的信息，因为用户保存了它。
virtual BOOL UpdateDocumentInfo(CDocument* pDocument);
参数
pDocument
[in] 指向已保存文档的指针。
返回值
如果此方法删除了自动保存的文档并更新了文档信息，则返回 TRUE；如果发生错误，则返回 FALSE。
注解
当用户保存文档时，应用程序会删除自动保存的文件，因为不再需要该文件。 UpdateDocumentInfo 通过调用 CDataRecoveryHandler::RemoveDocumentInfo 删除自动保存的文件。 然后，UpdateDocumentInfo 将 pDocument 中的信息添加到当前打开的文档列表中，因为 RemoveDocumentInfo 删除了该信息，但保存的文档仍处于打开状态。
要使用此方法，必须在 m_dwRestartManagerSupportFlags 中设置 AFX_RESTART_MANAGER_REOPEN_PREVIOUS_FILES。