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