VirtualBox

source: vbox/trunk/include/VBox/hgcmsvc.h@ 11083

Last change on this file since 11083 was 10652, checked in by vboxsync, 16 years ago

hgcm: added a callback parameter type (for host use only)

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 7.1 KB
Line 
1/** @file
2 * VBox - Host-Guest Communication Manager (HGCM):
3 * Service library definitions.
4 */
5
6/*
7 * Copyright (C) 2006-2007 Sun Microsystems, Inc.
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 * 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.
29 */
30
31#ifndef ___VBox_hgcm_h
32#define ___VBox_hgcm_h
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.
55 * 2.1->2.2 Because pfnSaveState and pfnLoadState were added
56 * 2.2->3.1 Because pfnHostCall is now synchronous, returns rc, and parameters were changed
57 * 3.1->3.2 Because pfnRegisterExtension was added
58 * 3.2->3.3 Because pfnDisconnectClient helper was added
59 * 3.3->4.1 Because the pvService entry and parameter was added
60 * 4.1->4.2 Because the VBOX_HGCM_SVC_PARM_CALLBACK paramteter type was added
61 */
62#define VBOX_HGCM_SVC_VERSION_MAJOR (0x0004)
63#define VBOX_HGCM_SVC_VERSION_MINOR (0x0002)
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. */
68struct VBOXHGCMCALLHANDLE_TYPEDEF;
69typedef struct VBOXHGCMCALLHANDLE_TYPEDEF *VBOXHGCMCALLHANDLE;
70
71/** Service helpers pointers table. */
72typedef struct _VBOXHGCMSVCHELPERS
73{
74 /** The service has processed the Call request. */
75 DECLR3CALLBACKMEMBER(void, pfnCallComplete, (VBOXHGCMCALLHANDLE callHandle, int32_t rc));
76
77 void *pvInstance;
78
79 /** The service disconnects the client. */
80 DECLR3CALLBACKMEMBER(void, pfnDisconnectClient, (void *pvInstance, uint32_t u32ClientID));
81} VBOXHGCMSVCHELPERS;
82
83typedef VBOXHGCMSVCHELPERS *PVBOXHGCMSVCHELPERS;
84
85/**
86 * Callback type for HGCM services which can send notification messages.
87 * Intended for use on the host side.
88 */
89typedef DECLCALLBACK(void) FNVBOXHGCMCALLBACK(void *pvParm);
90typedef FNVBOXHGCMCALLBACK *PFNVBOXHGCMCALLBACK;
91
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)
97
98typedef 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;
112 struct
113 {
114 PFNVBOXHGCMCALLBACK pFunction;
115 void *pvData;
116 } callback;
117 } u;
118} VBOXHGCMSVCPARM;
119
120typedef VBOXHGCMSVCPARM *PVBOXHGCMSVCPARM;
121
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 */
130typedef DECLCALLBACK(int) FNHGCMSVCEXT(void *pvExtension, uint32_t u32Function, void *pvParm, uint32_t cbParms);
131typedef FNHGCMSVCEXT *PFNHGCMSVCEXT;
132
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)
142typedef 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
159 /** Ensure that the following pointers are properly aligned on 64-bit system. */
160 uint32_t u32Alignment0;
161#endif
162
163 /** Uninitialize service */
164 DECLR3CALLBACKMEMBER(int, pfnUnload, (void *pvService));
165
166 /** Inform the service about a client connection. */
167 DECLR3CALLBACKMEMBER(int, pfnConnect, (void *pvService, uint32_t u32ClientID, void *pvClient));
168
169 /** Inform the service that the client wants to disconnect. */
170 DECLR3CALLBACKMEMBER(int, pfnDisconnect, (void *pvService, uint32_t u32ClientID, void *pvClient));
171
172 /** Service entry point.
173 * Return code is passed to pfnCallComplete callback.
174 */
175 DECLR3CALLBACKMEMBER(void, pfnCall, (void *pvService, VBOXHGCMCALLHANDLE callHandle, uint32_t u32ClientID, void *pvClient, uint32_t function, uint32_t cParms, VBOXHGCMSVCPARM paParms[]));
176
177 /** Host Service entry point meant for privileged features invisible to the guest.
178 * Return code is passed to pfnCallComplete callback.
179 */
180 DECLR3CALLBACKMEMBER(int, pfnHostCall, (void *pvService, uint32_t function, uint32_t cParms, VBOXHGCMSVCPARM paParms[]));
181
182 /** Inform the service about a VM save operation. */
183 DECLR3CALLBACKMEMBER(int, pfnSaveState, (void *pvService, uint32_t u32ClientID, void *pvClient, PSSMHANDLE pSSM));
184
185 /** Inform the service about a VM load operation. */
186 DECLR3CALLBACKMEMBER(int, pfnLoadState, (void *pvService, uint32_t u32ClientID, void *pvClient, PSSMHANDLE pSSM));
187
188 /** Manage the service extension. */
189 DECLR3CALLBACKMEMBER(int, pfnRegisterExtension, (void *pvService, PFNHGCMSVCEXT pfnExtension, void *pvExtension));
190
191 /** User/instance data pointer for the service. */
192 void *pvService;
193
194} VBOXHGCMSVCFNTABLE;
195#pragma pack()
196
197
198/** Service initialization entry point. */
199typedef DECLCALLBACK(int) VBOXHGCMSVCLOAD(VBOXHGCMSVCFNTABLE *ptable);
200typedef VBOXHGCMSVCLOAD *PFNVBOXHGCMSVCLOAD;
201#define VBOX_HGCM_SVCLOAD_NAME "VBoxHGCMSvcLoad"
202
203#endif
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette