VIX API Concepts : Handle Properties

Handle Properties

The Vix API defines a set of properties for each type of handle. A property is a typed name/value pair. A type name is a unique integer ID and the type may be one of the following:

• 32-bit Integer
• 64-bit Integer
• String
• Boolean
• Handle

Vix defines a different set of properties for each handle type. For example, a virtual machine handle has a string property that stores the file path name of the virtual machine, but a job handle does not. The complete set of handle properties for each type is defined in the VIX API Reference Guide.

If a property is defined for a particular handle type, all handles of that type always have some value for that property. For example, every virtual machine has a property that stores its file path name, whether the virtual machine is powered on or not, or whether it is stored on the local host or not.

Clients can modify handle properties only by invoking functions on the handle. For example, the function VixVM_PowerOn()modifies the VIX_PROPERTY_VM_IS_RUNNING of the virtual machine handle.

Properties are the main mechanism for reading both the persistent configuration state and the runtime status of handles. Properties allow Vix to be language independent and backward compatible.

GetProperties() Function

Vix provides one function that can get properties from any handle. This function has a varargs signature, which means you can use it to retrieve any number of properties by passing in sufficient parameters. The argument list must be terminated with a special property, VIX_PROPERTY_NONE.

VixError Vix_GetProperties(VixHandle handle, 
                           VixPropertyID firstPropertyID,
                           ...);

Here is an example of retrieving properties from a virtual machine handle:

1. Example 2-8.

VixError err;
VixHandle handle1;
int vmPowerState;
char *vmVmxPathName;
 
handle1 = MyOpenVMWrapper(...various parameters...);
 
err = Vix_GetProperties(handle1, 
                        VIX_PROPERTY_VM_VMX_PATHNAME,
                        &vmVmxPathName,
                        VIX_PROPERTY_VM_POWER_STATE,
                        &vmPowerState,
                        VIX_PROPERTY_NONE);

Property Lists

Vix defines a special runtime data structure, the property list, as a convenient way to store properties and pass them as arguments. Property lists are runtime-only data structures, and they behave as Vix objects. You can reference a property list with a handle and you can pass the handle to functions such as Vix_GetProperties().

Here is an example of a callback function that retrieves a value from a property list.

1. Example 2-9.

void MyFunction(VixHandle propertyListHandle)
{
   char *url = NULL;
 
   err = Vix_GetProperties(propertyListHandle, 
                           VIX_PROPERTY_VM_VMX_PATHNAME,
                           &url,
                           VIX_PROPERTY_NONE);
   if (VIX_OK != err) {
      // ...Handle the error...
   }
   // ... Use the url property, then release the buffer ...
   Vix_FreeBuffer(url);            
}