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