MFC Restart Manager Support in VS2010

Visual CPP Team

Hi, I am Weidong Huang, a Software Design Engineer in Test in the Visual C++ group.  Today I am going to talk about MFC’s support of Restart Manager functionality — a very amazing feature in VS2010.

 

What is Restart Manager?

Restart Manager is a new feature introduced by Microsoft’s Windows Vista operating system.  It can help applications maintain their data when an update needs to shutdown the application or when an unexpected software error or crash occurs. Instead of shutting down abnormally, Restart Manager enables an application to perform an application save before it is terminated. Furthermore, it can re-invoke the application enabling it to restore its state from before the shutdown or crash. 

 

What Restart Manager support can you get from MFC in VS2010?

·         For new MFC applications, you can get the application restart and recovery feature for free by using the MFC Application Wizard.

·         All configurable parts of the restart manager API are exposed to the user through overridable virtual members.

·         To upgrade an existing application to get the default restart manager support, you only need to add a single line of code.

·         An auto-save mechanism is added to the application that performs the saving of open documents to temporary files in user-definable intervals. If an application crashes due to an exception, the application will be restarted restoring the last backup.

·         A restore on restart UI prompts the end user to recover auto-saved versions if available.

 

How to enable Restart Manager in VS2010?

The MFC Restart Manager in VS2010 includes two levels of supports:

·         Restart Support

o   Restart the application after upgrade or crash

Note: This applies to all types of MFC applications

·         Application Recover Support:

o   Reopen the previously opened document

o   Recover the auto saved document

                Note: This only applies to Doc/View type MFC applications and needs restart support.

 

Enabling restart manager support steps are different between new application and existing application:

 

For new application, you only need 2 steps:

1.       Use MFC Application Wizard to Create a new MFC Application;

2.       In Advance Features page, select Support Restart Manager (see following). 

 

 

 

There are 3 options for selection:

a.       Select “Support Restart Manager” only

This option will enable your application with restart support only.  In other words, the application will be restarted after upgrade shutdown or crash but no attempt will be made to reopen documents or recover documents.

b.      Select “Support Restart Manager” and “Reopen previously open documents”

Besides the functionality described in a), this option enables your application to reopen previous open documents but no attempt to recover an auto-saved version of the document is made.

c.       Select “Support Restart Manager” , “Reopen previously open documents” and “Support application recovery”

Besides the functionality described in a) and b), restart manager will try to recover the documents with an auto-save version.  It will prompt with a TaskDialog (Unicode) or MessageBox(Non Unicode) and ask user whether to recover the documents.  If user chooses “Yes”, the auto-save documents will be opened and used as current documents. If user choose “No”, the last user saved documents will be opened and the auto-save changes will be discarded.

 

Note: 

1.       To select b), you need to select a), and to select c), you need to select b). 

2.       For Dialog type Application, b and c will be disabled automatically.

 

For existing application, you only need add only one line of code in App Class constructor, the code could be: (these 3 lines of code perform the same functionalities as above a, b and c respectively)

a.       m_dwRestartManagerSupportFlags = AFX_RESTART_MANAGER_SUPPORT_RESTART;

b.      m_dwRestartManagerSupportFlags =

AFX_RESTART_MANAGER_SUPPORT_RESTART_ASPECTS;

c.       m_dwRestartManagerSupportFlags = AFX_RESTART_MANAGER_SUPPORT_ALL_ASPECTS;

 

Example:

CMyApp::CMyApp()

{

                m_dwRestartManagerSupportFlags = AFX_RESTART_MANAGER_SUPPORT_RESTART;

 

//other initialize codes

}

 

Tips to use Restart Manager in VS2010

1.       Use CDataRecoveryHandler::SetAutoSaveInterval to adjust the auto save interval for your special needs.  The default value is 5 minutes.  You can get default CDataRecoveryHandler by calling “AfxGetApp()->GetDataRecoveryHandler()”.

2.       Although the default implementation of Restart Manager will be enough for most users, you may want to implement a different data recovery strategy for your application.  In this case, overload CWinApp::GetDataRecoveryHandler() and attach your own DataRecoveryHandler derived from CDataRecoveryHandler.  Since this is not a common user scenario, I am not covering the usage of this functionality today. For information on how to implement your own DataRecoveryHandler, please refer to the MSDN document which will be published with VS2010. 

3.       To test your application’s restart and recovery capabilities, you can embed crash code to simulate the crash scenario and use “RmStartSession “, “RmRegisterResources” and “RmShutdown” and “RmRestart” Windows APIs to simulate windows upgrade scenario.

Example code of using “Rm*” APIs:

#include “windows.h”

#include “RestartManager.h”

int wmain(int argc, WCHAR* argv[])

{

        DWORD dwSessionHandle = 0;

        WCHAR wszSessionKey[CCH_RM_SESSION_KEY+1];

        LPCWSTR pwzResourcesToRestart[] = {argv[1]};

        if (RmStartSession(&dwSessionHandle, 0, wszSessionKey) == ERROR_SUCCESS)

        {

                        if (RmRegisterResources(dwSessionHandle, 1, pwzResourcesToRestart, 0, NULL, 0, NULL) == ERROR_SUCCESS)

                        {

                                        if (RmShutdown(dwSessionHandle, RmShutdownOnlyRegistered, NULL) == ERROR_SUCCESS)

                                        {

                                                        if (RmRestart(dwSessionHandle, 0, NULL) == ERROR_SUCCESS)

                                                        {

                                                                        return 0;

                                                        }

                                        }

                        }

        }

}

 

Hope you like the feature. Let me know if you have any comments on this blog.

 

Thanks
Weidong Huang
Visual C++ Library QA Team

Posted in C++

0 comments

Discussion is closed.

Feedback usabilla icon