VM Guest Library Functions

Calling Context Functions

The VM Guest API provides a set of functions that initialize and manipulate the context where the Guest API operates. Before your application can use the accessor functions to retrieve information about a virtual machine, use the following functions to initialize the VM Guest API environment.

1. Call the VMGuestLib_OpenHandle function to obtain a handle for accessing information about the virtual machine. The guest library handle is a parameter to every Guest API function.
2. Call the VMGuestLib_UpdateInfo function to update the information available through the handle.
3. Call the VMGuestLib_GetSessionId function to retrieve a session ID.

About Context Functions

The code block below shows a C language fragment that illustrates the function calls for initialization. (Code fragments in this section do not perform error handling. For information about error handling, see VM Guest API Error Codes.)

Initializing the VM Guest API Environment

VMGuestLibHandle glHandle;
VMGuestLibError glError;
VMSessionId sid = 0;
glError = VMGuestLib_OpenHandle(&glHandle);
glError = VMGuestLib_UpdateInfo(glHandle);
glError = VMGuestLib_GetSessionId(glHandle, &sid);

You can use the session ID to detect changes that invalidate previously retrieved data. The code block below shows a fragment that illustrates how to use the session ID to detect stale data. The ResetStats function in the following fragment represents application code to handle the session change.

Detecting Stale Data

VMGuestLibHandle glHandle;
VMGuestLibError glError;
VMSessionId oldSid;
VMSessionId newSid;

/* [...code here would access data based on an existing, valid session ID (oldSid)...] */

/* Update the library, get the session ID, and compare it to the previous session ID */
glError = VMGuestLib_UpdateInfo(glHandle);
glError = GuestLib_GetSessionId(glHandle, &newSid);
if (oldSid != newSid) {
    ResetStats();
    oldSid = newSid;
}

Open, Close, and Update Functions lists the context functions for creating and releasing handles, updating information, and obtaining session IDs.

Accessor Functions (Virtual Machine)

Accessor functions retrieve information about a virtual machine. When you call an accessor function, you pass a guest library handle (type VMGuestLibHandle) to the function. If the function is successful, it returns the requested data as an output parameter. The function return value is an error code (type VMGuestLibError) that indicates success or failure. The code block below shows a C language fragment that illustrates calling VMGuestLib_GetCpuLimitMHz to retrieve the processor limit available to the virtual machine.

Using an Accessor Function

uint32 cpuLimitMHz = 0;
glError = VMGuestLib_GetCpuLimitMHz(glHandle, &cpuLimitMHz);

When a call completes successfully, the function returns the value VMGUESTLIB_ERROR_SUCCESS. If the call is unsuccessful, the error code name contains an appropriate description. For details, see VM Guest API Error Codes.

Call VMGuestLib_UpdateInfo once to refresh all statistics before calling an accessor function or a series of accessor functions.

For more information about ESXi resource management, see the vSphere Resource Management Guide, available on the VMware Web site.

Limits and Reservations

You use the Guest API to retrieve information about limits and reservations for CPU and memory. To set limits and reservations, you can use the vSphere (Web) Client or the vSphere API. Setting limits and reservations on a virtual machine ensures that resources are available to that machine and to other virtual machines that draw resources from the same resource pool.

To use the vSphere Client to set limits or reservations:

1. In the vSphere Client window, click the Resource Allocation tab.
2. In either the CPU or Memory section, click Edit.
3. In the Virtual Machine Properties Window, click the Resources tab.
4. Select either the CPU or Memory setting.
5. Use the slider controls to set limits or reservations.

For more information, see online help for the vSphere Client.

To use the vSphere API to set limits or reservations, call the ReconfigVM_Task method. In the method call, use the VirtualMachineConfigSpec data object to set the cpuAllocation or memoryAllocation property. These properties are of type ResourceAllocationInfo, which has limit and reservation properties. For more information, see the VMware vSphere API Reference Documentation.