[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
|
---|
[10652] | 60 | * 4.1->4.2 Because the VBOX_HGCM_SVC_PARM_CALLBACK paramteter type was added
|
---|
[1] | 61 | */
|
---|
[7801] | 62 | #define VBOX_HGCM_SVC_VERSION_MAJOR (0x0004)
|
---|
[10652] | 63 | #define VBOX_HGCM_SVC_VERSION_MINOR (0x0002)
|
---|
[1] | 64 | #define VBOX_HGCM_SVC_VERSION ((VBOX_HGCM_SVC_VERSION_MAJOR << 16) + VBOX_HGCM_SVC_VERSION_MINOR)
|
---|
| 65 |
|
---|
| 66 |
|
---|
| 67 | /** Typed pointer to distinguish a call to service. */
|
---|
| 68 | struct VBOXHGCMCALLHANDLE_TYPEDEF;
|
---|
| 69 | typedef struct VBOXHGCMCALLHANDLE_TYPEDEF *VBOXHGCMCALLHANDLE;
|
---|
| 70 |
|
---|
| 71 | /** Service helpers pointers table. */
|
---|
| 72 | typedef struct _VBOXHGCMSVCHELPERS
|
---|
| 73 | {
|
---|
| 74 | /** The service has processed the Call request. */
|
---|
[4698] | 75 | DECLR3CALLBACKMEMBER(void, pfnCallComplete, (VBOXHGCMCALLHANDLE callHandle, int32_t rc));
|
---|
[1] | 76 |
|
---|
| 77 | void *pvInstance;
|
---|
[6981] | 78 |
|
---|
| 79 | /** The service disconnects the client. */
|
---|
| 80 | DECLR3CALLBACKMEMBER(void, pfnDisconnectClient, (void *pvInstance, uint32_t u32ClientID));
|
---|
[1] | 81 | } VBOXHGCMSVCHELPERS;
|
---|
| 82 |
|
---|
| 83 | typedef VBOXHGCMSVCHELPERS *PVBOXHGCMSVCHELPERS;
|
---|
| 84 |
|
---|
[10652] | 85 | /**
|
---|
| 86 | * Callback type for HGCM services which can send notification messages.
|
---|
| 87 | * Intended for use on the host side.
|
---|
| 88 | */
|
---|
| 89 | typedef DECLCALLBACK(void) FNVBOXHGCMCALLBACK(void *pvParm);
|
---|
| 90 | typedef FNVBOXHGCMCALLBACK *PFNVBOXHGCMCALLBACK;
|
---|
[1] | 91 |
|
---|
[10652] | 92 | #define VBOX_HGCM_SVC_PARM_INVALID (0U)
|
---|
| 93 | #define VBOX_HGCM_SVC_PARM_32BIT (1U)
|
---|
| 94 | #define VBOX_HGCM_SVC_PARM_64BIT (2U)
|
---|
| 95 | #define VBOX_HGCM_SVC_PARM_PTR (3U)
|
---|
| 96 | #define VBOX_HGCM_SVC_PARM_CALLBACK (4U)
|
---|
[1] | 97 |
|
---|
| 98 | typedef struct VBOXHGCMSVCPARM
|
---|
| 99 | {
|
---|
| 100 | /** VBOX_HGCM_SVC_PARM_* values. */
|
---|
| 101 | uint32_t type;
|
---|
| 102 |
|
---|
| 103 | union
|
---|
| 104 | {
|
---|
| 105 | uint32_t uint32;
|
---|
| 106 | uint64_t uint64;
|
---|
| 107 | struct
|
---|
| 108 | {
|
---|
| 109 | uint32_t size;
|
---|
| 110 | void *addr;
|
---|
| 111 | } pointer;
|
---|
[10652] | 112 | struct
|
---|
| 113 | {
|
---|
| 114 | PFNVBOXHGCMCALLBACK pFunction;
|
---|
| 115 | void *pvData;
|
---|
| 116 | } callback;
|
---|
[1] | 117 | } u;
|
---|
| 118 | } VBOXHGCMSVCPARM;
|
---|
| 119 |
|
---|
| 120 | typedef VBOXHGCMSVCPARM *PVBOXHGCMSVCPARM;
|
---|
| 121 |
|
---|
[2386] | 122 | /** Service specific extension callback.
|
---|
| 123 | * This callback is called by the service to perform service specific operation.
|
---|
| 124 | *
|
---|
| 125 | * @param pvExtension The extension pointer.
|
---|
| 126 | * @param u32Function What the callback is supposed to do.
|
---|
| 127 | * @param pvParm The function parameters.
|
---|
| 128 | * @param cbParm The size of the function parameters.
|
---|
| 129 | */
|
---|
| 130 | typedef DECLCALLBACK(int) FNHGCMSVCEXT(void *pvExtension, uint32_t u32Function, void *pvParm, uint32_t cbParms);
|
---|
| 131 | typedef FNHGCMSVCEXT *PFNHGCMSVCEXT;
|
---|
| 132 |
|
---|
[1] | 133 | /** The Service DLL entry points.
|
---|
| 134 | *
|
---|
| 135 | * HGCM will call the DLL "VBoxHGCMSvcLoad"
|
---|
| 136 | * function and the DLL must fill in the VBOXHGCMSVCFNTABLE
|
---|
| 137 | * with function pointers.
|
---|
| 138 | */
|
---|
| 139 |
|
---|
| 140 | /* The structure is used in separately compiled binaries so an explicit packing is required. */
|
---|
| 141 | #pragma pack(1)
|
---|
| 142 | typedef struct _VBOXHGCMSVCFNTABLE
|
---|
| 143 | {
|
---|
| 144 | /** Filled by HGCM */
|
---|
| 145 |
|
---|
| 146 | /** Size of the structure. */
|
---|
| 147 | uint32_t cbSize;
|
---|
| 148 |
|
---|
| 149 | /** Version of the structure, including the helpers. */
|
---|
| 150 | uint32_t u32Version;
|
---|
| 151 |
|
---|
| 152 | PVBOXHGCMSVCHELPERS pHelpers;
|
---|
| 153 |
|
---|
| 154 | /** Filled by the service. */
|
---|
| 155 |
|
---|
| 156 | /** Size of client information the service want to have. */
|
---|
| 157 | uint32_t cbClient;
|
---|
| 158 | #if ARCH_BITS == 64
|
---|
[2386] | 159 | /** Ensure that the following pointers are properly aligned on 64-bit system. */
|
---|
| 160 | uint32_t u32Alignment0;
|
---|
[1] | 161 | #endif
|
---|
| 162 |
|
---|
| 163 | /** Uninitialize service */
|
---|
[7801] | 164 | DECLR3CALLBACKMEMBER(int, pfnUnload, (void *pvService));
|
---|
[1] | 165 |
|
---|
| 166 | /** Inform the service about a client connection. */
|
---|
[7801] | 167 | DECLR3CALLBACKMEMBER(int, pfnConnect, (void *pvService, uint32_t u32ClientID, void *pvClient));
|
---|
[1] | 168 |
|
---|
| 169 | /** Inform the service that the client wants to disconnect. */
|
---|
[7801] | 170 | DECLR3CALLBACKMEMBER(int, pfnDisconnect, (void *pvService, uint32_t u32ClientID, void *pvClient));
|
---|
[1] | 171 |
|
---|
| 172 | /** Service entry point.
|
---|
| 173 | * Return code is passed to pfnCallComplete callback.
|
---|
| 174 | */
|
---|
[7801] | 175 | DECLR3CALLBACKMEMBER(void, pfnCall, (void *pvService, VBOXHGCMCALLHANDLE callHandle, uint32_t u32ClientID, void *pvClient, uint32_t function, uint32_t cParms, VBOXHGCMSVCPARM paParms[]));
|
---|
[1] | 176 |
|
---|
| 177 | /** Host Service entry point meant for privileged features invisible to the guest.
|
---|
| 178 | * Return code is passed to pfnCallComplete callback.
|
---|
| 179 | */
|
---|
[7801] | 180 | DECLR3CALLBACKMEMBER(int, pfnHostCall, (void *pvService, uint32_t function, uint32_t cParms, VBOXHGCMSVCPARM paParms[]));
|
---|
[905] | 181 |
|
---|
| 182 | /** Inform the service about a VM save operation. */
|
---|
[7801] | 183 | DECLR3CALLBACKMEMBER(int, pfnSaveState, (void *pvService, uint32_t u32ClientID, void *pvClient, PSSMHANDLE pSSM));
|
---|
[1] | 184 |
|
---|
[905] | 185 | /** Inform the service about a VM load operation. */
|
---|
[7801] | 186 | DECLR3CALLBACKMEMBER(int, pfnLoadState, (void *pvService, uint32_t u32ClientID, void *pvClient, PSSMHANDLE pSSM));
|
---|
[905] | 187 |
|
---|
[2386] | 188 | /** Manage the service extension. */
|
---|
[7801] | 189 | DECLR3CALLBACKMEMBER(int, pfnRegisterExtension, (void *pvService, PFNHGCMSVCEXT pfnExtension, void *pvExtension));
|
---|
[2386] | 190 |
|
---|
[7801] | 191 | /** User/instance data pointer for the service. */
|
---|
| 192 | void *pvService;
|
---|
| 193 |
|
---|
[1] | 194 | } VBOXHGCMSVCFNTABLE;
|
---|
| 195 | #pragma pack()
|
---|
| 196 |
|
---|
| 197 |
|
---|
| 198 | /** Service initialization entry point. */
|
---|
| 199 | typedef DECLCALLBACK(int) VBOXHGCMSVCLOAD(VBOXHGCMSVCFNTABLE *ptable);
|
---|
| 200 | typedef VBOXHGCMSVCLOAD *PFNVBOXHGCMSVCLOAD;
|
---|
| 201 | #define VBOX_HGCM_SVCLOAD_NAME "VBoxHGCMSvcLoad"
|
---|
| 202 |
|
---|
[3633] | 203 | #endif
|
---|