[1] | 1 | /** @file
|
---|
| 2 | * VBox - Host-Guest Communication Manager (HGCM):
|
---|
| 3 | * Service library definitions.
|
---|
| 4 | */
|
---|
| 5 |
|
---|
| 6 | /*
|
---|
[2981] | 7 | * Copyright (C) 2006-2007 innotek GmbH
|
---|
[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.
|
---|
[1] | 25 | */
|
---|
| 26 |
|
---|
[3632] | 27 | #ifndef ___VBox_hgcm_h
|
---|
| 28 | #define ___VBox_hgcm_h
|
---|
[1] | 29 |
|
---|
| 30 | #include <VBox/cdefs.h>
|
---|
| 31 | #include <VBox/types.h>
|
---|
| 32 |
|
---|
| 33 | /** @todo proper comments. */
|
---|
| 34 |
|
---|
| 35 | /**
|
---|
| 36 | * Service interface version.
|
---|
| 37 | *
|
---|
| 38 | * Includes layout of both VBOXHGCMSVCFNTABLE and VBOXHGCMSVCHELPERS.
|
---|
| 39 | *
|
---|
| 40 | * A service can work with these structures if major version
|
---|
| 41 | * is equal and minor version of service is <= version of the
|
---|
| 42 | * structures.
|
---|
| 43 | *
|
---|
| 44 | * For example when a new helper is added at the end of helpers
|
---|
| 45 | * structure, then the minor version will be increased. All older
|
---|
| 46 | * services still can work because they have their old helpers
|
---|
| 47 | * unchanged.
|
---|
| 48 | *
|
---|
| 49 | * Revision history.
|
---|
| 50 | * 1.1->2.1 Because the pfnConnect now also has the pvClient parameter.
|
---|
[905] | 51 | * 2.1->2.2 Because pfnSaveState and pfnLoadState were added
|
---|
[1711] | 52 | * 2.2->3.1 Because pfnHostCall is now synchronous, returns rc, and parameters were changed
|
---|
[2386] | 53 | * 3.1->3.2 Because pfnRegisterExtension was added
|
---|
[6981] | 54 | * 3.2->3.3 Because pfnDisconnectClient helper was added
|
---|
[7801] | 55 | * 3.3->4.1 Because the pvService entry and parameter was added
|
---|
[1] | 56 | */
|
---|
[7801] | 57 | #define VBOX_HGCM_SVC_VERSION_MAJOR (0x0004)
|
---|
| 58 | #define VBOX_HGCM_SVC_VERSION_MINOR (0x0001)
|
---|
[1] | 59 | #define VBOX_HGCM_SVC_VERSION ((VBOX_HGCM_SVC_VERSION_MAJOR << 16) + VBOX_HGCM_SVC_VERSION_MINOR)
|
---|
| 60 |
|
---|
| 61 |
|
---|
| 62 | /** Typed pointer to distinguish a call to service. */
|
---|
| 63 | struct VBOXHGCMCALLHANDLE_TYPEDEF;
|
---|
| 64 | typedef struct VBOXHGCMCALLHANDLE_TYPEDEF *VBOXHGCMCALLHANDLE;
|
---|
| 65 |
|
---|
| 66 | /** Service helpers pointers table. */
|
---|
| 67 | typedef struct _VBOXHGCMSVCHELPERS
|
---|
| 68 | {
|
---|
| 69 | /** The service has processed the Call request. */
|
---|
[4698] | 70 | DECLR3CALLBACKMEMBER(void, pfnCallComplete, (VBOXHGCMCALLHANDLE callHandle, int32_t rc));
|
---|
[1] | 71 |
|
---|
| 72 | void *pvInstance;
|
---|
[6981] | 73 |
|
---|
| 74 | /** The service disconnects the client. */
|
---|
| 75 | DECLR3CALLBACKMEMBER(void, pfnDisconnectClient, (void *pvInstance, uint32_t u32ClientID));
|
---|
[1] | 76 | } VBOXHGCMSVCHELPERS;
|
---|
| 77 |
|
---|
| 78 | typedef VBOXHGCMSVCHELPERS *PVBOXHGCMSVCHELPERS;
|
---|
| 79 |
|
---|
| 80 |
|
---|
| 81 | #define VBOX_HGCM_SVC_PARM_INVALID (0U)
|
---|
| 82 | #define VBOX_HGCM_SVC_PARM_32BIT (1U)
|
---|
| 83 | #define VBOX_HGCM_SVC_PARM_64BIT (2U)
|
---|
| 84 | #define VBOX_HGCM_SVC_PARM_PTR (3U)
|
---|
| 85 |
|
---|
| 86 | typedef struct VBOXHGCMSVCPARM
|
---|
| 87 | {
|
---|
| 88 | /** VBOX_HGCM_SVC_PARM_* values. */
|
---|
| 89 | uint32_t type;
|
---|
| 90 |
|
---|
| 91 | union
|
---|
| 92 | {
|
---|
| 93 | uint32_t uint32;
|
---|
| 94 | uint64_t uint64;
|
---|
| 95 | struct
|
---|
| 96 | {
|
---|
| 97 | uint32_t size;
|
---|
| 98 | void *addr;
|
---|
| 99 | } pointer;
|
---|
| 100 | } u;
|
---|
| 101 | } VBOXHGCMSVCPARM;
|
---|
| 102 |
|
---|
| 103 | typedef VBOXHGCMSVCPARM *PVBOXHGCMSVCPARM;
|
---|
| 104 |
|
---|
[2386] | 105 | /** Service specific extension callback.
|
---|
| 106 | * This callback is called by the service to perform service specific operation.
|
---|
| 107 | *
|
---|
| 108 | * @param pvExtension The extension pointer.
|
---|
| 109 | * @param u32Function What the callback is supposed to do.
|
---|
| 110 | * @param pvParm The function parameters.
|
---|
| 111 | * @param cbParm The size of the function parameters.
|
---|
| 112 | */
|
---|
| 113 | typedef DECLCALLBACK(int) FNHGCMSVCEXT(void *pvExtension, uint32_t u32Function, void *pvParm, uint32_t cbParms);
|
---|
| 114 | typedef FNHGCMSVCEXT *PFNHGCMSVCEXT;
|
---|
| 115 |
|
---|
[1] | 116 | /** The Service DLL entry points.
|
---|
| 117 | *
|
---|
| 118 | * HGCM will call the DLL "VBoxHGCMSvcLoad"
|
---|
| 119 | * function and the DLL must fill in the VBOXHGCMSVCFNTABLE
|
---|
| 120 | * with function pointers.
|
---|
| 121 | */
|
---|
| 122 |
|
---|
| 123 | /* The structure is used in separately compiled binaries so an explicit packing is required. */
|
---|
| 124 | #pragma pack(1)
|
---|
| 125 | typedef struct _VBOXHGCMSVCFNTABLE
|
---|
| 126 | {
|
---|
| 127 | /** Filled by HGCM */
|
---|
| 128 |
|
---|
| 129 | /** Size of the structure. */
|
---|
| 130 | uint32_t cbSize;
|
---|
| 131 |
|
---|
| 132 | /** Version of the structure, including the helpers. */
|
---|
| 133 | uint32_t u32Version;
|
---|
| 134 |
|
---|
| 135 | PVBOXHGCMSVCHELPERS pHelpers;
|
---|
| 136 |
|
---|
| 137 | /** Filled by the service. */
|
---|
| 138 |
|
---|
| 139 | /** Size of client information the service want to have. */
|
---|
| 140 | uint32_t cbClient;
|
---|
| 141 | #if ARCH_BITS == 64
|
---|
[2386] | 142 | /** Ensure that the following pointers are properly aligned on 64-bit system. */
|
---|
| 143 | uint32_t u32Alignment0;
|
---|
[1] | 144 | #endif
|
---|
| 145 |
|
---|
| 146 | /** Uninitialize service */
|
---|
[7801] | 147 | DECLR3CALLBACKMEMBER(int, pfnUnload, (void *pvService));
|
---|
[1] | 148 |
|
---|
| 149 | /** Inform the service about a client connection. */
|
---|
[7801] | 150 | DECLR3CALLBACKMEMBER(int, pfnConnect, (void *pvService, uint32_t u32ClientID, void *pvClient));
|
---|
[1] | 151 |
|
---|
| 152 | /** Inform the service that the client wants to disconnect. */
|
---|
[7801] | 153 | DECLR3CALLBACKMEMBER(int, pfnDisconnect, (void *pvService, uint32_t u32ClientID, void *pvClient));
|
---|
[1] | 154 |
|
---|
| 155 | /** Service entry point.
|
---|
| 156 | * Return code is passed to pfnCallComplete callback.
|
---|
| 157 | */
|
---|
[7801] | 158 | DECLR3CALLBACKMEMBER(void, pfnCall, (void *pvService, VBOXHGCMCALLHANDLE callHandle, uint32_t u32ClientID, void *pvClient, uint32_t function, uint32_t cParms, VBOXHGCMSVCPARM paParms[]));
|
---|
[1] | 159 |
|
---|
| 160 | /** Host Service entry point meant for privileged features invisible to the guest.
|
---|
| 161 | * Return code is passed to pfnCallComplete callback.
|
---|
| 162 | */
|
---|
[7801] | 163 | DECLR3CALLBACKMEMBER(int, pfnHostCall, (void *pvService, uint32_t function, uint32_t cParms, VBOXHGCMSVCPARM paParms[]));
|
---|
[905] | 164 |
|
---|
| 165 | /** Inform the service about a VM save operation. */
|
---|
[7801] | 166 | DECLR3CALLBACKMEMBER(int, pfnSaveState, (void *pvService, uint32_t u32ClientID, void *pvClient, PSSMHANDLE pSSM));
|
---|
[1] | 167 |
|
---|
[905] | 168 | /** Inform the service about a VM load operation. */
|
---|
[7801] | 169 | DECLR3CALLBACKMEMBER(int, pfnLoadState, (void *pvService, uint32_t u32ClientID, void *pvClient, PSSMHANDLE pSSM));
|
---|
[905] | 170 |
|
---|
[2386] | 171 | /** Manage the service extension. */
|
---|
[7801] | 172 | DECLR3CALLBACKMEMBER(int, pfnRegisterExtension, (void *pvService, PFNHGCMSVCEXT pfnExtension, void *pvExtension));
|
---|
[2386] | 173 |
|
---|
[7801] | 174 | /** User/instance data pointer for the service. */
|
---|
| 175 | void *pvService;
|
---|
| 176 |
|
---|
[1] | 177 | } VBOXHGCMSVCFNTABLE;
|
---|
| 178 | #pragma pack()
|
---|
| 179 |
|
---|
| 180 |
|
---|
| 181 | /** Service initialization entry point. */
|
---|
| 182 | typedef DECLCALLBACK(int) VBOXHGCMSVCLOAD(VBOXHGCMSVCFNTABLE *ptable);
|
---|
| 183 | typedef VBOXHGCMSVCLOAD *PFNVBOXHGCMSVCLOAD;
|
---|
| 184 | #define VBOX_HGCM_SVCLOAD_NAME "VBoxHGCMSvcLoad"
|
---|
| 185 |
|
---|
[3633] | 186 | #endif
|
---|