The VixMntapi Library

The VixMntapi library supports guest operating systems on multiple platforms. On POSIX systems it requires FUSE mount, available on recent Linux systems, and freely available on the SourceForge Web site.

Definitions are contained in the following header file, installed in the same directory as vixDiskLib.h:

#include "vixMntapi.h"

Types and Structures

This section summarizes the important types and structures.

Operating System Information

The VixOsInfo structure encapsulates the following information:

■	Family of the guest operating system, VixOsFamily, one of the following:

■	Windows (NT-based)

■

Linux

■

Netware

■

Solaris

■

FreeBSD

■

OS/2

■	Mac OS X (Darwin)

■	Major version and minor version of the operating system

■	Whether it is 64-bit or 32-bit

■	Vendor and edition of the operating system

■	Location where the operating system is installed

Disk Volume Information

The VixVolumeInfo structure encapsulates the following information:

■	Type of the volume, VixVolumeType, one of the following:

■	Basic partition.

■	GPT – GUID Partition Table. However, VixMntapi does not support GPT partitions.

■	Dynamic volume, including Logical Disk Manager (LDM).

■	LVM – Logical Volume Manager disk storage.

■	Whether the guest volume is mounted on the proxy.

■	Path to the volume mount point on the proxy, or NULL if the volume is not mounted.

■	On Windows, numGuestMountPoints is the number of times a basic volume is mapped to a drive letter, or 0 if the volume is not mounted. IDE and boot disk come first. Unimplemented on Linux.

■	Mount points for the volume in the guest.

Function Calls

To obtain these functions, load the vixMntapi library separately from the vixDiskLib library. On Windows, compile with the vixMntapi.lib library so your program can load the vixMntapi.dll runtime.

These calls can be used to mount and read Windows virtual disks on Windows hosts (with at least one NTFS volume) or Linux virtual disks on Linux hosts. Cross-mounting is restricted, though it is possible to mount a virtual disk with a mix of formats, if the mounted partition was formatted with Windows.

Important You should run only one vixMntapi program at a time on a virtual machine, to avoid conflict between registry hives. See Multithreading Considerations for advice on worker threads.

The remainder of this section lists the available function calls in the vixMntapi library. Under parameters, [in] indicates input parameters, and [out] indicates output parameters. All functions that return vixError return VIX_OK on success, otherwise a suitable VIX error code.

VixMntapi_Init()

Initializes the library. Similar to VixDiskLib_InitEx – see Initialize Virtual Disk API.

VixError

VixMntapi_Init(uint32 majorVersion,

uint32 minorVersion,

VixDiskLibGenericLogFunc *log,

VixDiskLibGenericLogFunc *warn,

VixDiskLibGenericLogFunc *panic,

const char *libDir,

const char *configFile);

Parameters:

■	majorVersion [in] VixMntapi major version number, currently must be 1 (one).

■	minorVersion [in] VixMntapi minor version number, currently must be 0 (zero).

■	log [in] Callback function to write log messages.

■	warn [in] Callback function to write warning messages.

■	panic [in] Callback function to report fatal errors.

■	libDir [in] and configFile [in] as for VixDiskLib_InitEx(), allowing you to tmpDirectory.

VixMntapi_Exit()

Cleans up the VixMntapi library.

void VixMntapi_Exit();

VixMntapi_OpenDiskSet()

Opens the set of disks for mounting on a Windows or Linux virtual machine. All the disks for a dynamic volume or Logical Disk Manager (LDM) must be opened together.

VixError

VixMntapi_OpenDiskSet(VixDiskLibHandle diskHandles[],

int numberOfDisks,

uint32 openMode,

VixDiskSetHandle *diskSet);

The VixDiskLibHandle type, defined in vixDiskLib.h, is the same as for the diskHandle parameter in the VixDiskLib_Open() function, but here it is an array instead of a single value.

Parameters:

■	diskHandles [in] Array of handles to open disks.

■	numberOfDisks [in] Number of disk handles in the array.

■	openMode [in] Must be 0 (zero).

■	diskSet [out] Disk set handle to be filled in.

If you want to mount from a Windows system, first call VixDiskLib_Open() for every disk, then use the returned disk handle array to call VixMntapi_OpenDiskSet(), which returns a disk set handle.

If you want to mount from a Linux system, call the function VixMntapi_OpenDisks(), which opens and creates the disk set handle, all in one function.

VixMntapi_OpenDisks()

Opens disks for mounting on a Windows or Linux virtual machine. On Linux, the Logical Volume Manager (LVM) is not supported.

VixError

VixMntapi_OpenDisks(VixDiskLibConnection connection,

const char *diskNames[],

size_t numberOfDisks,

uint32 openFlags,

VixDiskSetHandle *handle);

Parameters:

■	connection [in] The VixDiskLibConnection to use for opening the disks. Calls VixDiskLib_Open() with the specified flags for each disk to open.

■	diskNames [in] Array of disk names to open.

■	numberOfDisks [in] Number of disk handles in the array. Must be 1 for Linux.

■	flags [in] Flags to open the disk.

■	handle [out] Disk set handle to be filled in.

VixMntapi_GetDiskSetInfo()

Retrieves information about the disk set.

VixError

VixMntapi_GetDiskSetInfo(VixDiskSetHandle handle,

VixDiskSetInfo **diskSetInfo);

Parameters:

■	handle [in] Handle to an open disk set.

■	diskSetInfo [out] Disk set information to be filled in.

VixMntapi_FreeDiskSetInfo()

Frees memory allocated by VixMntapi_GetDiskSetInfo().

void VixMntapi_FreeDiskSetInfo(VixDiskSetInfo *diskSetInfo);

Parameter:

■	diskSetInfo [in] OS info to be freed.

VixMntapi_CloseDiskSet()

Closes the disk set.

VixError

VixMntapi_CloseDiskSet(VixDiskSetHandle diskSet);

Parameter:

■	diskSet [in] Handle to an open disk set.

VixMntapi_GetVolumeHandles()

Retrieves handles to volumes in the disk set. The third parameter VixVolumeHandle can be a volume handle or an array of volume handles. If you pass an array this function returns the volume handle for the first volume only. If you pass a pointer (such as VixVolumeHandle *volumeHandles) it returns all the volume handles.

VixError

VixMntapi_GetVolumeHandles(VixDiskSetHandle diskSet,

int *numberOfVolumes,

VixVolumeHandle **volumeHandles);

Parameters:

■	diskSet [in] Handle to an open disk set.

■	numberOfVolumes [out] Number of volume handles.

■	volumeHandles [out] Volume handles to be filled in.

VixMntapi_FreeVolumeHandles()

Frees memory allocated by VixMntapi_GetVolumeHandles().

void VixMntapi_FreeVolumeHandles(VixVolumeHandle *volumeHandles);

Parameter:

■	volumeHandles [in] Volume handle to be freed.

VixMntapi_GetOsInfo()

Retrieves information about the default operating system in the disk set.

To get operating system information, VixMntapi_GetOsInfo() requires the system and boot volumes to be already mounted. It does not dismount the system volume at the end of this function. Your application should be prepared to handle the “volume already mounted” error gracefully.

This function is effective only when used with operating systems of the same type. For instance, a VixMntapi program running on Windows can provide information about the VMDK of a Windows virtual machine, but not about the VMDK of a Linux virtual machine.

VixError

VixMntapi_GetOsInfo(VixDiskSetHandle diskSet,

VixOsInfo **info);

Parameters:

■	diskSet [in] Handle to an open disk set.

■	info [out] OS information to be filled in.

VixMntapi_FreeOsInfo()

Frees memory allocated by VixMntapi_GetOsInfo().

void VixMntapi_FreeOsInfo(VixOsInfo* info);

Parameter:

■	info [in] OS info to be freed.

VixMntapi_MountVolume()

Mounts the volume. After mounting the volume, use VixMntapi_GetVolumeInfo() to obtain the path to the mounted volume. This mount call locks the source disks until you call VixMntapi_DismountVolume(). The VixMntapi_MountVolume() function cannot mount Linux swap or extended partitions.

VixError

VixMntapi_MountVolume(VixVolumeHandle volumeHandle,

Bool isReadOnly);

Parameters:

■	volumeHandle [in] Handle to a volume.

■	isReadOnly [in] Whether to mount the volume in read-only mode. Does not override openMode.

VixMntapi_DismountVolume()

Unmounts the volume.

VixError

VixMntapi_DismountVolume(VixVolumeHandle volumeHandle,

Bool force);

Parameters:

■	volumeHandle [in] Handle to a volume.

■	force [in] Force unmount even if files are open on the volume.

VixMntapi_GetVolumeInfo()

Retrieves information about a disk volume. Some information, such as the number of mount points, requires you to set the open read-only flag. Some information is available only if a volume was previously mounted by VixMntapi_MountVolume(). The Windows registry returns volume information only for mounted disks. On Windows the VixMntapi_GetVolumeInfo() call returns a symbolic link from the VixVolumeInfo structure in the form \\.\vstor2-mntapi10-shared-<longhexnum>\. You can transform this symbolic link into a target path by replacing \\. with \Device and deleting the final backslash, then map a drive letter with DefineDosDevice(DDD_RAW_TARGET_PATH,...) and proceed as if you have a local drive. Alternatively on Windows, you can open a volume with CreateFile() and traverse the file system with FindFirstFile().

VixError

VixMntapi_GetVolumeInfo(VixVolumeHandle volumeHandle,

VixVolumeInfo **info);

Parameters:

■	volumeHandle [in] Handle to a volume.

■	info [out] Volume information to be filled in.

VixMntapi_FreeVolumeInfo()

Frees memory allocated in VixMntapi_GetVolumeInfo().

void VixMntapi_FreeVolumeInfo(VixVolumeInfo *info);

Parameter:

■	info [in] Volume info to be freed.