VMWARE VIX API and SDK

Versions

Currently the installations I use of VMWare vCenter Server are version 5.1.x which is requires we use the following SDK version:

VIX Version	Products	Path
1.12	vSphere 5.1, Workstation 9, Fusion 5, Player 5, or earlier	Workstation-9.0.0-and-vSphere-5.1.0

If or when we upgrade to v5.5.x we will be looking at the following:

VIX Version	Products	Path
1.13	vSphere 5.5, Workstation 10, Fusion 6, Player 6, or earlier	Workstation-10.0.0-and-vSphere-5.5.0

Setting Up Development Environment

Since we are systems people we shouldn't be adverse to getting down and dirty with C when needed, but the goal of my work will be to build a light Ruby wrapper around the C code to allow people in TechOps that are less comfortable with with common systems engineering practices (i.e. writing sane C code) to write glue for their automation much easier AND be able to write automated unit, functional, and integration tests which they really ought to. This is the main reason to use Ruby which it's mature set of testing libraries readily available over shell scripts or the Perl bindings available (the benefit isn't subjective "beauty" of code like some may taut as it's value add, that is a bogus argument).

However, this is a walk through of how I am setting up my development environment for building the Ruby/C extension and providing links to appropriate API references from VMWare so people can follow along very easily.

You actually need to create an account on VMWare to download the VIX SDK for Linux x86_64. OMGUGHBBQ: https://my.vmware.com/group/vmware/details?downloadGroup=VIXAPI112&productId=353
Then you have to trust it is legit by sudo sh-ing it: sudo sh VMware-VIX-1.12.0-812388.x86_64.bundle
Now follow the instructions...

Note: Don't worry I will download the bundle and put it somewhere within Jive and update this doc when it's available

For sample programs in C check out: /usr/share/doc/vmware-vix/VMwareVix/samples/

To uninstall it you can run:

sudo vmware-installer -u vmware-vix

Now it's as simple as adding the include and lib paths to your compiler and linker settings and adding #include "vix.h" when using the APIs.

Next, a whirl wind tour of the API.

VIX API Whirlwind

Basic Concepts

There are five core "things" the API exposes, the rest are auxiliary types:

Virtual Machine (this can be in on or off state)
Job
Event
Snapshot
Host

These should be self explanatory.

Handles

Handles are reference counted. This is pretty common practice in C APIs. This should not be weird, just clean up after yourself with:

void Vix_ReleaseHandle(VixHandle handle);

For example,

VixHandle handle1;

// other code here necessary to setup arguments to pass in...
handle1 = MyOpenVMWrapper(...ALL_THE_ARGS...);

// Now you can perform various operations on handle1

// Now you are done with handle1 so...
Vix_ReleaseHandle(handle1);
handle1 = VIX_INVALID_HANDLE;

You always need to open and release handles when you need to reference an entity from VMWare via the API, e.g. Virtual Machine, Job, Snapshot, Host, etc.

Error Codes in VIX

Don't bother doing your won bit masking, it's error prone and much more likely to be subject to change in different versions of the API. Instead use the VIX defines:

VIX_ERROR_CODE(err)
VIX_SUCCEEDED(err)
VIX_FAILED(err)

So many APIs return error values which can then be passed into the above defines so you can add your required logic, e.g.:

VixError err;
VixHandle handle1;
int vmPowerState;
char *vmPathName;

handle1 = MyOpenVMWrapper(...ARGS...);

err = Vix_GetProperties(handle1, VIX_PROPERTY_VM_VMX_PATHNAME, &vmPathName, VIX_PROPERTY_VM_POWER_STATE, &vmPowerState, VIX_PROPERTY_NONE);

if (VIX_E_... == VIX_ERROR_CODE(err)) {
  // handle this case however you want
}


// Alternatively you might just care if it succeeded or not:
if (VIX_SUCCEEDED(err)) {
  // handle success case here
}

// Or you might only care about a failure case before proceeding
if (VIX_FAILED(err)) {
  // output to stderr with more information if possible
  exit(1);
}

Thread Safety

While VMware claims Vix objects are thread safe, always double check your assumptions. Never trust a vendor. I know this all to well, especially in C/C++ and Java APIs. :)

mbbx6spp/VMWARE_VIX_API.md