VirtualBox

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

Last change on this file since 7581 was 6989, checked in by vboxsync, 17 years ago

HGCM: bumped service minor version

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 6.2 KB
Line 
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. */
62struct VBOXHGCMCALLHANDLE_TYPEDEF;
63typedef struct VBOXHGCMCALLHANDLE_TYPEDEF *VBOXHGCMCALLHANDLE;
64
65/** Service helpers pointers table. */
66typedef 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
77typedef 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
85typedef 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
102typedef 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 */
112typedef DECLCALLBACK(int) FNHGCMSVCEXT(void *pvExtension, uint32_t u32Function, void *pvParm, uint32_t cbParms);
113typedef 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)
124typedef 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. */
178typedef DECLCALLBACK(int) VBOXHGCMSVCLOAD(VBOXHGCMSVCFNTABLE *ptable);
179typedef VBOXHGCMSVCLOAD *PFNVBOXHGCMSVCLOAD;
180#define VBOX_HGCM_SVCLOAD_NAME "VBoxHGCMSvcLoad"
181
182#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