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.

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.

Call the

VMGuestLib_UpdateInfo

function to update the information available through the handle.

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;
}

Table 1 lists the context functions for creating and releasing handles, updating information, and obtaining session IDs.

Open, Close, and Update Functions
Function	Description
VMGuestLib_OpenHandle	Gets a handle for use with other VM Guest API functions. The guest library handle provides a context for accessing information about the virtual machine. Virtual machine statistics and state data are associated with a particular guest library handle, so using one handle does not affect the data associated with another handle.
VMGuestLib_CloseHandle	Releases a handle acquired with VMGuestLib_OpenHandle .
VMGuestLib_UpdateInfo	Updates information about the virtual machine. This information is associated with the VMGuestLibHandle . VMGuestLib_UpdateInfo requires similar CPU resources to a system call and therefore can affect performance. If you are concerned about performance, minimize the number of calls to VMGuestLib_UpdateInfo . If your program uses multiple threads, each thread must use a different handle. Otherwise, you must implement a locking scheme around update calls. The VM Guest API does not implement internal locking around access with a handle.
VMGuestLib_GetSessionId	Retrieves the VMSessionID for the current session. Call this function after calling VMGuestLib_UpdateInfo . If VMGuestLib_UpdateInfo has never been called, VMGuestLib_GetSessionId returns VMGUESTLIB_ERROR_NO_INFO .

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.

Accessor Functions for Virtual Machine Data
Function	Description
VMGuestLib_GetCpuLimitMHz	Retrieves the upper limit of processor use in MHz available to the virtual machine. For information about setting the CPU limit, see Limits and Reservations.
VMGuestLib_GetCpuReservationMHz	Retrieves the minimum processing power in MHz reserved for the virtual machine. For information about setting a CPU reservation, see Limits and Reservations.
VMGuestLib_GetCpuShares	Retrieves the number of CPU shares allocated to the virtual machine. For information about how an ESXi host uses CPU shares to manage virtual machine priority, see the vSphere Resource Management Guide .
VMGuestLib_GetCpuStolenMs	Retrieves the number of milliseconds that the virtual machine was in a ready state (able to transition to a run state), but was not scheduled to run.
VMGuestLib_GetCpuUsedMs	Retrieves the number of milliseconds during which the virtual machine has used the CPU. This value includes the time used by the guest operating system and the time used by virtualization code for tasks for this virtual machine. You can combine this value with the elapsed time ( VMGuestLib_GetElapsedMs ) to estimate the effective virtual machine CPU speed. This value is a subset of elapsedMs.
VMGuestLib_GetElapsedMs	Retrieves the number of milliseconds that have passed in the virtual machine since it last started running on the server. The count of elapsed time restarts each time the virtual machine is powered on, resumed, or migrated using VMotion. This value counts milliseconds, regardless of whether the virtual machine is using processing power during that time. You can combine this value with the CPU time used by the virtual machine ( VMGuestLib_GetCpuUsedMs ) to estimate the effective virtual machine CPU speed. cpuUsedMS is a subset of this value.
VMGuestLib_GetHostProcessorSpeed	Retrieves the speed of the ESXi host’s physical CPU in MHz.
VMGuestLib_GetMemActiveMB	Retrieves the amount of memory the virtual machine is actively using—its estimated working set size.
VMGuestLib_GetMemBalloonedMB	Retrieves the amount of memory that has been reclaimed from this virtual machine by the vSphere memory balloon driver, which is also called the “vmmemctl” driver.
VMGuestLib_GetMemLimitMB	Retrieves the upper limit of memory that is available to the virtual machine. For information about setting a memory limit, see Limits and Reservations.
VMGuestLib_GetMemMappedMB	Retrieves the amount of memory that is allocated to the virtual machine. Memory that is ballooned, swapped, or has never been accessed is excluded.
VMGuestLib_GetMemOverheadMB	Retrieves the amount of “overhead” memory associated with this virtual machine that is currently consumed on the host system. Overhead memory is additional memory that is reserved for data structures required by the virtualization layer.
VMGuestLib_GetMemReservationMB	Retrieves the minimum amount of memory that is reserved for the virtual machine. For information about setting a memory reservation, see Limits and Reservations.
VMGuestLib_GetMemSharedMB	Retrieves the amount of physical memory associated with this virtual machine that is copy-on-write (COW) shared on the host.
VMGuestLib_GetMemSharedSavedMB	Retrieves the estimated amount of physical memory on the host saved from copy-on-write (COW) shared guest physical memory.
VMGuestLib_GetMemShares	Retrieves the number of memory shares allocated to the virtual machine, as an unsigned 32-bit value. If the value cannot fit in 32-bits, this call returns an error. In that case, use VMGuestLib_GetMemShares64 instead. For information about how ESXi hosts use memory shares to manage virtual machine priority, see the vSphere Resource Management Guide .
VMGuestLib_GetMemShares64	This call was added in vSphere 7.0 to get the 64-bit value of memory shares allocated to the virtual machine.
VMGuestLib_GetMemSwappedMB	Retrieves the amount of memory that has been reclaimed from this virtual machine by transparently swapping guest memory to disk.
VMGuestLib_GetMemTargetSizeMB	Retrieves the size of the target memory allocation for this virtual machine.
VMGuestLib_GetMemUsedMB	Retrieves the estimated amount of physical host memory currently consumed for this virtual machine's physical memory.
VMGuestLib_GetResourcePoolPath	Retrieves the path name of the resource pool affiliated with the virtual machine on the ESXi host where it is running. VMGuestLib_GetResourcePoolPath uses an additional parameter to determine the size of the path name output string buffer. VMGuestLibError VmGuestLib_GetResourcePoolPath(   VMGuestLibHandle handle,  size_t bufferSize,  char pathBuffer ); handle is an input parameter specifying the guest library handle. bufferSize is an input/output parameter. It is a pointer to the size of the pathBuffer in bytes. If bufferSize is not large enough to accommodate the path (including a NULL terminator), the function returns VMGUESTLIB_ERROR_BUFFER_TOO_SMALL. In this case, the function uses the bufferSize parameter to return the number of bytes required for the string. pathBuffer is an output parameter. It is a pointer to a buffer that receives the resource pool path string. The path string is NULL-terminated. For information about using resource pools, see the vSphere Resource Management Guide .

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:

In the vSphere Client window, click the Resource Allocation tab.

In either the CPU or Memory section, click Edit.

In the Virtual Machine Properties Window, click the Resources tab.

Select either the CPU or Memory setting.

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.

VMware vSphere SDKs and Tools 8.0

VM Guest Library Functions

Calling Context Functions

About Context Functions

Accessor Functions (Virtual Machine)

Limits and Reservations