2 * Host-Guest Communication Manager (HGCM) - Service library definitions.
6 * Copyright (C) 2006-2017 Oracle Corporation
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
26 #ifndef ___VBox_hgcm_h
27 #define ___VBox_hgcm_h
29 #include <iprt/assert.h>
30 #include <iprt/string.h>
31 #include <VBox/cdefs.h>
32 #include <VBox/types.h>
34 #ifdef VBOX_TEST_HGCM_PARMS
35 # include <iprt/test.h>
38 /** @todo proper comments. */
41 * Service interface version.
43 * Includes layout of both VBOXHGCMSVCFNTABLE and VBOXHGCMSVCHELPERS.
45 * A service can work with these structures if major version
46 * is equal and minor version of service is <= version of the
49 * For example when a new helper is added at the end of helpers
50 * structure, then the minor version will be increased. All older
51 * services still can work because they have their old helpers
55 * 1.1->2.1 Because the pfnConnect now also has the pvClient parameter.
56 * 2.1->2.2 Because pfnSaveState and pfnLoadState were added
57 * 2.2->3.1 Because pfnHostCall is now synchronous, returns rc, and parameters were changed
58 * 3.1->3.2 Because pfnRegisterExtension was added
59 * 3.2->3.3 Because pfnDisconnectClient helper was added
60 * 3.3->4.1 Because the pvService entry and parameter was added
61 * 4.1->4.2 Because the VBOX_HGCM_SVC_PARM_CALLBACK parameter type was added
62 * 4.2->5.1 Removed the VBOX_HGCM_SVC_PARM_CALLBACK parameter type, as
63 * this problem is already solved by service extension callbacks
65 #define VBOX_HGCM_SVC_VERSION_MAJOR (0x0005)
66 #define VBOX_HGCM_SVC_VERSION_MINOR (0x0001)
67 #define VBOX_HGCM_SVC_VERSION ((VBOX_HGCM_SVC_VERSION_MAJOR << 16) + VBOX_HGCM_SVC_VERSION_MINOR)
70 /** Typed pointer to distinguish a call to service. */
71 struct VBOXHGCMCALLHANDLE_TYPEDEF
;
72 typedef struct VBOXHGCMCALLHANDLE_TYPEDEF
*VBOXHGCMCALLHANDLE
;
74 /** Service helpers pointers table. */
75 typedef struct VBOXHGCMSVCHELPERS
77 /** The service has processed the Call request. */
78 DECLR3CALLBACKMEMBER(void, pfnCallComplete
, (VBOXHGCMCALLHANDLE callHandle
, int32_t rc
));
82 /** The service disconnects the client. */
83 DECLR3CALLBACKMEMBER(void, pfnDisconnectClient
, (void *pvInstance
, uint32_t u32ClientID
));
86 typedef VBOXHGCMSVCHELPERS
*PVBOXHGCMSVCHELPERS
;
89 #define VBOX_HGCM_SVC_PARM_INVALID (0U)
90 #define VBOX_HGCM_SVC_PARM_32BIT (1U)
91 #define VBOX_HGCM_SVC_PARM_64BIT (2U)
92 #define VBOX_HGCM_SVC_PARM_PTR (3U)
94 typedef struct VBOXHGCMSVCPARM
96 /** VBOX_HGCM_SVC_PARM_* values. */
110 /** Extract an uint32_t value from an HGCM parameter structure */
111 int getUInt32(uint32_t *u32
)
113 AssertPtrReturn(u32
, VERR_INVALID_POINTER
);
114 int rc
= VINF_SUCCESS
;
115 if (type
!= VBOX_HGCM_SVC_PARM_32BIT
)
116 rc
= VERR_INVALID_PARAMETER
;
122 /** Extract a uint64_t value from an HGCM parameter structure */
123 int getUInt64(uint64_t *u64
)
125 AssertPtrReturn(u64
, VERR_INVALID_POINTER
);
126 int rc
= VINF_SUCCESS
;
127 if (type
!= VBOX_HGCM_SVC_PARM_64BIT
)
128 rc
= VERR_INVALID_PARAMETER
;
134 /** Extract a pointer value from an HGCM parameter structure */
135 int getPointer(void **ppv
, uint32_t *pcb
)
137 AssertPtrReturn(ppv
, VERR_INVALID_POINTER
);
138 AssertPtrReturn(pcb
, VERR_INVALID_POINTER
);
139 if (type
== VBOX_HGCM_SVC_PARM_PTR
)
141 *ppv
= u
.pointer
.addr
;
142 *pcb
= u
.pointer
.size
;
146 return VERR_INVALID_PARAMETER
;
149 /** Extract a constant pointer value from an HGCM parameter structure */
150 int getPointer(const void **ppcv
, uint32_t *pcb
)
152 AssertPtrReturn(ppcv
, VERR_INVALID_POINTER
);
153 AssertPtrReturn(pcb
, VERR_INVALID_POINTER
);
155 int rc
= getPointer(&pv
, pcb
);
160 /** Extract a pointer value to a non-empty buffer from an HGCM parameter
162 int getBuffer(void **ppv
, uint32_t *pcb
)
164 AssertPtrReturn(ppv
, VERR_INVALID_POINTER
);
165 AssertPtrReturn(pcb
, VERR_INVALID_POINTER
);
168 int rc
= getPointer(&pv
, &cb
);
178 return VERR_INVALID_PARAMETER
;
181 /** Extract a pointer value to a non-empty constant buffer from an HGCM
182 * parameter structure */
183 int getBuffer(const void **ppcv
, uint32_t *pcb
)
185 AssertPtrReturn(ppcv
, VERR_INVALID_POINTER
);
186 AssertPtrReturn(pcb
, VERR_INVALID_POINTER
);
188 int rc
= getBuffer(&pcv
, pcb
);
193 /** Extract a string value from an HGCM parameter structure */
194 int getString(char **ppch
, uint32_t *pcb
)
198 int rc
= getBuffer((void **)&pch
, &cb
);
205 rc
= RTStrValidateEncodingEx(pch
, cb
,
206 RTSTR_VALIDATE_ENCODING_ZERO_TERMINATED
);
212 /** Extract a constant string value from an HGCM parameter structure */
213 int getString(const char **ppch
, uint32_t *pcb
)
216 int rc
= getString(&pch
, pcb
);
221 /** Set a uint32_t value to an HGCM parameter structure */
222 void setUInt32(uint32_t u32
)
224 type
= VBOX_HGCM_SVC_PARM_32BIT
;
228 /** Set a uint64_t value to an HGCM parameter structure */
229 void setUInt64(uint64_t u64
)
231 type
= VBOX_HGCM_SVC_PARM_64BIT
;
235 /** Set a pointer value to an HGCM parameter structure */
236 void setPointer(void *pv
, uint32_t cb
)
238 type
= VBOX_HGCM_SVC_PARM_PTR
;
243 /** Set a const string value to an HGCM parameter structure */
244 void setString(const char *psz
)
246 type
= VBOX_HGCM_SVC_PARM_PTR
;
247 u
.pointer
.addr
= (void *)psz
;
248 u
.pointer
.size
= (uint32_t)strlen(psz
) + 1;
251 #ifdef ___iprt_cpp_ministring_h
252 /** Set a const string value to an HGCM parameter structure */
253 void setCppString(const RTCString
&rString
)
255 type
= VBOX_HGCM_SVC_PARM_PTR
;
256 u
.pointer
.addr
= (void *)rString
.c_str();
257 u
.pointer
.size
= (uint32_t)rString
.length() + 1;
261 #ifdef VBOX_TEST_HGCM_PARMS
262 /** Test the getString member function. Indirectly tests the getPointer
263 * and getBuffer APIs.
264 * @param hTest an running IPRT test
265 * @param aType the type that the parameter should be set to before
267 * @param apcc the value that the parameter should be set to before
268 * calling getString, and also the address (!) which we
269 * expect getString to return. Stricter than needed of
270 * course, but I was feeling lazy.
271 * @param acb the size that the parameter should be set to before
272 * calling getString, and also the size which we expect
273 * getString to return.
274 * @param rcExp the expected return value of the call to getString.
276 void doTestGetString(RTTEST hTest
, uint32_t aType
, const char *apcc
,
277 uint32_t acb
, int rcExp
)
279 /* An RTTest API like this, which would print out an additional line
280 * of context if a test failed, would be nice. This is because the
281 * line number alone doesn't help much here, given that this is a
282 * subroutine called many times. */
284 RTTestContextF(hTest,
285 ("doTestGetString, aType=%u, apcc=%p, acp=%u, rcExp=%Rrc",
286 aType, apcc, acp, rcExp));
288 setPointer((void *)apcc
, acb
);
289 type
= aType
; /* in case we don't want VBOX_HGCM_SVC_PARM_PTR */
290 const char *pcc
= NULL
;
292 int rc
= getString(&pcc
, &cb
);
293 RTTEST_CHECK_RC(hTest
, rc
, rcExp
);
294 if (RT_SUCCESS(rcExp
))
296 RTTEST_CHECK_MSG_RETV(hTest
, (pcc
== apcc
),
297 (hTest
, "expected %p, got %p", apcc
, pcc
));
298 RTTEST_CHECK_MSG_RETV(hTest
, (cb
== acb
),
299 (hTest
, "expected %u, got %u", acb
, cb
));
303 /** Run some unit tests on the getString method and indirectly test
304 * getPointer and getBuffer as well. */
305 void testGetString(RTTEST hTest
)
307 RTTestSub(hTest
, "HGCM string parameter handling");
308 doTestGetString(hTest
, VBOX_HGCM_SVC_PARM_32BIT
, "test", 3,
309 VERR_INVALID_PARAMETER
);
310 doTestGetString(hTest
, VBOX_HGCM_SVC_PARM_PTR
, "test", 5,
312 doTestGetString(hTest
, VBOX_HGCM_SVC_PARM_PTR
, "test", 3,
313 VERR_BUFFER_OVERFLOW
);
314 doTestGetString(hTest
, VBOX_HGCM_SVC_PARM_PTR
, "test\xf0", 6,
315 VERR_INVALID_UTF8_ENCODING
);
316 doTestGetString(hTest
, VBOX_HGCM_SVC_PARM_PTR
, "test", 0,
317 VERR_INVALID_PARAMETER
);
318 doTestGetString(hTest
, VBOX_HGCM_SVC_PARM_PTR
, (const char *)0x1, 5,
319 VERR_INVALID_PARAMETER
);
320 RTTestSubDone(hTest
);
324 VBOXHGCMSVCPARM() : type(VBOX_HGCM_SVC_PARM_INVALID
) {}
328 typedef VBOXHGCMSVCPARM
*PVBOXHGCMSVCPARM
;
330 #ifdef VBOX_WITH_CRHGSMI
331 typedef void * HGCMCVSHANDLE
;
333 typedef DECLCALLBACK(void) HGCMHOSTFASTCALLCB (int32_t result
, uint32_t u32Function
, PVBOXHGCMSVCPARM pParam
, void *pvContext
);
334 typedef HGCMHOSTFASTCALLCB
*PHGCMHOSTFASTCALLCB
;
338 /** Service specific extension callback.
339 * This callback is called by the service to perform service specific operation.
341 * @param pvExtension The extension pointer.
342 * @param u32Function What the callback is supposed to do.
343 * @param pvParm The function parameters.
344 * @param cbParm The size of the function parameters.
346 typedef DECLCALLBACK(int) FNHGCMSVCEXT(void *pvExtension
, uint32_t u32Function
, void *pvParm
, uint32_t cbParms
);
347 typedef FNHGCMSVCEXT
*PFNHGCMSVCEXT
;
349 /** The Service DLL entry points.
351 * HGCM will call the DLL "VBoxHGCMSvcLoad"
352 * function and the DLL must fill in the VBOXHGCMSVCFNTABLE
353 * with function pointers.
356 /* The structure is used in separately compiled binaries so an explicit packing is required. */
357 #pragma pack(1) /** @todo r=bird: The pragma pack(1) is not at all required!! */
358 typedef struct VBOXHGCMSVCFNTABLE
360 /** @name Filled by HGCM
363 /** Size of the structure. */
366 /** Version of the structure, including the helpers. */
369 PVBOXHGCMSVCHELPERS pHelpers
;
372 /** @name Filled in by the service.
375 /** Size of client information the service want to have. */
378 /** Ensure that the following pointers are properly aligned on 64-bit system. */
379 uint32_t u32Alignment0
;
382 /** Uninitialize service */
383 DECLR3CALLBACKMEMBER(int, pfnUnload
, (void *pvService
));
385 /** Inform the service about a client connection. */
386 DECLR3CALLBACKMEMBER(int, pfnConnect
, (void *pvService
, uint32_t u32ClientID
, void *pvClient
));
388 /** Inform the service that the client wants to disconnect. */
389 DECLR3CALLBACKMEMBER(int, pfnDisconnect
, (void *pvService
, uint32_t u32ClientID
, void *pvClient
));
391 /** Service entry point.
392 * Return code is passed to pfnCallComplete callback.
394 DECLR3CALLBACKMEMBER(void, pfnCall
, (void *pvService
, VBOXHGCMCALLHANDLE callHandle
, uint32_t u32ClientID
, void *pvClient
, uint32_t function
, uint32_t cParms
, VBOXHGCMSVCPARM paParms
[]));
396 /** Host Service entry point meant for privileged features invisible to the guest.
397 * Return code is passed to pfnCallComplete callback.
399 DECLR3CALLBACKMEMBER(int, pfnHostCall
, (void *pvService
, uint32_t function
, uint32_t cParms
, VBOXHGCMSVCPARM paParms
[]));
401 /** Inform the service about a VM save operation. */
402 DECLR3CALLBACKMEMBER(int, pfnSaveState
, (void *pvService
, uint32_t u32ClientID
, void *pvClient
, PSSMHANDLE pSSM
));
404 /** Inform the service about a VM load operation. */
405 DECLR3CALLBACKMEMBER(int, pfnLoadState
, (void *pvService
, uint32_t u32ClientID
, void *pvClient
, PSSMHANDLE pSSM
));
407 /** Register a service extension callback. */
408 DECLR3CALLBACKMEMBER(int, pfnRegisterExtension
, (void *pvService
, PFNHGCMSVCEXT pfnExtension
, void *pvExtension
));
410 /** User/instance data pointer for the service. */
414 } VBOXHGCMSVCFNTABLE
;
418 /** Service initialization entry point. */
419 typedef DECLCALLBACK(int) VBOXHGCMSVCLOAD(VBOXHGCMSVCFNTABLE
*ptable
);
420 typedef VBOXHGCMSVCLOAD
*PFNVBOXHGCMSVCLOAD
;
421 #define VBOX_HGCM_SVCLOAD_NAME "VBoxHGCMSvcLoad"