vSphere Guest Programming Guide

VMware vSphere Guest SDK 4.0

This document supports the version of each product listed and supports all subsequent versions until the document is replaced by a new edition. To check for more recent editions of this document, see http://www.vmware.com/support/pubs.

EN-000389-00

vSphere Guest Programming Guide

You can find the most up-to-date technical documentation on the VMware Web site at: http://www.vmware.com/support/ The VMware Web site also provides the latest product updates. If you have comments about this documentation, submit your feedback to: docfeedback@vmware.com

Copyright 2005, 2007, 2009, 2010 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and intellectual property laws. VMware products are covered by one or more patents listed at http://www.vmware.com/go/patents. VMware is a registered trademark or trademark of VMware, Inc. in the United States and/or other jurisdictions. All other marks and names mentioned herein may be trademarks of their respective companies.

VMware, Inc. 3401 Hillview Ave. Palo Alto, CA 94304 www.vmware.com

VMware, Inc.

Contents

AboutThisBook

5 7

VMwarevSphereGuestSDKProgrammingGuide
OverviewofthevSphereGuestAPI 7 SupportedGuestOperatingSystems 7 VirtualMachineStatistics 7 HowtoUsethevSphereGuestAPI 8 vSphereGuestAPIRuntimeComponents 8 EnablingandDisablingtheRuntimeComponents 8 vSphereGuestAPIDataTypes 9 vSphereGuestAPIFunctions 9 ContextFunctions 9 AccessorFunctions(VirtualMachine) 11 vSphereGuestAPIErrorCodes 13

Index 15

VMware, Inc.

vSphere Guest Programming Guide

VMware, Inc.

About This Book

ThevSphereGuestProgrammingGuideprovidesinformationaboutdevelopingapplicationsusingtheVMware GuestApplicationProgrammingInterface(API).VMwareprovidesseveraldifferentsoftwaredevelopment kit(SDK)products,eachofwhichtargetsdifferentdevelopercommunitiesandtargetplatforms.Thisguideis intendedfordeveloperswhowanttoretrieveinformationaboutthevirtualmachineandhosthardwarein whichtheapplicationruns.ThesupportedplatformsincludeVMwareESX3.0.x,andVMwareESX/ESXi3.5, 4.0,and4.1.

Revision History
Thisbookisrevisedwitheachreleaseoftheproductorwhennecessary.Arevisedversioncancontainminor ormajorchanges.Table 1summarizesthesignificantchangesineachversionofthisbook. Table 1. Revision History
Revision Date 13JUL2010 7MAY2009 29NOV2007 18JUL2005 Description Nonewinformation,butrevisedtonotesupportforVMwareESX4.1. RevisedmanualforVMwareESXversion4.0. Nonewinformation,butrevisedtonotesupportforVMwareESX3.5andVMwareESX3iversion3.5. InitialreleaseoftheVMwareGuestSDKprovidingsupportforVMwareESX3.0.

Intended Audience
Thisbookisintendedforanyonedevelopingapplicationstoruninsideguestoperatingsystemsunder VMwareESX.

VMware Technical Publications Glossary

VMwareTechnicalPublicationsprovidesaglossaryoftermsthatmightbeunfamiliartoyou.Fordefinitions oftermsastheyareusedinVMwaretechnicaldocumentationgotohttp://www.vmware.com/support/pubs.

Document Feedback
VMwarewelcomesyoursuggestionsforimprovingourdocumentation.Sendyourfeedbackto docfeedback@vmware.com.

Technical Support and Education Resources

Thefollowingsectionsdescribethetechnicalsupportresourcesavailabletoyou.Toaccessthecurrentversions ofotherVMwarebooks,gotohttp://www.vmware.com/support/pubs.

VMware, Inc.

vSphere Guest Programming Guide

Online and Telephone Support

Touseonlinesupporttosubmittechnicalsupportrequests,viewyourproductandcontractinformation,and registeryourproducts,gotohttp://www.vmware.com/support.

Support Offerings
TofindouthowVMwaresupportofferingscanhelpmeetyourbusinessneeds,goto http://www.vmware.com/support/services.

VMware Professional Services

VMwareEducationServicescoursesofferextensivehandsonlabs,casestudyexamples,andcoursematerials designedtobeusedasonthejobreferencetools.Coursesareavailableonsite,intheclassroom,andlive online.Foronsitepilotprograms andimplementationbestpractices,VMwareConsultingServicesprovides offeringsto helpyouassess,plan,build,andmanageyourvirtualenvironment.Toaccessinformationabout educationclasses,certificationprograms,andconsultingservices,gotohttp://www.vmware.com/services.

VMware, Inc.

VMware vSphere Guest SDK Programming Guide

TheVMwareGuestAPIprovidesfunctionsthatyoucanuseinaprogramthatrunsintheguestoperating systemenvironmentonaVMwareESXvirtualmachine.Thisguideincludesthefollowingtopics:

OverviewofthevSphereGuestAPIonpage 7 HowtoUsethevSphereGuestAPIonpage 8

Overview of the vSphere Guest API

ThevSphereGuestAPIprovidesfunctionsthatmanagementagentsandothersoftwarecanusetocollectdata aboutthestateandperformanceofaVMwareESXvirtualmachine.TheAPIprovidesfastaccesstoresource managementinformation,withouttheneedforauthentication. TheGuestAPIprovidesreadonlyaccess.YoucanreaddatausingtheAPI,butyoucannotsendcontrol commands.Toissuecontrolcommands,usethevSphereWebServicesSDK.Fordetails,seetheVMware vSphereWebServicesSDKProgrammingGuideandtheVMwarevSphereAPIReference,whichareavailableonthe VMwareWebsite.

Supported Guest Operating Systems

ThevSphereGuestAPIsoftwarerunsonmostWindowsorLinuxguestoperatingsystemssupportedby VMwareESX3.0.x,VMwareESX/ESXi 3.5,VMwareESX/ESXi 4.0,orVMwareESX/ESXi4.1.TheGuestAPI doesnotsupportthefollowingguestoperatingsystemenvironments:

Windows9x. WinNT4.TousetheGuestAPIonWinNT4youmustuseGuestSDK3.5;goto http://www.vmware.com/support/developer/guestsdk.

SeetheGuestOperatingSystemInstallationGuideforalistofsupportedguestoperatingsystemversions.

Virtual Machine Statistics

WiththevSphereGuestAPI,youcanmonitorvariousstatisticsaboutthevirtualmachine.Youcanusethis informationtoretrieveschedulingandresourceusageinformationabouttheenvironment.Withthese statistics,thevirtualmachinecanreacttochangesinthevirtualenvironmentimmediatelyattheapplication layer. ThefollowinglistshowssomeoftheinformationthatyoucanretrievethroughthevSphereGuestAPI:

Amountofmemoryreservedforthevirtualmachine. Amountofmemorybeingusedbythevirtualmachine. Upperlimitofmemoryavailabletothevirtualmachine. Numberofmemorysharesassignedtothevirtualmachine.

VMware, Inc.

vSphere Guest Programming Guide

MaximumspeedtowhichthevirtualmachinesCPUislimited. Reservedrateatwhichthevirtualmachineisallowedtoexecute.Anidlingvirtualmachinemight consumeCPUcyclesatamuchlowerrate. NumberofCPUsharesassignedtothevirtualmachine. Elapsedtimesincethevirtualmachinewaslastpoweredonorreset. CPUtimeconsumedbyaparticularvirtualmachine.Whencombinedwithothermeasurements,youcan estimatehowfastthevirtualmachinesCPUsarerunningcomparedtothehostCPUs.

IMPORTANTTheAPIusesahandlethatprovidesaccesstothestatistics.Thehandlealsoisamechanismto determinewhethertheAPIcanprovideaccurateinformation.(Certainevents,suchamigratingavirtual machinewithVMotion,temporarilymakeitimpossibletoprovideaccurateinformation.)

How to Use the vSphere Guest API

ThevSphereGuestAPIdefinesfunctionsanddatatypesthatyouusetoextractvirtualmachinedata.This sectioncoversthefollowingtopics:

vSphereGuestAPIRuntimeComponentsonpage 8 vSphereGuestAPIDataTypesonpage 9 vSphereGuestAPIFunctionsonpage 9 vSphereGuestAPIErrorCodesonpage 13

vSphere Guest API Runtime Components

TousethevSphereGuestAPI,theruntimecomponentsmustbeinstalledintheguestoperatingsystem.The runtimecomponentsaredynamicallyloadedbinarymodulesfor32bitand64bitguests.Whenyouinstall VMwareTools,thevSphereGuestAPIruntimecomponentsareinstalledautomatically.Youcanalso downloadthemfromhttp://www.vmware.com/download/sdk/guest_sdk.html. TomakethevSphereGuestAPIfunctionsavailabletoyourprogram,useyourprogramsstandardmethods toloadthelibrary.

InaWindowsguestoperatingsystem,thelibraryfileisvmGuestLib.dll.Theimportlibraryfileis vmGuestLib.lib. InaLinuxguestoperatingsystem,thelibraryfileislibvmGuestLib.so. IMPORTANTIfyouareusingaSecurityEnhancedLinux(SELinux)guestoperatingsystem,thesecurity policiesmightinterferewithdynamicloadingoflibvmGuestLib.so.RefertodocumentationaboutSELinux policyconfiguration.

ThevSphereGuestSDKincludesthetestprogramvmGuestlibTest.c.IfyouareusingaWindows environment,youmustrebuildthetestprogram.ThevmGuestLib.dlllibraryfileisanonUnicodeDLL.In MicrosoftVisualStudio,buildthetestprogramvmGuestlibTest.casanonUnicodeexecutablesothatthe programcanaccesstheDLLatruntime.

Enabling and Disabling the Runtime Components

ThevSphereGuestAPIruntimecomponentsareenabledbydefault(disable = FALSE).Todisablethe runtimecomponents,usetheconfigurationeditorinthevSphereClienttoedittheconfigurationfileforthe virtualmachine.Thevirtualmachinemustbepoweredoffbeforeyoucanusetheconfigurationeditor. 1 2 3 InthevSphereClientwindow,rightclickthevirtualmachineinthemachinelist. Inthedropdownmenu,selectEditSettings. IntheVirtualMachinePropertieswindow,clicktheOptionstab.

VMware, Inc.

VMware vSphere Guest SDK Programming Guide

4 5 6

InthelistofAdvancedsettings,selectGeneral. ClickConfigurationParameters. IntheConfigurationParameterswindow,addthefollowinglineor,ifthefilealreadycontainsthedisable configurationsetting,setthevaluetoTRUE:

isolation.tools.guestlibGetInfo.disable = "TRUE"

ThedefaultvalueforthedisablesettingisFALSE.Thedefaultsettingenablestheruntimecomponents. ReinstallingVMwareToolsdoesnotaffectthedisablesetting.IfyoudisablethevSphereGuestAPIand thenreinstallVMwaretools,thevSphereGuestAPIcontinuestobeunavailableuntilyouchangethe guestLibGetInfo.disableconfigurationsettingtoFALSE.

vSphere Guest API Data Types

ThevSphereGuestAPIusesthedatatypeslistedinTable 2tosupportaccesstovirtualmachinedata. Table 2. Data Types
Data Type VMGuestLibHandle VMSessionID Description Referencetovirtualmachinedata.VMGuestLibHandleisdefinedinvmGuestLib.h. Uniqueidentifierforasession.ThesessionIDchangesafteravirtualmachineis migratedusingVMotion,suspendedandresumed,orrevertedtoasnapshot.Anyof theseeventsislikelytorenderanyinformationretrievedwiththisAPIinvalid.You canusethesessionIDtodetectthoseeventsandreactaccordingly.Forexample,you canrefreshandresetanystatethatreliesonthevalidityofpreviouslyretrieved information. UseVMGuestLib_GetSessionIdtoobtainavalidsessionID.AsessionIDis opaque.YoucannotcompareavirtualmachinesessionIDwiththesessionIDsfrom anyothervirtualmachines.YoumustalwayscallVMGuestLib_GetSessionIdafter callingVMGuestLib_UpdateInfo. VMSessionIDisdefinedinvmSessionId.h. VMGuestLibError Statuscodethatindicatessuccessorfailure.Eachfunctionreturnsa VMGuestLibErrorcode.Forinformationaboutspecificerrorcodes,seevSphere GuestAPIErrorCodesonpage 13.VMGuestLibErrorisanenumeratedtype definedinvmGuestLib.h.

vSphere Guest API Functions

ThevSphereGuestSDKcontainstheheaderfilevmGuestLib.h.Thisfiledeclaresthefunctionsanddatatypes thatyouusetocallthevSphereGuestAPI.ThefollowingsectionsdescribethevSphereGuestAPIfunctions:

ContextFunctionsonpage 9 AccessorFunctions(VirtualMachine)onpage 11

Context Functions
ThevSphereGuestAPIprovidesasetoffunctionsthatinitializeandmanipulatethecontextinwhichthe GuestAPIoperates.Beforeyourapplicationcanusetheaccessorfunctionstoretrieveinformationabouta virtualmachine,usethefollowingfunctionstoinitializethevSphereGuestAPIenvironment. 1 2 3 CalltheVMGuestLib_OpenHandlefunctiontoobtainahandleforaccessinginformationaboutthevirtual machine.TheguestlibraryhandleisaparametertoeveryGuestAPIfunction. CalltheVMGuestLib_UpdateInfofunctiontoupdatetheinformationavailablethroughthehandle. CalltheVMGuestLib_GetSessionIdfunctiontoretrieveasessionID.

VMware, Inc.

vSphere Guest Programming Guide

Example 1showsaCcodefragmentthatillustratesthefunctioncallsforinitialization.(Thecodefragmentsin thissectiondonotperformerrorhandling.Forinformationabouterrorhandling,seevSphereGuestAPI ErrorCodesonpage 13.) Example 1. Initializing the vSphere Guest API Environment
VMGuestLibHandle glHandle; VMGuestLibError glError; VMSessionId sid = 0; glError = VMGuestLib_OpenHandle(&glHandle); glError = VMGuestLib_UpdateInfo(glHandle); glError = VMGuestLib_GetSessionId(glHandle, &sid);

YoucanusethesessionIDtodetectchangesthatinvalidatepreviouslyretrieveddata.Example 2showsacode fragmentthatillustrateshowtousethesessionIDtodetectstaledata.(TheResetStatsfunctioninthe followingfragmentrepresentsapplicationcodetohandlethesessionchange.) Example 2. 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 3liststhecontextfunctionsforcreatingandreleasinghandles,updatinginformation,andobtaining sessionIDs. Table 3. Open, Close, and Update Functions

Function VMGuestLib_OpenHandle Description GetsahandleforusewithothervSphereGuestAPIfunctions.Theguestlibrary handleprovidesacontextforaccessinginformationaboutthevirtualmachine. Virtualmachinestatisticsandstatedataareassociatedwithaparticularguestlibrary handle,sousingonehandledoesnotaffectthedataassociatedwithanotherhandle. ReleasesahandleacquiredwithVMGuestLib_OpenHandle. Updatesinformationaboutthevirtualmachine.Thisinformationisassociatedwith theVMGuestLibHandle. VMGuestLib_UpdateInforequiressimilarCPUresourcestoasystemcalland thereforecanaffectperformance.Ifyouareconcernedaboutperformance,minimize thenumberofcallstoVMGuestLib_UpdateInfo. Ifyourprogramusesmultiplethreads,eachthreadmustuseadifferenthandle. Otherwise,youmustimplementalockingschemearoundupdatecalls.ThevSphere GuestAPIdoesnotimplementinternallockingaroundaccesswithahandle. VMGuestLib_GetSessionId RetrievestheVMSessionIDforthecurrentsession.Callthisfunctionaftercalling VMGuestLib_UpdateInfo.IfVMGuestLib_UpdateInfohasneverbeencalled, VMGuestLib_GetSessionIdreturnsVMGUESTLIB_ERROR_NO_INFO.

VMGuestLib_CloseHandle VMGuestLib_UpdateInfo

10

VMware, Inc.

VMware vSphere Guest SDK Programming Guide

Accessor Functions (Virtual Machine)

Accessorfunctionsretrieveinformationaboutavirtualmachine.Whenyoucallanaccessorfunction,youpass aguestlibraryhandle(typeVMGuestLibHandle)tothefunction.Ifthefunctionissuccessful,itreturnsthe requesteddataasanoutputparameter.Thefunctionreturnvalueisanerrorcode(typeVMGuestLibError) thatindicatessuccessorfailure.Example 3showsaCcodefragmentthatillustratesanexampleofcalling VMGuestLib_GetCpuLimitMHztoretrievetheprocessorlimitavailabletothevirtualmachine. Example 3. Using an Accessor Function
uint32 cpuLimitMHz = 0; glError = VMGuestLib_GetCpuLimitMHz(glHandle, &cpuLimitMHz);

Whenacallcompletessuccessfully,thefunctionreturnsthevalueVMGUESTLIB_ERROR_SUCCESS.Unsuccessful callsreturnerrorcodesthatcontainanappropriatedescriptionaspartoftheerrorcodename.Fordetails,see vSphereGuestAPIErrorCodesonpage 13. CallVMGuestLib_UpdateInfooncetorefreshallstatisticsbeforecallinganaccessorfunctionoraseriesof accessorfunctions. Table 4. Accessor Functions for Virtual Machine Data
Function VMGuestLib_GetCpuLimitMHz Description RetrievestheupperlimitofprocessoruseinMHzavailabletothevirtual machine.ForinformationaboutsettingtheCPUlimit,seeLimitsand Reservationsonpage 12. RetrievestheminimumprocessingpowerinMHzreservedforthevirtual machine.ForinformationaboutsettingaCPUreservation,seeLimitsand Reservationsonpage 12. RetrievesthenumberofCPUsharesallocatedtothevirtualmachine.For informationabouthowanESXserverusesCPUsharestomanagevirtual machinepriority,seethevSphereResourceManagementGuide. Retrievesthenumberofmillisecondsthatthevirtualmachinewasina readystate(abletotransitiontoarunstate),butwasnotscheduledtorun. Retrievesthenumberofmillisecondsduringwhichthevirtualmachine hasusedtheCPU.Thisvalueincludesthetimeusedbytheguest operatingsystemandthetimeusedbyvirtualizationcodefortasksforthis virtualmachine.Youcancombinethisvaluewiththeelapsedtime (VMGuestLib_GetElapsedMs)toestimatetheeffectivevirtualmachine CPUspeed.ThisvalueisasubsetofelapsedMs. Retrievesthenumberofmillisecondsthathavepassedinthevirtual machinesinceitlaststartedrunningontheserver.Thecountofelapsed timerestartseachtimethevirtualmachineispoweredon,resumed,or migratedusingVMotion.Thisvaluecountsmilliseconds,regardlessof whetherthevirtualmachineisusingprocessingpowerduringthattime. YoucancombinethisvaluewiththeCPUtimeusedbythevirtualmachine (VMGuestLib_GetCpuUsedMs)toestimatetheeffectivevirtualmachine CPUspeed.cpuUsedMSisasubsetofthisvalue. RetrievesthespeedoftheESXsystemsphysicalCPUinMHz. Retrievestheamountofmemorythevirtualmachineisactivelyusingits estimatedworkingsetsize. Retrievestheamountofmemorythathasbeenreclaimedfromthisvirtual machinebythevSpherememoryballoondriver(alsoreferredtoasthe vmmemctldriver). Retrievestheupperlimitofmemorythatisavailabletothevirtual machine.Forinformationaboutsettingamemorylimit,seeLimitsand Reservationsonpage 12. Retrievestheamountofmemorythatisallocatedtothevirtualmachine. Memorythatisballooned,swapped,orhasneverbeenaccessedis excluded.

VMGuestLib_GetCpuReservationMHz

VMGuestLib_GetCpuShares

VMGuestLib_GetCpuStolenMs VMGuestLib_GetCpuUsedMs

VMGuestLib_GetElapsedMs

VMGuestLib_GetHostProcessorSpeed VMGuestLib_GetMemActiveMB VMGuestLib_GetMemBalloonedMB

VMGuestLib_GetMemLimitMB

VMGuestLib_GetMemMappedMB

VMware, Inc.

11

vSphere Guest Programming Guide

Table 4. Accessor Functions for Virtual Machine Data (Continued)

VMGuestLib_GetMemOverheadMB Retrievestheamountofoverheadmemoryassociatedwiththisvirtual machinethatiscurrentlyconsumedonthehostsystem.Overhead memoryisadditionalmemorythatisreservedfordatastructuresrequired bythevirtualizationlayer. Retrievestheminimumamountofmemorythatisreservedforthevirtual machine.Forinformationaboutsettingamemoryreservation,seeLimits andReservationsonpage 12. Retrievestheamountofphysicalmemoryassociatedwiththisvirtual machinethatiscopyonwrite(COW)sharedonthehost. Retrievestheestimatedamountofphysicalmemoryonthehostsaved fromcopyonwrite(COW)sharedguestphysicalmemory. Retrievesthenumberofmemorysharesallocatedtothevirtualmachine. ForinformationabouthowanESXserverusesmemorysharestomanage virtualmachinepriority,seethevSphereResourceManagementGuide. Retrievestheamountofmemorythathasbeenreclaimedfromthisvirtual machinebytransparentlyswappingguestmemorytodisk. Retrievesthesizeofthetargetmemoryallocationforthisvirtualmachine. Retrievestheestimatedamountofphysicalhostmemorycurrently consumedforthisvirtualmachinesphysicalmemory. Retrievesthepathnameoftheresourcepooltowhichthevirtualmachine belongsontheESXsystemwhereitisrunning. VMGuestLib_GetResourcePoolPathusesanadditionalparameterto determinethesizeofthepathnameoutputstringbuffer. VMGuestLibError VmGuestLib_GetResourcePoolPath( VMGuestLibHandle handle, size_t *bufferSize, char *pathBuffer ); handleisaninputparameterspecifyingtheguestlibraryhandle. bufferSizeisaninput/outputparameter.Itisapointertothesizeofthe pathBufferinbytes.IfbufferSizeisnotlargeenoughtoaccomodatethe path(includingaNULLterminator),thefunctionreturns VMGUESTLIB_ERROR_BUFFER_TOO_SMALL.Inthiscase,thefunction usesthebufferSizeparametertoreturnthenumberofbytesrequiredfor thestring. pathBufferisanoutputparameter.Itisapointertoabufferthatreceives theresourcepoolpathstring.ThepathstringisNULLterminated. Forinformationaboutusingresourcepools,seethevSphereResource ManagementGuide.

VMGuestLib_GetMemReservationMB

VMGuestLib_GetMemSharedMB VMGuestLib_GetMemSharedSavedMB VMGuestLib_GetMemShares

VMGuestLib_GetMemSwappedMB VMGuestLib_GetMemTargetSizeMB VMGuestLib_GetMemUsedMB VMGuestLib_GetResourcePoolPath

FormoreinformationaboutESXresourcemanagement,seethevSphereResourceManagementGuide,available ontheVMwareWebsite. Limits and Reservations YouusetheGuestAPItoretrieveinformationaboutlimitsandreservationsforCPUandmemory.Tosetlimits andreservations,youcanuseeitherthevSphereClientorthevSphereAPI.Settinglimitsandreservationson avirtualmachineensuresthatresourcesareavailabletothatmachineandtoothervirtualmachinesthatdraw resourcesfromthesameresourcepool. TousethevSphereClienttosetlimitsorreservations: 1 2 3 InthevSphereClientwindow,clickontheResourceAllocationtab. IneithertheCPUorMemorysection,clickEdit. IntheVirtualMachinePropertiesWindow,clickontheResourcestab.

12

VMware, Inc.

VMware vSphere Guest SDK Programming Guide

4 5

SelecteithertheCPUorMemorysetting. Usetheslidercontrolstosetlimitsorreservations.

Formoreinformation,seethehelpforthevSphereClient. TousethevSphereAPItosetlimitsorreservations,calltheReconfigVM_Taskmethod.Inthemethodcall, usetheVirtualMachineConfigSpecdataobjecttosetthecpuAllocationormemoryAllocationproperty. ThesepropertiesareoftypeResourceAllocationInfotype,whichhaslimitandreservationproperties.For moreinformation,seetheVMwarevSphereAPIReferenceDocumentation.

vSphere Guest API Error Codes

EachvSphereGuestAPIfunctionreturnsanerrorcode.Ifsuccessful,thereturnederrorcodeis VMGUESTLIB_ERROR_SUCCESS.Ifthefunctionisunabletocompleteitstask,theerrorcodeprovidesinformationfor diagnosingtheproblem. UsetheVMGuestLib_GetErrorTextfunctiontoretrievetheerrortextassociatedwithaparticularerrorcode. Whenyoucallthefunction,passtheerrorcodetothefunction;VMGuestLib_GetErrorTextreturnsapointer toastringcontainingtheerrortext. Example 4showserrorhandling.TheCcodefragmentdeclaresaguestlibraryhandleandcallsthefunction VMGuestLib_OpenHandle.Ifthecallisnotsuccessful,thecodecallsVMGuestLib_GetErrorTextand displaystheerrortext. Example 4. Error Handling
VMGuestLibHandle glHandle; glError = VMGuestLib_OpenHandle(&glHandle); if (glError != VMGUESTLIB_ERROR_SUCCESS) { printf("OpenHandle failed: %s\n", VMGuestLib_GetErrorText(glError)); }

Table 5listsallerrorcodesdefinedforthevSphereGuestAPI. Table 5. Error Codes

Error Code VMGUESTLIB_ERROR_SUCCESS VMGUESTLIB_ERROR_OTHER VMGUESTLIB_ERROR_NOT_RUNNING_IN_VM VMGUESTLIB_ERROR_NOT_ENABLED Description Thefunctionhascompletedsuccessfully. Anerrorhasoccurred.Noadditionalinformationaboutthetypeof errorisavailable. TheprogrammakingthiscallisnotrunningonaVMwarevirtual machine. ThevSphereGuestAPIisnotenabledonthishost,sothesefunctions cannotbeused.Forinformationabouthowtoenablethelibrary,see ContextFunctionsonpage 9. Theinformationrequestedisnotavailableonthishost. Thehandledatastructuredoesnotcontainanyinformation.Youmust callVMGuestLib_UpdateInfotoupdatethedatastructure. Thereisnotenoughmemoryavailabletocompletethecall. Thebufferistoosmalltoaccommodatethefunctioncall.Forexample, whenyoucallVMGuestLib_GetResourcePoolPath,ifthepathbuffer istoosmallfortheresultingresourcepoolpath,thefunctionreturns thiserror.Toresolvethiserror,allocatealargerbuffer. Thehandlethatyouusedisinvalid.Makesurethatyouhavethecorrect handleandthatitisopen.Itmightbenecessarytocreateanewhandle usingVMGuestLib_OpenHandle. Oneormoreoftheargumentspassedtothefunctionwereinvalid. Thehostdoesnotsupporttherequestedstatistic.

VMGUESTLIB_ERROR_NOT_AVAILABLE VMGUESTLIB_ERROR_NO_INFO VMGUESTLIB_ERROR_MEMORY VMGUESTLIB_ERROR_BUFFER_TOO_SMALL

VMGUESTLIB_ERROR_INVALID_HANDLE

VMGUESTLIB_ERROR_INVALID_ARG VMGUESTLIB_ERROR_UNSUPPORTED_VERSION

VMware, Inc.

13

vSphere Guest Programming Guide

14

VMware, Inc.

Index

Numerics
32-bit guest support 8 64-bit guest support 8

A
accessor functions 11

C
configuration file for virtual machine 8 context functions 9

D
data types 9 disabling the vSphere Guest API 8

E
enabling the vSphere Guest API 8

H
handle 9, 11 how to use the vSphere Guest API 8

L
libvmGuestLib.so 8 Linux guest operating system 7

N
non-Unicode DLL (Windows) 8

VMGuestLib_CloseHandle 10 VMGuestLib_GetCpuLimitMHz 11 VMGuestLib_GetCpuReservationMHz 11 VMGuestLib_GetCpuShares 11 VMGuestLib_GetCpuStolenMs 11 VMGuestLib_GetCpuUsedMs 11 VMGuestLib_GetElapsedMs 11 VMGuestLib_GetHostProcessorSpeed 11 VMGuestLib_GetMemActiveMB 11 VMGuestLib_GetMemBalloonedMB 11 VMGuestLib_GetMemLimitMB 11 VMGuestLib_GetMemMappedMB 11 VMGuestLib_GetMemOverheadMB 12 VMGuestLib_GetMemReservationMB 12 VMGuestLib_GetMemSharedMB 12 VMGuestLib_GetMemSharedSavedMB 12 VMGuestLib_GetMemShares 12 VMGuestLib_GetMemSwappedMB 12 VMGuestLib_GetMemUsedMB 12 VMGuestLib_GetResourcePoolPath 12 VMGuestLib_GetSessionId 10 VMGuestLib_OpenHandle 10 VMGuestLib_UpdateInfo 10 VMGuestLibError 9 VMGuestLibHandle 9 VMGuestLibSessionID 9 vSphere Guest API runtime components 8

O
overview of the vSphere Guest API 7

W
Windows guest operating system 7

R
refreshing all statistics 11 runtime components 8

S
session ID 9 supported guest operating systems 7

T
technical support resources 5 test program vmGuestlibTest.c 8

V
virtual machine statistics 7 vmGuestLib.h 9 vmGuestLib.lib 8
VMware, Inc. 15

vSphere Guest Programming Guide

16

VMware, Inc.