Download Oracle VM VirtualBox Programming Guide and Reference

7 Host-Guest Communication Manager
7.4 HGCM Service Implementation
The HGCM service is a shared library with a specific set of entry points. The library must export
the VBoxHGCMSvcLoad entry point:
extern "C" DECLCALLBACK(DECLEXPORT(int)) VBoxHGCMSvcLoad (VBOXHGCMSVCFNTABLE *ptable)
The service must check the ptable->cbSize and ptable->u32Version fields of the input
structure and fill the remaining fields with function pointers of entry points and the size of the
required client buffer size.
The HGCM service gets a dedicated thread, which calls service entry points synchronously, that
is the service will be called again only when a previous call has returned. However, the guest
calls can be processed asynchronously. The service must call a completion callback when the
operation is actually completed. The callback can be issued from another thread as well.
Service entry points are listed in the VBox/hgcmsvc.h in the VBOXHGCMSVCFNTABLE structure.
Entry
pfnUnload
pfnConnect
pfnDisconnect
pfnCall
pfnHostCall
pfnSaveState
pfnLoadState
Description
The service is being unloaded.
A client u32ClientID is connected to the service. The pvClient parameter points
to an allocated memory buffer which can be used by the service to store the client
information.
A client is being disconnected.
A guest client calls a service function. The callHandle must be used in the
VBOXHGCMSVCHELPERS::pfnCallComplete callback when the call has been
processed.
Called by the VirtualBox host components to perform functions which should be
not accessible by the guest. Usually this entry point is used by VirtualBox to
configure the service.
The VM state is being saved and the service must save relevant information using
the SSM API (VBox/ssm.h).
The VM is being restored from the saved state and the service must load the saved
information and be able to continue operations from the saved state.
321