About the Virtual Disk API

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.

Features of VixDiskLib

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:

• It permits random read/write access to data anywhere in a VMDK file.
• It creates and manages redo logs (parent-child disk chaining, or delta links).
• It can read and write disk metadata.
• It is able to delete VMDK files programmatically.
• It supports advanced transports for greater efficiency on vSphere.

For details about VixDiskLib, see the Virtual Disk Programming Guide on the VMware documentation Web site.

Product Compatibility

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.

Programming with VixDiskLib

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().

Types and Metatypes

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.