The Virtual Disk API, or VixDiskLib, is a set of function calls to manipulate virtual disk files in VMDK format (virtual machine disk). Function-call names and usages are patterned after C system calls for file I/O. The Virtual Disk API enables partners and software vendors to manage VMDK directly from their applications.
VixDiskLib includes a binary component delivered as a Windows user mode DLL, or a Linux shared object, both supporting a C/C++ API. The package is delivered as a ZIP file for Windows or a tar.gz file for Linux.
VixDiskLib duplicates functionality of the command-line utilities vmware-mount and vmware-vdiskmanager with the following additional capabilities:
For details about VixDiskLib, see the Virtual Disk Programming Guide on the VMware documentation Web site.
These library functions can manipulate virtual disks on most recent VMware platform products.
For a list of supported platform products and tested guest operating systems, see the VDDK Release Notes.
An example program is installed in the doc/sample subdirectory, including a Makefile for the GNU C compiler on Linux, and solution and project files for Visual Studio C++ on Windows.
At the top of your program, include "vixDiskLib.h" along with any other header files you need.
Call VixDiskLib_InitEx() to initialize the library in your application. This function takes major and minor version numbers to account for future extensions. You can provide your own logging, warning, or panic functions to substitute for the default VixDiskLib handlers. You can also change the library directory, and configure settings by passing a configFilePath.
Call VixDiskLib_Connect() to communicate with a VMware hosted product. To connect to the local host, specify null values in the connection parameters for virtual machine name, hostname, username, password, and port.
Call VixDiskLib_ConnectEx() to communicate with a VMware managed product such as ESXi. You must provide valid credentials for the ESXi host or vCenter Server to access virtual disk. This could include virtual machine name, hostname, username, password, and port. The VixDiskLib_ConnectEx() function also expects a readOnly boolean, an optional snapshotRef, and your preferred transportModes.
Call VixDiskLib_Open() to open the virtual disk of a guest virtual machine. Pass the connection handle obtained from VixDiskLib_Connect() or VixDiskLib_ConnectEx(). The VixDiskLib_Open() function also expects path-to-virtual-disk, option flags, and a parameter to pass back the resulting disk handle.
Structures and type definitions are declared in the "vixDiskLib.h" include file, so you do not need to create them or allocate memory for them. VixDiskLibConnection is initialized by a call to VixDiskLib_Connect() or VixDiskLib_ConnectEx(). VixDiskLibHandle is initialized by a call to VixDiskLib_Open(). VixDiskLibInfo is filled in by a call to VixDiskLib_GetInfo().
Before calling VixDiskLib_ConnectEx() to connect to a VMware host, you initialize the VixDiskLibConnectParams structure with the following information:
char *vmxSpec; // URL-like spec of the VM char *serverName; // Name or IP address vCenter or ESXi host VixDiskLibCredType credType; // For later expansion with Session ID char *userName; // User ID on vCenter or ESXi host char *password; // Password on vCenter or ESXi host char *thumbPrint; // SSL Certificate Thumb Print uint32 port;
Before calling VixDiskLib_Open() to open a virtual disk, you initialize the VixDiskLibCreateParams structure with the following information:
VixDiskLibDiskType diskType; // VMFS or not, monolithic or split, flat or sparse VixDiskLibAdapterType adapterType; // SCSI Buslogic, SCSI LSIlogic, or IDE uint16 hwVersion; // Virtual hardware version VixDiskLibSectorType capacity; // Capacity of virtual disk in sectors
Metatypes: formatted strings are used for VMX specification and transport mode. For example, the string "san:nbd:file" specifies preferred transport modes.
Functor prototypes: VixDiskLibGenericLogFunc() is a single function to log, warn, and panic. VixDiskLibProgressFunc() displays the progress of an operation. Both are defined in vixDiskLib.h and provided for use as callbacks.