Introduction to the Volume Shadow Copy Service API in C++

• Download simplesnapshot - 5 MB

Introduction

The Volume Shadow Copy Service aka VSS provides the backup infrastructure for the Microsoft Windows operating system, as well as a mechanism for creating consistent point-in-time copies of data known as shadow copies. VSS was introduced in Windows XP SP2 and is available on Windows Server 2003, Vista, Windows Server 2008, Windows 7, and Windows Server 2008 R2.

The Volume Shadow Copy Service can produce consistent manual or automatic backup copies or snapshots of data, even if it has a lock by coordinating with applications, file-system services, backup applications, fast-recovery solutions, and storage hardware. Several features in the Windows OS make use the Volume Shadow Copy Service. Beginning with Vista, some components like the property sheet shell extension called Previous Versions allows restoring individual files or folders locally from the restore point, as they existed at the time of the snapshot, thus retrieving an earlier version of a file or recovering a file deleted by mistake.

What you will find in this article is how to create a basic snapshot using the VSS API in native C++. The MSDN documentation is very good but also a little bit confusing to say the least this is why I get the idea to write this article hoping it will expose the VSS API in a more friendly way. <o:p>

VSS Vocabulary

Before we write some code we have to identify the different components that make a solution:<o:p>

• VSS service

<o:p>

This component is the part of Windows that ensures the other components can communicate with each other properly and work together.<o:p>

• VSS requester

<o:p>

This is what this article will focus on. It is a just the set of instruction that creates, imports or deletes the shadow copies. A typical example is a backup application like NTBackup. Under vista or Win 7 and Win 2008, the Windows Server Backup utility and the System Center Data Protection Manager application are VSS requesters. This first installment will focus on the basics of VSS requesters. <o:p>

• VSS writer

<o:p>

A VSS writer is a software component that guarantees that we have a consistent data set to back up by receiving freeze and thaw notifications to ensure that backup copies of their data files are internally consistent. SQL Server® or Exchange Server users are familiar with VSS writers as this two applications come with their own writer. Windows also include some VSS writers for various components like the registry for example. You would create your own VSS writer for your application if you want to guarantee data consistency during back up. The part 2 of this article will address VSS writers.<o:p>

• VSS provider

<o:p>

This component creates and maintains the shadow copies. This can occur in the software or in the hardware. The Windows operating system includes a VSS provider that uses copy-on-write. If you use a storage area network (SAN), it is important that you install the VSS hardware provider for the SAN, if one is provided. A hardware provider offloads the task of creating and maintaining a shadow copy from the host operating system. I will refer to the VSS provider through this article but to know more about it, visit the MSDN page.

How does it operate?

Now that we know what a requester, a writer and a provider are, how about putting their roles into context and show how they interact with each other to create a snapshot?

Regardless of the specific purpose for the copy and the application making use of VSS, shadow copy creation follows the same steps:<o:p>

1. The requester asks the Volume Shadow Copy Service to enumerate the writers, gather the writer metadata, and prepare for shadow copy creation.
2. Each writer creates an XML description of the components and data stores that need to be backed up and provides it to the Volume Shadow Copy Service. The writer also defines a restore method, which is used for all components. The Volume Shadow Copy Service provides the writer's description to the requester, which selects the components that will be backed up. This part will be covered in the part 2.
3. The Volume Shadow Copy Service notifies all the writers to prepare their data for making a shadow copy.
4. Each writer prepares the data as appropriate, such as completing all open transactions, rolling transaction logs, and flushing caches. When the data is ready to be shadow-copied, the writer notifies the Volume Shadow Copy Service.
5. The writers temporarily freeze application write I/O requests for the few seconds that are required to create the shadow copy of the volume or volumes. Note that during that period, the read I/O requests are still possible. The application freeze is not allowed to take longer than 60 seconds. The Volume Shadow Copy Service flushes the file system buffers and then freezes the file system, which ensures that the file system metadata is recorded correctly and the data to be shadow-copied is written in a consistent order.
6. The shadow copy is then created by the provider. This operation lasts no more than 10 seconds, during which all write I/O requests to the file system remain frozen.
7. The VSS Service releases file system write I/O requests and tells the writers to thaw application write I/O requests.

<o:p>

<o:p>

<o:p>

<o:p>

<o:p>

<o:p>

<o:p>

<o:p>

<o:p>

<o:p>

Writing some code

Now it’s time to dig in the API. I assume that you are aware of my development environment. VSS is available in the Microsoft Windows SDK. If you are using Windows Server 2003 and Windows XP then you must use the Volume Shadow Copy Service 7.2 SDK. There is a limitation in Windows XP; the snapshot created is not persistent. For this article the code have been compiled using Visual C++ 2010 and the windows SDK 7.1 and tested under windows Vista and windows 7. One more thing to know is that all VSS applications (requesters, providers, and writers) must run as native 32-bit or 64-bit applications. Running them under WOW64 is not supported.

The VSS API assumes knowledge of COM (intermediate).<o:p>

The interface for a home-brew requester: IVssBackupComponents

Whether you want to run a backup a restore or get some information about snapshots you will have to implement a requester. All requesters use the interface IVssBackupComponent. An application uses an instance of this interface to poll writer poll writers about file status and to run backup or restore operations. Applications obtain an instance of the IVssBackupComponents interface by calling CreateVssBackupComponents.

 // Create the IVssBackupComponents Interface
IVssBackupComponents *pVssBackup = NULL;
HRESULT hr = CreateVssBackupComponents(&pVssBackup);
if (result = S_OK) {. . .
... 

Creating a snapshot

Any shadow copy creation will always require the methods IVssBackupComponents::InitializeForBackup and IVssBackupComponents::StartSnapshotSet.

// sets the context for subsequent shadow copy-related operations.
HRESULT result = pVssBackup->InitializeForBackup(); 
if (result == S_OK){
                    . . 
}. 

Even though there are different types of shadow copy a requester can create, most backup applications, would call the following methods:

1. Call IVssBackupComponents::SetContext

with a context of VSS_CTX_BACKUP.

 // sets the context for subsequent shadow copy-related operations.
HRESULT result = pVssBackup->SetContext(VSS_CTX_BACKUP | VSS_CTX_CLIENT_ACCESSIBLE_WRITERS                                        | VSS_CTX_APP_ROLLBACK);
if (result == S_OK) {. . . 

// sets the context for subsequent shadow copy-related operations.
<pre>IVssAsync *pAsync = NULL;
HRESULT result = pVssBackup->GatherWriterMetadata(&pAsync);
if (result == S_OK) 
{ 
}
// Free all resources allocated during the call to GatherWriterMetadata
pVssBackup->FreeWriterMetadata();
//  

3. IVssBackupComponents::StartSnapshotSet to initialize the shadow copy mechanism.

VSS_ID snapshotSetID;
HRESULT result = pVssBackup->StartSnapshotSet(); 
if (result == S_OK) {. . . 

The VSS_ID definition specifies the general VSS identifier format. It is a standard GUID data type and used to identify shadow copies, shadow copy sets, providers, provider versions, writers.

TCHAR szVolumeName[MAX_PATH]; // DO NOT FORGET TO INITIALIZE IT!!!
HRESULT result = pVssBackup->AddToSnapshotSet(szVolumeName , GUID_NULL, &snapshotSetID); 
if (result == S_OK) {. . .  

The first parameters can be the name of the volume or the UNC path of the remote file share to be shadow copied. It must be in one of the following formats and must include a trailing backslash (\):

• The path of a mounted folder, for example, Y:\MountX\
• A drive letter, for example, D:\
• A volume GUID path of the form \\?\Volume{GUID}\ (where GUID identifies the volume)
• A UNC path that specifies a remote file share, for example, \\Clusterx\Share1\

5. Call IVssBackupComponents::PrepareForBackup to notify writers of backup operations.

IVssAsync *pAsync = NULL; 
HRESULT result = pVssBackup->PrepareForBackup(&pAsync); 
if (result == S_OK) {. . . 

The demo project attached to this article creates contains the code that creates a snapshot.

Working with snapshots

Windows XP and later include a command line utility called vssadmin that can be used to manipulate shadow copies. This utility requires administrator privileges.

The command vssadmin list shadows /for=c:\ will return the list of all the shadow copies on the drive C:\

On vista and Vista and higher, these copies can be mounted in Window explorer by typing the command:

mklink /d c:\mount_shadow_copy \\?\GLOBALROOT\Device\HarddiskVolumeShadowCopyX\ . X is any number return by the previous command

You want to mount a shadow copy programmatically? Well the function CreateSymbolicLink is your answer. An example is commented out in the code that comes with this article. Note that this function is only available on Vista and Win7 and Win 2k8.

Coming up

This concludes the first part of the VSS series. I’ll be back with another article on advanced requester and VSS Writers. Till then happy coding.