[1] | 1 | /** @file
|
---|
| 2 | * VBox - Host-Guest Communication Manager (HGCM):
|
---|
| 3 | * Service library definitions.
|
---|
| 4 | */
|
---|
| 5 |
|
---|
| 6 | /*
|
---|
[8155] | 7 | * Copyright (C) 2006-2007 Sun Microsystems, Inc.
|
---|
[1] | 8 | *
|
---|
| 9 | * This file is part of VirtualBox Open Source Edition (OSE), as
|
---|
| 10 | * available from http://www.virtualbox.org. This file is free software;
|
---|
| 11 | * you can redistribute it and/or modify it under the terms of the GNU
|
---|
[5999] | 12 | * General Public License (GPL) as published by the Free Software
|
---|
| 13 | * Foundation, in version 2 as it comes in the "COPYING" file of the
|
---|
| 14 | * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
|
---|
| 15 | * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
|
---|
| 16 | *
|
---|
| 17 | * The contents of this file may alternatively be used under the terms
|
---|
| 18 | * of the Common Development and Distribution License Version 1.0
|
---|
| 19 | * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
|
---|
| 20 | * VirtualBox OSE distribution, in which case the provisions of the
|
---|
| 21 | * CDDL are applicable instead of those of the GPL.
|
---|
| 22 | *
|
---|
| 23 | * You may elect to license modified versions of this file under the
|
---|
| 24 | * terms and conditions of either the GPL or the CDDL or both.
|
---|
[8155] | 25 | *
|
---|
| 26 | * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
|
---|
| 27 | * Clara, CA 95054 USA or visit http://www.sun.com if you need
|
---|
| 28 | * additional information or have any questions.
|
---|
[1] | 29 | */
|
---|
| 30 |
|
---|
[3632] | 31 | #ifndef ___VBox_hgcm_h
|
---|
| 32 | #define ___VBox_hgcm_h
|
---|
[1] | 33 |
|
---|
| 34 | #include <VBox/cdefs.h>
|
---|
| 35 | #include <VBox/types.h>
|
---|
| 36 |
|
---|
| 37 | /** @todo proper comments. */
|
---|
| 38 |
|
---|
| 39 | /**
|
---|
| 40 | * Service interface version.
|
---|
| 41 | *
|
---|
| 42 | * Includes layout of both VBOXHGCMSVCFNTABLE and VBOXHGCMSVCHELPERS.
|
---|
| 43 | *
|
---|
| 44 | * A service can work with these structures if major version
|
---|
| 45 | * is equal and minor version of service is <= version of the
|
---|
| 46 | * structures.
|
---|
| 47 | *
|
---|
| 48 | * For example when a new helper is added at the end of helpers
|
---|
| 49 | * structure, then the minor version will be increased. All older
|
---|
| 50 | * services still can work because they have their old helpers
|
---|
| 51 | * unchanged.
|
---|
| 52 | *
|
---|
| 53 | * Revision history.
|
---|
| 54 | * 1.1->2.1 Because the pfnConnect now also has the pvClient parameter.
|
---|
[905] | 55 | * 2.1->2.2 Because pfnSaveState and pfnLoadState were added
|
---|
[1711] | 56 | * 2.2->3.1 Because pfnHostCall is now synchronous, returns rc, and parameters were changed
|
---|
[2386] | 57 | * 3.1->3.2 Because pfnRegisterExtension was added
|
---|
[6981] | 58 | * 3.2->3.3 Because pfnDisconnectClient helper was added
|
---|
[7801] | 59 | * 3.3->4.1 Because the pvService entry and parameter was added
|
---|
[1] | 60 | */
|
---|
[7801] | 61 | #define VBOX_HGCM_SVC_VERSION_MAJOR (0x0004)
|
---|
| 62 | #define VBOX_HGCM_SVC_VERSION_MINOR (0x0001)
|
---|
[1] | 63 | #define VBOX_HGCM_SVC_VERSION ((VBOX_HGCM_SVC_VERSION_MAJOR << 16) + VBOX_HGCM_SVC_VERSION_MINOR)
|
---|
| 64 |
|
---|
| 65 |
|
---|
| 66 | /** Typed pointer to distinguish a call to service. */
|
---|
| 67 | struct VBOXHGCMCALLHANDLE_TYPEDEF;
|
---|
| 68 | typedef struct VBOXHGCMCALLHANDLE_TYPEDEF *VBOXHGCMCALLHANDLE;
|
---|
| 69 |
|
---|
| 70 | /** Service helpers pointers table. */
|
---|
| 71 | typedef struct _VBOXHGCMSVCHELPERS
|
---|
| 72 | {
|
---|
| 73 | /** The service has processed the Call request. */
|
---|
[4698] | 74 | DECLR3CALLBACKMEMBER(void, pfnCallComplete, (VBOXHGCMCALLHANDLE callHandle, int32_t rc));
|
---|
[1] | 75 |
|
---|
| 76 | void *pvInstance;
|
---|
[6981] | 77 |
|
---|
| 78 | /** The service disconnects the client. */
|
---|
| 79 | DECLR3CALLBACKMEMBER(void, pfnDisconnectClient, (void *pvInstance, uint32_t u32ClientID));
|
---|
[1] | 80 | } VBOXHGCMSVCHELPERS;
|
---|
| 81 |
|
---|
| 82 | typedef VBOXHGCMSVCHELPERS *PVBOXHGCMSVCHELPERS;
|
---|
| 83 |
|
---|
| 84 |
|
---|
| 85 | #define VBOX_HGCM_SVC_PARM_INVALID (0U)
|
---|
| 86 | #define VBOX_HGCM_SVC_PARM_32BIT (1U)
|
---|
| 87 | #define VBOX_HGCM_SVC_PARM_64BIT (2U)
|
---|
| 88 | #define VBOX_HGCM_SVC_PARM_PTR (3U)
|
---|
| 89 |
|
---|
| 90 | typedef struct VBOXHGCMSVCPARM
|
---|
| 91 | {
|
---|
| 92 | /** VBOX_HGCM_SVC_PARM_* values. */
|
---|
| 93 | uint32_t type;
|
---|
| 94 |
|
---|
| 95 | union
|
---|
| 96 | {
|
---|
| 97 | uint32_t uint32;
|
---|
| 98 | uint64_t uint64;
|
---|
| 99 | struct
|
---|
| 100 | {
|
---|
| 101 | uint32_t size;
|
---|
| 102 | void *addr;
|
---|
| 103 | } pointer;
|
---|
| 104 | } u;
|
---|
| 105 | } VBOXHGCMSVCPARM;
|
---|
| 106 |
|
---|
| 107 | typedef VBOXHGCMSVCPARM *PVBOXHGCMSVCPARM;
|
---|
| 108 |
|
---|
[2386] | 109 | /** Service specific extension callback.
|
---|
| 110 | * This callback is called by the service to perform service specific operation.
|
---|
| 111 | *
|
---|
| 112 | * @param pvExtension The extension pointer.
|
---|
| 113 | * @param u32Function What the callback is supposed to do.
|
---|
| 114 | * @param pvParm The function parameters.
|
---|
| 115 | * @param cbParm The size of the function parameters.
|
---|
| 116 | */
|
---|
| 117 | typedef DECLCALLBACK(int) FNHGCMSVCEXT(void *pvExtension, uint32_t u32Function, void *pvParm, uint32_t cbParms);
|
---|
| 118 | typedef FNHGCMSVCEXT *PFNHGCMSVCEXT;
|
---|
| 119 |
|
---|
[1] | 120 | /** The Service DLL entry points.
|
---|
| 121 | *
|
---|
| 122 | * HGCM will call the DLL "VBoxHGCMSvcLoad"
|
---|
| 123 | * function and the DLL must fill in the VBOXHGCMSVCFNTABLE
|
---|
| 124 | * with function pointers.
|
---|
| 125 | */
|
---|
| 126 |
|
---|
| 127 | /* The structure is used in separately compiled binaries so an explicit packing is required. */
|
---|
| 128 | #pragma pack(1)
|
---|
| 129 | typedef struct _VBOXHGCMSVCFNTABLE
|
---|
| 130 | {
|
---|
| 131 | /** Filled by HGCM */
|
---|
| 132 |
|
---|
| 133 | /** Size of the structure. */
|
---|
| 134 | uint32_t cbSize;
|
---|
| 135 |
|
---|
| 136 | /** Version of the structure, including the helpers. */
|
---|
| 137 | uint32_t u32Version;
|
---|
| 138 |
|
---|
| 139 | PVBOXHGCMSVCHELPERS pHelpers;
|
---|
| 140 |
|
---|
| 141 | /** Filled by the service. */
|
---|
| 142 |
|
---|
| 143 | /** Size of client information the service want to have. */
|
---|
| 144 | uint32_t cbClient;
|
---|
| 145 | #if ARCH_BITS == 64
|
---|
[2386] | 146 | /** Ensure that the following pointers are properly aligned on 64-bit system. */
|
---|
| 147 | uint32_t u32Alignment0;
|
---|
[1] | 148 | #endif
|
---|
| 149 |
|
---|
| 150 | /** Uninitialize service */
|
---|
[7801] | 151 | DECLR3CALLBACKMEMBER(int, pfnUnload, (void *pvService));
|
---|
[1] | 152 |
|
---|
| 153 | /** Inform the service about a client connection. */
|
---|
[7801] | 154 | DECLR3CALLBACKMEMBER(int, pfnConnect, (void *pvService, uint32_t u32ClientID, void *pvClient));
|
---|
[1] | 155 |
|
---|
| 156 | /** Inform the service that the client wants to disconnect. */
|
---|
[7801] | 157 | DECLR3CALLBACKMEMBER(int, pfnDisconnect, (void *pvService, uint32_t u32ClientID, void *pvClient));
|
---|
[1] | 158 |
|
---|
| 159 | /** Service entry point.
|
---|
| 160 | * Return code is passed to pfnCallComplete callback.
|
---|
| 161 | */
|
---|
[7801] | 162 | DECLR3CALLBACKMEMBER(void, pfnCall, (void *pvService, VBOXHGCMCALLHANDLE callHandle, uint32_t u32ClientID, void *pvClient, uint32_t function, uint32_t cParms, VBOXHGCMSVCPARM paParms[]));
|
---|
[1] | 163 |
|
---|
| 164 | /** Host Service entry point meant for privileged features invisible to the guest.
|
---|
| 165 | * Return code is passed to pfnCallComplete callback.
|
---|
| 166 | */
|
---|
[7801] | 167 | DECLR3CALLBACKMEMBER(int, pfnHostCall, (void *pvService, uint32_t function, uint32_t cParms, VBOXHGCMSVCPARM paParms[]));
|
---|
[905] | 168 |
|
---|
| 169 | /** Inform the service about a VM save operation. */
|
---|
[7801] | 170 | DECLR3CALLBACKMEMBER(int, pfnSaveState, (void *pvService, uint32_t u32ClientID, void *pvClient, PSSMHANDLE pSSM));
|
---|
[1] | 171 |
|
---|
[905] | 172 | /** Inform the service about a VM load operation. */
|
---|
[7801] | 173 | DECLR3CALLBACKMEMBER(int, pfnLoadState, (void *pvService, uint32_t u32ClientID, void *pvClient, PSSMHANDLE pSSM));
|
---|
[905] | 174 |
|
---|
[2386] | 175 | /** Manage the service extension. */
|
---|
[7801] | 176 | DECLR3CALLBACKMEMBER(int, pfnRegisterExtension, (void *pvService, PFNHGCMSVCEXT pfnExtension, void *pvExtension));
|
---|
[2386] | 177 |
|
---|
[7801] | 178 | /** User/instance data pointer for the service. */
|
---|
| 179 | void *pvService;
|
---|
| 180 |
|
---|
[1] | 181 | } VBOXHGCMSVCFNTABLE;
|
---|
| 182 | #pragma pack()
|
---|
| 183 |
|
---|
| 184 |
|
---|
| 185 | /** Service initialization entry point. */
|
---|
| 186 | typedef DECLCALLBACK(int) VBOXHGCMSVCLOAD(VBOXHGCMSVCFNTABLE *ptable);
|
---|
| 187 | typedef VBOXHGCMSVCLOAD *PFNVBOXHGCMSVCLOAD;
|
---|
| 188 | #define VBOX_HGCM_SVCLOAD_NAME "VBoxHGCMSvcLoad"
|
---|
| 189 |
|
---|
[3633] | 190 | #endif
|
---|