hgcmsvc.h revision 5cf075f1173d07b89c26db295070415dffc6109d
/** @file
* Host-Guest Communication Manager (HGCM) - Service library definitions.
*/
/*
* Copyright (C) 2006-2007 Oracle Corporation
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* General Public License (GPL) as published by the Free Software
* Foundation, in version 2 as it comes in the "COPYING" file of the
* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
*
* The contents of this file may alternatively be used under the terms
* of the Common Development and Distribution License Version 1.0
* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
* VirtualBox OSE distribution, in which case the provisions of the
* CDDL are applicable instead of those of the GPL.
*
* You may elect to license modified versions of this file under the
* terms and conditions of either the GPL or the CDDL or both.
*/
#ifndef ___VBox_hgcm_h
#define ___VBox_hgcm_h
#ifdef VBOX_TEST_HGCM_PARMS
#endif
/** @todo proper comments. */
/**
* Service interface version.
*
* Includes layout of both VBOXHGCMSVCFNTABLE and VBOXHGCMSVCHELPERS.
*
* A service can work with these structures if major version
* is equal and minor version of service is <= version of the
* structures.
*
* For example when a new helper is added at the end of helpers
* structure, then the minor version will be increased. All older
* services still can work because they have their old helpers
* unchanged.
*
* Revision history.
* 1.1->2.1 Because the pfnConnect now also has the pvClient parameter.
* 2.1->2.2 Because pfnSaveState and pfnLoadState were added
* 2.2->3.1 Because pfnHostCall is now synchronous, returns rc, and parameters were changed
* 3.1->3.2 Because pfnRegisterExtension was added
* 3.2->3.3 Because pfnDisconnectClient helper was added
* 3.3->4.1 Because the pvService entry and parameter was added
* 4.1->4.2 Because the VBOX_HGCM_SVC_PARM_CALLBACK parameter type was added
* 4.2->5.1 Removed the VBOX_HGCM_SVC_PARM_CALLBACK parameter type, as
* this problem is already solved by service extension callbacks
*/
#define VBOX_HGCM_SVC_VERSION_MAJOR (0x0005)
#define VBOX_HGCM_SVC_VERSION_MINOR (0x0001)
/** Typed pointer to distinguish a call to service. */
struct VBOXHGCMCALLHANDLE_TYPEDEF;
typedef struct VBOXHGCMCALLHANDLE_TYPEDEF *VBOXHGCMCALLHANDLE;
/** Service helpers pointers table. */
typedef struct _VBOXHGCMSVCHELPERS
{
/** The service has processed the Call request. */
void *pvInstance;
/** The service disconnects the client. */
typedef VBOXHGCMSVCHELPERS *PVBOXHGCMSVCHELPERS;
#define VBOX_HGCM_SVC_PARM_INVALID (0U)
#define VBOX_HGCM_SVC_PARM_32BIT (1U)
#define VBOX_HGCM_SVC_PARM_64BIT (2U)
#define VBOX_HGCM_SVC_PARM_PTR (3U)
typedef struct VBOXHGCMSVCPARM
{
/** VBOX_HGCM_SVC_PARM_* values. */
union
{
struct
{
void *addr;
} pointer;
} u;
#ifdef __cplusplus
/** Extract a uint32_t value from an HGCM parameter structure */
{
int rc = VINF_SUCCESS;
if (type != VBOX_HGCM_SVC_PARM_32BIT)
if (RT_SUCCESS(rc))
return rc;
}
/** Extract a uint64_t value from an HGCM parameter structure */
{
int rc = VINF_SUCCESS;
if (type != VBOX_HGCM_SVC_PARM_64BIT)
if (RT_SUCCESS(rc))
return rc;
}
/** Extract a pointer value from an HGCM parameter structure */
{
if (type == VBOX_HGCM_SVC_PARM_PTR)
{
return VINF_SUCCESS;
}
return VERR_INVALID_PARAMETER;
}
/** Extract a constant pointer value from an HGCM parameter structure */
{
void *pv;
return rc;
}
/** Extract a pointer value to a non-empty buffer from an HGCM parameter
* structure */
{
if ( RT_SUCCESS(rc)
&& cb > 0)
{
return VINF_SUCCESS;
}
return VERR_INVALID_PARAMETER;
}
/** Extract a pointer value to a non-empty constant buffer from an HGCM
* parameter structure */
{
return rc;
}
/** Extract a string value from an HGCM parameter structure */
{
if (RT_FAILURE(rc))
{
*pcb = 0;
return rc;
}
return rc;
}
/** Extract a constant string value from an HGCM parameter structure */
{
return rc;
}
/** Set a uint32_t value to an HGCM parameter structure */
{
}
/** Set a uint64_t value to an HGCM parameter structure */
{
}
/** Set a pointer value to an HGCM parameter structure */
{
}
/** Set a const string value to an HGCM parameter structure */
{
}
#ifdef VBOX_TEST_HGCM_PARMS
/** Test the getString member function. Indirectly tests the getPointer
* and getBuffer APIs.
* @param hTest an running IPRT test
* @param aType the type that the parameter should be set to before
* calling getString
* @param apcc the value that the parameter should be set to before
* calling getString, and also the address (!) which we
* expect getString to return. Stricter than needed of
* course, but I was feeling lazy.
* @param acb the size that the parameter should be set to before
* calling getString, and also the size which we expect
* getString to return.
* @param rcExp the expected return value of the call to getString.
*/
{
/* An RTTest API like this, which would print out an additional line
* of context if a test failed, would be nice. This is because the
* line number alone doesn't help much here, given that this is a
* subroutine called many times. */
/*
RTTestContextF(hTest,
("doTestGetString, aType=%u, apcc=%p, acp=%u, rcExp=%Rrc",
aType, apcc, acp, rcExp));
*/
if (RT_SUCCESS(rcExp))
{
}
}
/** Run some unit tests on the getString method and indirectly test
* getPointer and getBuffer as well. */
{
}
#endif
#endif
typedef VBOXHGCMSVCPARM *PVBOXHGCMSVCPARM;
#ifdef VBOX_WITH_CRHGSMI
typedef void * HGCMCVSHANDLE;
typedef DECLCALLBACK(void) HGCMHOSTFASTCALLCB (int32_t result, uint32_t u32Function, PVBOXHGCMSVCPARM pParam, void *pvContext);
typedef HGCMHOSTFASTCALLCB *PHGCMHOSTFASTCALLCB;
#endif
/** Service specific extension callback.
* This callback is called by the service to perform service specific operation.
*
* @param pvExtension The extension pointer.
* @param u32Function What the callback is supposed to do.
* @param pvParm The function parameters.
* @param cbParm The size of the function parameters.
*/
typedef DECLCALLBACK(int) FNHGCMSVCEXT(void *pvExtension, uint32_t u32Function, void *pvParm, uint32_t cbParms);
typedef FNHGCMSVCEXT *PFNHGCMSVCEXT;
/** The Service DLL entry points.
*
* HGCM will call the DLL "VBoxHGCMSvcLoad"
* function and the DLL must fill in the VBOXHGCMSVCFNTABLE
* with function pointers.
*/
/* The structure is used in separately compiled binaries so an explicit packing is required. */
#pragma pack(1)
typedef struct _VBOXHGCMSVCFNTABLE
{
/** Filled by HGCM */
/** Size of the structure. */
/** Version of the structure, including the helpers. */
/** Filled by the service. */
/** Size of client information the service want to have. */
#if ARCH_BITS == 64
/** Ensure that the following pointers are properly aligned on 64-bit system. */
#endif
/** Uninitialize service */
/** Inform the service about a client connection. */
/** Inform the service that the client wants to disconnect. */
/** Service entry point.
* Return code is passed to pfnCallComplete callback.
*/
DECLR3CALLBACKMEMBER(void, pfnCall, (void *pvService, VBOXHGCMCALLHANDLE callHandle, uint32_t u32ClientID, void *pvClient, uint32_t function, uint32_t cParms, VBOXHGCMSVCPARM paParms[]));
/** Host Service entry point meant for privileged features invisible to the guest.
* Return code is passed to pfnCallComplete callback.
*/
DECLR3CALLBACKMEMBER(int, pfnHostCall, (void *pvService, uint32_t function, uint32_t cParms, VBOXHGCMSVCPARM paParms[]));
/** Inform the service about a VM save operation. */
DECLR3CALLBACKMEMBER(int, pfnSaveState, (void *pvService, uint32_t u32ClientID, void *pvClient, PSSMHANDLE pSSM));
/** Inform the service about a VM load operation. */
DECLR3CALLBACKMEMBER(int, pfnLoadState, (void *pvService, uint32_t u32ClientID, void *pvClient, PSSMHANDLE pSSM));
/** Register a service extension callback. */
DECLR3CALLBACKMEMBER(int, pfnRegisterExtension, (void *pvService, PFNHGCMSVCEXT pfnExtension, void *pvExtension));
void *pvService;
#pragma pack()
/** Service initialization entry point. */
typedef VBOXHGCMSVCLOAD *PFNVBOXHGCMSVCLOAD;
#define VBOX_HGCM_SVCLOAD_NAME "VBoxHGCMSvcLoad"
#endif