VMware Virtual Disk Development Kit Blog

For someone not too familiar with Windows volumes and devices, vixMntapi is not the easiest API to use. I will try and walk through a few basic steps here - hopefully it will clarify a few things:

The motivation behind VixMntapi is simple, you have a virtual disk, and you want to know which files are inside this disk. You may want to take a backup, check for virus, whatever.

So, at the bare minimum, you want to provide VixMntapi a virtual disk and you get a drive letter corresponding to that disk - somewhat like pushing a USB stick into your computer.

OK, that may lead you to expect something like VixMntapi_Mount(diskname) which returns say a drive letter. However, things are not that simple because a disk can have multiple partitions (and volumes) and a volume can span multiple disks.

To handle such cases, VixMntapi has a concept of a diskset which is just a collection of disks. This is a way to associate many disks (all backing the same volume for example). You call VixMntapi_OpenDisks, providing a number of disks and you will get back a handle that represents the diskset.

As part of opening diskset, VixMntapi walks through the partition tables of all the disks and collects all the volumes (including logical). VixMntapi can also look at the LDM disk database and figure out the details of dynamic volumes if any.

You can get details of these volumes by calling VixMntapi_GetVolumeHandles and querying for volume information on each of these handles using VixMntapi_GetVolumeInformation (Don't forget to call the corresponding free functions.)

So far, the procedure did not involve any operating system component. This is possible because VixMntapi has code to parse the partition details as well as the LDM databases. In other words, these 'volume objects' of VixMntapi are strictly known only to the VixMntapi and not to the OS.

But just having volume information is not that useful, you want to read files from this volume. And for this you need to mount the volume - or somehow make these volumes known to ths OS. To do this, you call VixMntapi_MountVolume. VixMntapi then creates a Windows device object representing this volume. To do this, VixMntapi needs the services of a kernel mode driver (which is part of VDDK and is installed when you install VDDK).  This is roughly the equivalent to plugging in a USB stick into your computer. A new volume appears.

From now on, various Windows storage stack components come into play, finally resulting in a volume that is exposed to user mode programs. If this volume is formatted with a file system, the file system driver will take ownership of the volume, if not the volume is simply a raw stream of bytes.

Since there are only a limited number of drive letters, VixMntapi does not map the volume to a drive letter. Instead, it gives the volume device object a name that can be accessed from the application. This is what you see as symbolic link in the Volume Information structure. (As the name shows, this is not the real volume name but an alias - the details are not that important).

Once you extract the symbolic link, you can for example use a function like DefineDosDevice to map the volume to a drive letter. Or you can simply use CreateFile to start reading from the volume. The following snippet is mounting a system volume and reading the file boot.ini in the root directory.

....
VixMntapi_MountVolume(volHandle, TRUE);
VixMntapi_GetVolumeInfo(volHandle, &volInfo);
string filePath = volInfo->symbolicLink + "boot.ini";
handle = CreateFile(filePath.c_str(), ....);
ReadFile(handle, ...)
....