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 deactivates 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 identity tracking purposes, and is limited to 50 characters. It 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 vCenter, cannot deactivate 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.

/* New sample code accounts for VMODL_TYPE_VIM_FAULT_METHOD_ALREADY_DISABLED_FAULT */
if (appGlobals.vmxSpec != NULL) {
     for (int i = 0; i < 10; i++) {
          vixError = VixDiskLib_PrepareForAccess(&cnxParams, "Sample");
          if (vixError == VIX_OK) {
              break;
          } else {
              Sleep(60000);
          }
     }
}