VIX API Concepts : Callback Functions

Callback Functions

All asynchronous Vix functions, such as VixVM_Open(), include a parameter for a callback procedure and a parameter that is passed to the callback procedure. These parameters are optional, so a caller can pass NULL for either. The prototype of this callback procedure parameter is:

typedef void (VixEventProc)(VixHandle handle,
                            VixEventType eventType,
                            VixHandle moreEventInfo,
                            void *clientData);

Using a Callback Function

If the caller provides a callback procedure, that procedure is registered with the job object and is invoked when the job object is signaled. For example, if a caller passes a callback procedure to VixVM_Open(), that callback procedure is invoked when the virtual machine has been opened. This situation could happen either before or after VixVM_Open() returns. It also can happen on any thread.

This mechanism allows the Vix function to complete asynchronously, so the application should not call VixJob_Wait() when using a callback function.

When a callback procedure is invoked, it is passed the clientData parameter that was passed in the original call to the asynchronous function. This allows a callback procedure to associate some context with an outstanding asynchronous call.

1. Example 2-14.

void myCallback(VixHandle jobHandle,
                VixEventType eventType,
                VixHandle moreEventInfo,
                void *clientData)
{
   VixError err;
   VixError asyncErr;
   VixHandle vmHandle = VIX_INVALID_HANDLE;
 
   /*
    * Ignore progress callbacks. Check only for final signal.
    */
   if (VIX_EVENTTYPE_JOB_COMPLETED != eventType) {
      return;
   }
    
   err = Vix_GetProperties(jobHandle,
                           VIX_PROPERTY_JOB_RESULT_HANDLE,
                           &vmHandle,
                           VIX_PROPERTY_JOB_RESULT_ERROR_CODE,
                           &asyncErr,
                           VIX_PROPERTY_NONE);
    
   if (VIX_OK != asyncErr) {
      /*
       * The open failed.
       */
   }
}
  
int main()
{
   VixError err = VIX_OK;
   VixHandle hostHandle = VIX_INVALID_HANDLE;
   VixHandle jobHandle = VIX_INVALID_HANDLE;
   VixHandle vmHandle = VIX_INVALID_HANDLE;
   char *contextData = "Hello, Vix";
 
   jobHandle = VixHost_Connect(VIX_API_VERSION,
                               VIX_SERVICEPROVIDER_VMWARE_VI_SERVER,
                               "https://server2.example.com/sdk", // hostName
                               0, // hostPort
                               "root", // username
                               "secretpw", // password
                               0, // options
                               VIX_INVALID_HANDLE, // propertyListHandle
                               NULL, // callbackProc
                               NULL); // clientData
 
   // Block for host connection to complete.
   err = VixJob_Wait(jobHandle, 
                     VIX_PROPERTY_JOB_RESULT_HANDLE,
                     &hostHandle,
                     VIX_PROPERTY_NONE);
   Vix_ReleaseHandle(jobHandle);
   jobHandle = VIX_INVALID_HANDLE;
   if (VIX_OK != err) {
      goto abort;
   }
 
   // Use callback function to capture completion of virtual machine open.
   jobHandle = VixVM_Open(hostHandle,
                          "[standard] WindowsXP/WindowsXP.vmx",
                          myCallback,
                          contextData);
   /*
    * Do something, like pump a message pump. 
    * Later, myCallback will be invoked on another thread.
    */ 
    
abort:
   Vix_ReleaseHandle(jobHandle);
   jobHandle = VIX_INVALID_HANDLE;
}

Callback Events

Note that a callback might be called several times, for several different reasons. For example, it might be called for periodic progress updates. The eventType parameter indicates why the callback is being called. The supported event types are:

•  VIX_EVENTTYPE_JOB_COMPLETED -- This event indicates that the asynchronous action has completed, whether successfully or not.
•  VIX_EVENTTYPE_JOB_PROGRESS -- This event may be passed several times to report progress on an asynchronous action.
•  VIX_EVENTTYPE_FIND_ITEM -- This event is used by VixHost_FindItems().
•  VIX_EVENTTYPE_HOST_INITIALIZED -- This event is used by VixHost_Connect().