Collapse All
Parallels Virtualization SDK
ContentsIndex
PreviousUpNext
PHT_EVENT
Functions  Functions by Handle  Legend

The PHT_EVENT handle is a container that can contain information about system events or extended error information in asynchronous functions.

Description

When the PHT_EVENT object is used as an event data container, a handle to it is obtained through callback functionality (a handle is passed as a parameter to a callback function). When the object is used as an extended error information container in asynchronous functions, a handle to it is obtained from the PHT_JOB object returned by a function by calling the PrlJob_GetError function. 

The common steps in processing an event in a callback function are as follows:

  1. Determine the type of the event by calling the PrlEvent_GetType function passing the event handle to it. The event types are defined in the PRL_EVENT_TYPE enumeration. This will tell you what happened on the Parallels Service side. For example, a virtual machine state has changed, the host configuration has been updated, etc.
  2. Determine the event source by calling the PrlEvent_GetIssuerType function. The function returns the event issuer type that you can look up in the PRL_EVENT_ISSUER_TYPE enumeration. This will tell you if the event was generated by the host, a virtual machine, a web service, etc.
  3. If an event was generated by the Parallels Service or a virtual machine, you can obtain the server or the virtual machine handle by using the PrlEvent_GetServer or the PrlEvent_GetVm function respectively. Depending on the event type, you may use a handle to access the Parallels Service or a virtual machine and perform some operations on them if needed.
  4. An event object may contain additional parameters, which can be retrieved from it using the PrlEvent_GetParam function. The function returns a handle of type PHT_EVENT_PARAMETER containing an individual parameter data. There may be multiple parameters in a given event object, so the function must be called once for each of the available parameters. To determine the number of parameters, use the PrlEvent_GetParamsCount function. Once you've obtained a PHT_EVENT_PARAMETER handle, you can use its functions to retrieve the parameter values.
Functions
 
Name 
Description 
 
Determines whether the event is critical or not. 
 
Generates properly formatted and structured answer to a question included in the event. 
 
Generates response to a response included in the event. 
 
Clients can use this method to receive a data buffer specific to the event type. 
 
Returns the code associated with the event. 
 
Returns string representation of the event message. 
 
Returns the event issuer ID (host UUID, virtual machine UUID, etc). 
 
Returns the event issuer type (virtual machine, host, etc.). 
 
Obtains the handle of the job that caused the event. 
 
Obtains a handle of type PHT_EVENT_PARAMETER containing an event parameter data. 
 
Obtains a handle of type PHT_EVENT_PARAMETER containing an event parameter data by specified parameter name. 
 
Determines the number of the parameters in the event container. 
 
Obtains a handle of type PHT_SERVER identifying the Parallels Service that generated the event. 
 
Returns the type of the event. 
 
Obtains a handle of type PHT_VIRTUAL_MACHINE referencing the virtual machine that generated the event. 
 
Determines whether the event requires a response from the client. 
Links
© 2021 Parallels International GmbH. All rights reserved.