HA Application Monitoring API Functions

The following calls are available to a vSphere HA application monitoring program:
HA Application Monitoring API Calls
Call Name
Data Type Returned
Description
VMGuestAppMonitor_Enable
char
Requests the virtual machine infrastructure to monitor the calling application.
The virtual machine infrastructure returns a value of VMGUESTAPPMONITORLIB_ERROR_SUCCESS, if monitoring was enabled.
After your application monitoring program makes this call, your program must call VMGuestAppMonitor_MarkActive() at least once every 30 seconds or the virtual machine infrastructure will change the virtual machine’s status to Red or Gray.
VMGuestAppMonitor_Disable
int
Requests the virtual machine infrastructure to stop monitoring the calling program.
The virtual machine infrastructure returns a value of TRUE if monitoring was disabled.
VMGuestAppMonitor_IsEnabled
int
Returns the current recorded state of application monitoring.
The virtual machine infrastructure returns a value of TRUE if monitoring is enabled.
VMGuestAppMonitor_MarkActive
char
Sends a request to mark the program as active. This function is also called the heartbeat because your program must call it at least once every 30 seconds while your application monitoring is enabled, or the virtual machine infrastructure will determine that the monitoring has failed.
VMGuestAppMonitor_PostAppState
int
Publish the application state that the guest OS wants delivered to vSphere HA. The application should monitor its environment and update its state accordingly. Heartbeat counting does not need to be enabled as a pre-condition, so the
enable()
call is not necessary. Returns 0 (zero) on success.
The single
state
parameter passed to this call can be either:
  • OK – The guest's application agent declared state to be normal and no action is required.
  • needReset
    – The guest's application agent has requested an immediate reset. The guest can request this at any time.
VMGuestAppMonitor_GetAppStatus
char
Returns the current status recorded by the virtual machine infrastructure as ‘Green’, ‘Red’, or ‘Gray’.
  • Green. Virtual machine infrastructure acknowledges that the application is being monitored.
  • Red. Virtual machine infrastructure does not think the application is being monitored. The HA monitoring agent will initialize an asynchronous reset on the virtual machine if the status is Red.
  • Gray. Application should send VMGuestAppMonitor_Enable again, followed by VMGuestAppMonitor_MarkActive, because either application monitoring failed, or the virtual machine was vMotioned to a different location.
    Call VMGuestAppMonitor_Free to free the result.
    If this call returns a nonerror result that was not anticipated, it can mean that another program in the same virtual machine has called VMGuestAppMonitor_Disable or VMGuestAppMonitor_Enable. If your application is still running, call VMGuestAppMonitor_Enable again, followed by calls to VMGuestAppMonitor_MarkActive.
VMGuestAppMonitor_Free
char
Returns a pointer to the memory to be freed.