# Name

VixHost_FindItems

# Description

    VixHandle
    VixHost_FindItems(VixHandle hostHandle,
                      VixFindItemType searchType,
                      VixHandle searchCriteria,
                      int32 timeout,
                      VixEventProc *callbackProc,
                      void *clientData);

This function asynchronously finds Vix objects and calls the application's callback function to report each object found. For example, when used to find all running virtual machines, VixHost_FindItems() returns a series of virtual machine file path names.

# Parameters

hostHandle
  The host handle returned by VixHost_Connect().
searchType
  The type of items to find. Values are listed in the Types Reference under VixFindItemType.
searchCriteria
  Must be VIX_INVALID_HANDLE.
timeout
  Must be -1.
callbackProc
  A function to be invoked when VixHost_FindItems() completes.
clientData
  A user-supplied parameter to be passed to the callback function.

# Return Value

VixHandle. A job handle that describes the state of this asynchronous call.

# Remarks

- When an object is found, VixHost_FindItems() passes the value VIX_EVENTTYPE_FIND_ITEM in the eventType parameter.
- When an object is found, VixHost_FindItems() passes a property list object containing the location of the object found. The property list is passed as the value of the moreEventInfo parameter. The property list contains a single string value (VIX_PROPERTY_FOUND_ITEM_LOCATION), which is the URL of the item found. For Server 2.0, ESX and vSphere, this value includes the datacenter.
- When VixHost_FindItems() is done searching, it calls the callback function a final time and passes VIX_EVENTTYPE_CALLBACK_SIGNALLED as the event type.

# Side Effects

None.

# Requirements

vix.h, since VMware Server 1.0.

# Example

The following example prints the path name of every virtual machine currently running on the host.

    static VixHandle hostHandle = VIX_INVALID_HANDLE;

    void VixDiscoveryProc(VixHandle jobHandle,
                          VixEventType eventType,
                          VixHandle moreEventInfo,
                          void *clientData)
    {
       VixError err = VIX_OK;
       char *url = NULL;

       // Check callback event; ignore progress reports.
       if (VIX_EVENTTYPE_FIND_ITEM != eventType) {
          return;
       }

       // Found a virtual machine.
       err = Vix_GetProperties(moreEventInfo,
                               VIX_PROPERTY_FOUND_ITEM_LOCATION,
                               &url,
                               VIX_PROPERTY_NONE);
       if (VIX_OK != err) {
          // Handle the error...
          goto abort;
       }

       printf("\nFound virtual machine: %s", url);

    abort:
       Vix_FreeBuffer(url);
    }

    int main()
    {
       VixHandle jobHandle = VIX_INVALID_HANDLE;
       VixHandle hostHandle = VIX_INVALID_HANDLE;
       VixError err;
       jobHandle = VixHost_Connect(VIX_API_VERSION,
                                   VIX_SERVICEPROVIDER_VMWARE_WORKSTATION,
                                   NULL, // hostName
                                   0, // hostPort
                                   NULL, // userName
                                   NULL, // password,
                                   0, // options
                                   VIX_INVALID_HANDLE, // propertyListHandle
                                   NULL, // callbackProc
                                   NULL); // clientData
       err = VixJob_Wait(jobHandle,
                         VIX_PROPERTY_JOB_RESULT_HANDLE,
                         &hostHandle,
                         VIX_PROPERTY_NONE);
       if (VIX_FAILED(err)) {
          // Handle the error...
          goto abort;
       }

       Vix_ReleaseHandle(jobHandle);

       printf("\nLooking for running virtual machines");

       jobHandle = VixHost_FindItems(hostHandle,
                                     VIX_FIND_RUNNING_VMS,
                                     VIX_INVALID_HANDLE, // searchCriteria
                                     -1, // timeout
                                     VixDiscoveryProc,
                                     NULL);
       err = VixJob_Wait(jobHandle, VIX_PROPERTY_NONE);
       if (VIX_FAILED(err)) {
          // Handle the error...
          goto abort;
       }
    abort:
       Vix_ReleaseHandle(jobHandle);
       VixHost_Disconnect(hostHandle);
    }

Copyright (C) 2007-2018 VMware, Inc. All rights reserved.