Virtual Disk API Programming Guide - Documentation - VMware

Virtual Disk Programming Guide
VixError vixError = VixDiskLib_ConnectEx(&cnxParams, TRUE,
"snapshot-47", NULL, &connection);
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:
vmxSpec = "moid=23498";
vmxSpec = "moid=898273";
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.
Get Selected Transport Method
The VixDiskLib_GetTransportMode() function returns the transport method selected for diskHandle.
printf("Selected transport method: %s\n", VixDiskLib_GetTransportMode(diskHandle));
Prepare For Access and End Access
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.
vixError = VixDiskLib_PrepareForAccess(&cnxParams, "vmName");
The connection parameters must indicate one virtual machine only. When opening a managed disk, provide
valid credentials for the vCenter Server that manages the ESXi host with the disk. The second parameter is
currently just for tracking purposes, and could be the virtual machine name or the name of your application.
If you run VixDiskLib_PrepareForAccess() directly on an ESXi host, the system throws an error saying
“VDDK: HostAgent is not a VirtualCenter, cannot disable sVmotion.”
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.
vixError = VixDiskLib_EndAccess(&cnxParams, "vmName");
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 (appGlobals.vmxSpec != NULL) {
int i;
retry:
vixError = VixDiskLib_PrepareForAccess(&cnxParams, "VMname");
for (i = 0; i < 10; i++) {
if (vixError != VIX_OK) { // no specific error code for vMotion-in-progress
sleep(60);
goto retry;
}
}
}
38 VMware, Inc.