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