Replacing VixDiskLib_Init(),
VixDiskLib_InitEx() initializes new releases of the library, Parameters are similar, except you should specify an actual
libDir, and the new
configFile parameter. For multithreaded programming, you should write your own
logFunc, because the default logging function is not thread-safe. On Windows,
*libDir could be C
:\Program Files\VMware\VMware Virtual Disk Development Kit. On Linux,
*libDir is probably
/usr/lib/vmware-vix-disklib.
The currently supported entries in the configFile are listed below. The correct way to specify a configuration is
name=value. See
Example: Sample InitEx configuration file for a sample configuration file.
On Linux, log messages appear under /var/log by default. On Windows, they appear in a temporary folder, whose location can change from time to time. Early Windows systems used
C:\Windows\Temp. Windows XP and Server 2003 use
C:\Documents and Settings\<user>\Local Settings\Temp\vmware-<user>. Vista, Windows 7, and Server 2008 use
C:\Users\<user>AppData\Local\Temp\vmware-<user>.
On all versions of Windows the user’s TEMP environment setting overrides the default Temp folder location. Temporary is something of a misnomer because files are never deleted from the Temp folder, unless the user or an application deletes them. If the
TEMP or Windows default Temp folder is not found, VDDK (and other VMware software) have a fallback to
<localAppDir>\Temp.
The VixDiskLib_ListTransportModes() function returns the currently supported transport methods as a colon-separated string value, currently “
file:san:hotadd:nbd” where
nbd indicates LAN transport. When available, SSL encrypted NBD transport is shown as
nbdssl.
The default transport priority over the network is san:hotadd:nbdssl:nbd assuming all are available.
With SAN transport on Linux, read and write operations are performed in “direct” mode (O_DIRECT), meaning that no read or write buffering is done. Direct mode prevents other processes from accessing the latest data, and avoids loss of information if the process dies before committing its write buffers. In direct mode, the most time efficient performance can be achieved if applications follow these guidelines when performing reads and writes:
VixDiskLib_ConnectEx() connects the library to managed disk on a remote ESX/ESXi host or through VMware vCenter Server. For hosted disk on the local system, it works the same as
VixDiskLib_Connect().
VixDiskLib_ConnectEx() takes three additional parameters:
Even when a program calls VixDiskLib_ConnectEx() with NULL parameter to accept the default transport mode, SAN is selected as the preferred mode, if SAN storage is available from the ESX/ESXi host. Then if the program opens a virtual disk on local storage, subsequent writes will fail. In this case, the program should explicitly pass
nbd or
nbdssl as the preferred transport mode.
In the connection parameters cnxParams, the
vmxSpec managed object reference would be different on an ESX/ESXi host than on the vCenter Server:
The port should be the one on which vCenter Server listens for API queries. Specifying a null port allows the library to select the default communications port. It is likely to be 443 (HTTPS) or maybe 902 (VIX automation). This is the port for data copying, not the port for SOAP requests.
The VixDiskLib_GetTransportMode() function returns the transport method selected for
diskHandle.
The VixDiskLib_PrepareForAccess() function notifies a vCenter-managed host that a virtual machine’s disks are being opened, probably for backup, so the host should postpone virtual machine operations that might interfere with virtual disk access. Call this function before creating a snapshot on a virtual machine. Internally, this function disables the vSphere API method
RelocateVM_Task.
Every VixDiskLib_PrepareForAccess() call should have a matching
VixDiskLib_EndAccess() call.
The VixDiskLib_EndAccess() function notifies the host that a virtual machine’s disks have been closed, so operations that rely on the virtual disks to be closed, such as vMotion, can now be allowed. Call this function after closing all the virtual disks, and after deleting the virtual machine snapshot. Normally this function is called after previously calling
VixDiskLib_PrepareForAccess, but you can call it to clean up after a crash. Internally, this function re-enables the vSphere API method
RelocateVM_Task.
Here is a code snippet showing use of PrepareForAccess in a backup program that waits up to 10 minutes for Storage vMotion to finish. Regular vMotion would finish much faster than that.
If virtual machine state was not cleaned up correctly after connection shut down, VixDiskLib_Cleanup() removes extra state for each virtual machine. Its three parameters specify connection, and pass back the number of virtual machines cleaned up, and the number remaining to be cleaned up.