VMware Infrastructure (VI) SDK 2.5.0 Release Notes

Last updated:   8-Dec-2008


Known Issues

This release of the VI SDK has the following known issues:

API Issues

SearchIndex FindByDnsName Operation Is Case-Sensitive
Domain names should resolve to IP addresses in a case-insensitive manner. However, the FindByDnsName operation (of SearchIndex managed object is case sensitive and must match the name of the server identically, in terms of upper- and lower-case letters. This is a known issue and will be resolved in a future release. Also, if you search using the IP address rather than the FQDN (fully-qualified domain name) for the server, do not prefix single- or double-digit IP address fields with zeros (0). For example, enter the IP address as (not

VirtualDiskManager Managed Object Type Not Supported on VirtualCenter Server
VirtualCenter Server does not support the VirtualDiskManager managed object type. VirtualDiskManager is supported on ESX Server 3.5 systems. See the VI API ReferenceGuide for more information about the VirtualDiskManager managed object type.

CIM or SMASH Issues

The ESX Server 3i CIM Object Manager (CIMOM) or one of its sub-systems has several known issues, most of which are related to power operations (the implementation of the Power State Management Profile, documented by the DMTF in DSP1027). These include:

  • ESX Server 3i Systems With LSI And IPMI Controllers Report The Same Disk Drive Twice
    Internal hard-disk drives connected to an LSI controller are reported under VMware_DiskDrive. The same internal hard drives are reported by IMPI providers under OMC_DiskDrive. There is no workaround at this time.
  • Host Power Operations Not Supported for Hosts that are Nodes in a DRS (Distributed Resource Management) Cluster
    The CIM Provider (a subsystem of the CIMOM) does not correctly handle RequestPowerStateChange() operations when the HostSystem is part of a DRS cluster.
  • Host Power Operations Cannot Always Handle Suspending Virtual Machine
    When suspending a virtual machine prior to powering off a HostSystem, the virtual machine cannot respond to prompts.
  • VMware_PowerManagementService.RequestPowerStateChange() Starts Host in Maintenance Mode
    The VMware implementation of CIM_PowerManagementService.RequestPowerStateChange() currently always starts or restarts the host in maintenance mode. In addition, after a reboot, any virtual machines on the host that were running are in a suspended state.
  • Changes to Permissions (Add, Delete) Can Take Up to 20 Minutes to Propagate to CIM Client
    Adding or deleting permissions can take as long as 20 minutes (1200 seconds) to become visible to CIM clients via VICimProvider.

API Reference Guide and Other Documentation Known Issues

CPU Wait Time Counter Description Inaccurate in the API Reference
The PerformanceManager managed object type as described in the API Reference Guide is incorrect. The wait counter captures total time (in milliseconds) spent in any of the possible idle states—idle state, wait state, or halted state.

FileManager Documentation Inaccurate in the API Reference
The API ReferenceGuide provides documentation for using URLs with FileManager. However, FileManager does not support URLs at this time. Only datastore paths are supported:

Incomplete Descriptions of UUID Properties in the API Reference
The uuid properties of the HostSystemInfo, HostHardwareSummary, VirtualMachineConfigSummary, VmUuidAssignedEvent, VmUuidConflictEvent, and VmUuidChangedEvent data objects lack information for the UUID format. They use 128-bit SMBIOS UUID represented as a hexadecimal string in a 12345678-abcd-1234-cdef-123456789abc format. The same format is used for the bundleUuid and hostUuid properties of the MismatchedBundle fault.

Ambiguous Description of ResourceAllocationInfo Property in the API Reference
In the API Reference Guide, the description of the ResourceAllocationInfo data object shares property is ambiguous. The corrected description is "Optional. Relative allocation of resources that can be used to arbitrate resource contention. Shares are used to determine relative allocation between resource consumers."

Incorrect Description of FileManager Methods in the API Reference
The descriptions of CopyDatastoreFile_Task, DeleteDatastoreFile_Task, and MoveDatastoreFile_Task in the API Reference Guide state that these methods do not support recursive folder operations, which is not true for VI SDK 2.5. CopyDatastoreFile_Task supports recursive folder copy, DeleteDatastoreFile_Task supports recursive folder delete, and MoveDatastoreFile_Task supports recursive folder move.

Inaccurate Description of SearchDatastoreSubFolders_Task Return Value in the API Reference
In the API Reference Guide, the description of the ManagedObjectReference to a Task return value for the SearchDatastoreSubFolders_Task method is inaccurate. The corrected description is "This method returns a Task object with which to monitor the operation. The info.result property in the Task object contains the list of HostDatastoreBrowserSearchResults upon success."

Some SearchIndex Methods Do Not Return Templates
The FindByDnsName, FindByIp, and FindByUuid methods of the SearchIndex managed object type return actual virtual machines only, and do not return templates. The other SearchIndex methods, such as FindByDatastorePath, FindByInventoryPath, and FindChild, do work with templates. Be sure to include the template's complete filename extension (.vmtx) when using the FindByDatastorePath method.

RetrieveUserGroups Operation Issue
The RetrieveUserGroups operation (of UserDirectory managed object type) for ESX Server systems returns the list of users or groups that are specified in the /etc/passwd file of the server. If this file contains Sun NIS or NIS+ users and groups, these will be available through the API as well, along with local users configured on the server. If you don't want NIS (or NIS+) users to be available through the API, do not add them to the ESX (or ESXi) Server's configuration.

QueryEvents Operation Not Supported on ESX
The QueryEvents operation is not supported on ESX systems. The VI SDK 2.5 Programming Guide inaccurately implies that QueryEvents can be used with ESX. However, invoking this operation raises an error. For a possible workaround, use the CreateCollectorForEvents operation. See "Retrieving Historical Information" in VI SDK 2.5 Programming Guide for examples.

SDK Download File Contains Out-Of-Date and Erroneous Documentation
Included in the SDK download are several readme files and PDF documents that are obsolete or incorrect. These include:

  • The Installation Guide contained in the SDK package has been completely replaced by the “Developer’s Setup Guide,” available online only.
  • The readme files contained in the SDK package might contain links to defunct Web locations.
  • The Porting Guide contained in the SDK package is legacy documentation.

Current documentation is available from the VMware Infrastructure SDK home page:

Incorrect Descriptions of Java Samples in the Programming Guide
Several of the sample application descriptions in the Programming Guide (chapter 1, “What’s New in the VI SDK?“) are incorrect, due to code improvements after the RC (release candidate). For example, the functionality provided by the GetVersion class (GetVersion.java) is encompassed in a helper class (apputils.version.VersionUtil).

Sample Code Issues

Some Java Samples Do Not Work
The following sample applications throw errors, or do not work:
  ColdMigration (com.vmware.samples.httpfileaccess.ColdMigration.java)
  GetVMFiles (com.vmware.samples.httpfileaccess.GetVMFiles.java)
  HostPowerOps (com.vmware.samples.version.hostpowerops.HostPowerOps) – PowerDownHostToStandBy() times out and throws an error.

Misleading Parameter Information for VMClone.java Sample
In the Readme for VI SDK 2.5.0 Java Samples, the description of the vmpath parameter syntax in VMClone.java is misleading. The correct syntax uses a slash (/), and not a period (.), to separate the elements in the path, as in parent/child1/child2. Also, vmpath should include a vm string before the name of the virtual machine to be cloned.
For example:

WSDL Issue

ESX Server WSDL Differs from the WSDL Available in the VI SDK
Unlike the WSDL provided with the SDK, the ESX Server (hostd) WSDL does not define the UnexpectedFault fault type. However, this fault is not thrown by any operations in ESX Server 3i, ESX Server 3.5, or VirtualCenter 2.5, but is defined for possible use in future releases. Also, the ESX Server WSDL defines an internal operation, LoginExtension, which is not supported on ESX Server 3.5.
However, neither of these minor differences have any impact on your development projects or on your ability to run existing code or samples. You can safely disregard this issue.

Performance Statistics Issue

Incorrect Value Returned for Missing Statistics
When performance statistics are not available for a time interval, their value is returned as -1. This might happen due to a failure in statistics collection (for example, if hostd is down, or VirtualCenter is not able to collect statistics). Also, the relevant statistic might not be applicable during the time period (for example, if the virtual machine is not powered on, or the virtual machine’s network adapter is disabled).