How to use the System Restore API to save and to restore system data in Visual C++ .NET or in Visual C++ 2005 (315530)

SUMMARY

The System Restore application programming interface (API) allows you to save system state information, to change the state, and to roll back to a previously held consistent state.

This article demonstrates how to use the System Restore API from Visual C++. In this article, you build an application that creates a restore point, that installs a dummy application, and then that finalizes the restore point. You also see how to view existing Restore Points and how to roll back using the System Restore user interface.

System state information includes the following:

• Current configuration
• Registry information
• Installed applications
• Devices
• Critical operating system files

System state information does not include user files such as documents, spreadsheets, and so on.

You can use the System Restore API to record the current state of the operating system and the installed applications. If any subsequent changes (for example, installed applications or devices) cause instability in the system, you can revert to the last stable state. You can also use the System Restore API as part of the installation process of applications that you develop; you can undo any changes that you made if the system becomes unstable after the installation.

The System Restore API monitors selected files on a drive-by-drive basis and makes copies of these files before it changes the files during a system update. A driver in the Microsoft Windows XP operating system intercepts the operations that are performed on files. The copies of files are compressed to save space. Each set of saved files is referred to as a Restore Point. You can use the System Restore user interface to revert the system back to the state that is determined by any Restore Point that you have captured on the computer.

System Restore monitors files that have a recognized file name extension, such as .exe, .dll, and .ini, are described in the following file: back to the top

Requirements

The following list outlines the recommended hardware, software, network infrastructure, and service packs that are required:

• Microsoft Windows XP Home Edition or Microsoft Windows XP Professional
• Microsoft Visual Studio .NET or Microsoft Visual Studio 2005
• Microsoft Platform SDK

This article assumes that you are familiar with Visual C++ programming.

back to the top

Create a Test Application

1. Start Visual Studio .NET or Visual Studio 2005.
2. On the File menu, point to New, and then click Project.
3. In the New Project dialog box, click Visual C++ Projectsunder Project Types, and then click Win32 Project under Templates.
   
   Note In Visual Studio 2005, click Visual C++ under Project Types.
4. In the Name text box, type Install, and then click OK.
5. In the Win32 Application Wizard, click Application Settings.
6. Under Application type, click Console Application, and then click Finish to create the application.
7. In Solution Explorer, right-click the Install project, and then click Properties.
8. In the Install.cpp Property Pages dialog box, click Configuration Properties, click Linker, click Input, add Srclient.lib to the list of additional dependencies, and then click OK.
   
   Note In Visual Studio 2005, the name of the dialog box is Install Property Pages.

back to the top

Create a Restore Point

1. Add the following #include directives to the end of stdafx.h:

   #include <windows.h>
   #include <srrestoreptapi.h>
   					

2. In the _tmain function in Install.cpp, create the two variables shown in the following code:

   RESTOREPOINTINFO RstPt;
   STATEMGRSTATUS MgrStat; 
   					

3. Add the following statements that populate the RstPt variable with information that indicates that an application is about to be installed:

   RstPt.dwEventType = BEGIN_SYSTEM_CHANGE;
   RstPt.dwRestorePtType = APPLICATION_INSTALL;
   strcpy(RstPt.szDescription, "Demonstration Restore Point");
   					

4. Create a Restore Point to mark the beginning of the installation using the SRSetRestorePoint function. In the event of a failure, report the reason for the failure and exit:

   if (!SRSetRestorePoint(&RstPt, &MgrStat))
   {
       printf("Unable to set restore point. Error %ld\n",
           MgrStat.nStatus);
       return 1;
   }
   					

5. Display the sequence number for the newly created Restore Point:

   printf("Restore point created. Sequence %ld\n", 
       MgrStat.llSequenceNumber);
   					

back to the top

Install an Application

1. Add the following statements that simulate some of the operations that are performed when an application is installed. The application creates a subdirectory called A New Application and adds three files to this subdirectory. The file extensions used (.exe, .dll, and .ini) are all examples of monitored extensions.

                  // Begin application installation code
   	
   CreateDirectory("C:\\A New Application", NULL);
   CreateFile("C:\\A New Application\\Application File.exe",
       GENERIC_READ, 0, NULL, CREATE_ALWAYS, 0, NULL);
   CreateFile("C:\\A New Application\\Application File.dll",
       GENERIC_READ, 0, NULL, CREATE_ALWAYS, 0, NULL);
   CreateFile("C:\\A New Application\\Application File.ini",
       GENERIC_READ, 0, NULL, CREATE_ALWAYS, 0, NULL);
   
                  // End application installation code
   					

back to the top

Complete the Restore Point

1. Populate the Restore Point structure with the data that you need to indicate that the installation has completed and that the Restore Point should be saved and recorded. The sequence number used should be the same sequence number that was returned when the Restore Point was created:

   RstPt.dwEventType = END_SYSTEM_CHANGE;
   RstPt.llSequenceNumber = MgrStat.llSequenceNumber;
   					

2. Call SRSetRestorePoint again to complete the Restore Point. If an error occurs, delete the application files, and remove the Restore Point using the SRRemoveRestorePoint function:

   if (!SRSetRestorePoint(&RstPt, &MgrStat))
   {
       printf("Unable to set end of restore point. Error %ld\n",
           MgrStat.nStatus);
   
       // Delete application files and remove restore point
       DeleteFile("C:\\A New Application\\Application File.exe");
       DeleteFile("C:\\A New Application\\Application File.dll");
       DeleteFile("C:\\A New Application\\Application File.ini");
       RemoveDirectory("C:\\A New Application");
       SRRemoveRestorePoint((DWORD)MgrStat.llSequenceNumber);
       printf("Restore point removed\n");
       return 1;
   }
   printf("Restore point completed\n");
   return 0;
   					

back to the top

Verify the Restore Point

1. Build and run the Install application. If the installation is successful, the following messages appear in the Console window (the sequence number may vary):

   Restore Point created. Sequence 24
   Restore Point completed
   					

2. Using Windows Explorer, navigate to the root directory of the C drive. Find a new folder that is named A New Application. This folder contains three files called Application_File.exe, Application_File.dll, and Application_File.ini.

back to the top

View the Restore Point

1. Execute the System Restore user interface application, Rstrui.exe, that is located in the following directory:

      %windir%\system32\Restore
   						

2. In the Welcome to System Restore dialog box, verify that the Restore my computer to an earlier time radio button is selected, and then click Next.
3. In the Select a Restore Point dialog box, you see a Restore Point that is labeled Demonstration Restore Point in the list. This is the Restore Point that you created during the Install application. Any other Restore Points for the current day, if you have installed other applications or executed Install more than once, are listed also. You can click dates on the calendar to see the Restore Points for other days.

back to the top

Rollback the Application Installation

1. Verify that the Demonstration Restore Point is selected, and then click Next.
2. In the Confirm Restore Point Selection dialog box, click Next.
   Visual C++ closes all applications that are running. You can see the System Restore window while the system settings are restored and the application is uninstalled. The computer shuts down and restarts.
3. When Windows XP has restarted, log in. In the Restoration Complete dialog box, click OK.
4. Use Windows Explorer to view the root directory of the C drive. The directory A New Application is now visible.

back to the top