VirtualBox

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

Last change on this file since 91729 was 91105, checked in by vboxsync, 3 years ago

HGCM: Forgot to bump the version in r146747. oem2ticketref:46 bugref:10038
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 25.7 KB
Line 
1/** @file
2 * Host-Guest Communication Manager (HGCM) - Service library definitions.
3 */
4
5/*
6 * Copyright (C) 2006-2020 Oracle Corporation
7 *
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.
15 *
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.
21 *
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.
24 */
25
26#ifndef VBOX_INCLUDED_hgcmsvc_h
27#define VBOX_INCLUDED_hgcmsvc_h
28#ifndef RT_WITHOUT_PRAGMA_ONCE
29# pragma once
30#endif
31
32#include <iprt/assert.h>
33#include <iprt/stdarg.h>
34#include <iprt/string.h>
35#include <VBox/cdefs.h>
36#include <VBox/types.h>
37#include <iprt/err.h>
38#ifdef IN_RING3
39# include <iprt/mem.h>
40# include <VBox/err.h>
41# include <VBox/vmm/stam.h>
42# include <VBox/vmm/dbgf.h>
43# include <VBox/vmm/ssm.h>
44#endif
45#ifdef VBOX_TEST_HGCM_PARMS
46# include <iprt/test.h>
47#endif
48
49/** @todo proper comments. */
50
51/**
52 * Service interface version.
53 *
54 * Includes layout of both VBOXHGCMSVCFNTABLE and VBOXHGCMSVCHELPERS.
55 *
56 * A service can work with these structures if major version
57 * is equal and minor version of service is <= version of the
58 * structures.
59 *
60 * For example when a new helper is added at the end of helpers
61 * structure, then the minor version will be increased. All older
62 * services still can work because they have their old helpers
63 * unchanged.
64 *
65 * Revision history.
66 * 1.1->2.1 Because the pfnConnect now also has the pvClient parameter.
67 * 2.1->2.2 Because pfnSaveState and pfnLoadState were added
68 * 2.2->3.1 Because pfnHostCall is now synchronous, returns rc, and parameters were changed
69 * 3.1->3.2 Because pfnRegisterExtension was added
70 * 3.2->3.3 Because pfnDisconnectClient helper was added
71 * 3.3->4.1 Because the pvService entry and parameter was added
72 * 4.1->4.2 Because the VBOX_HGCM_SVC_PARM_CALLBACK parameter type was added
73 * 4.2->5.1 Removed the VBOX_HGCM_SVC_PARM_CALLBACK parameter type, as
74 * this problem is already solved by service extension callbacks
75 * 5.1->6.1 Because pfnCall got a new parameter. Also new helpers. (VBox 6.0)
76 * 6.1->6.2 Because pfnCallComplete starts returning a status code (VBox 6.0).
77 * 6.2->6.3 Because pfnGetRequestor was added (VBox 6.0).
78 * 6.3->6.4 Bacause pfnConnect got an additional parameter (VBox 6.0).
79 * 6.4->6.5 Bacause pfnGetVMMDevSessionId was added pfnLoadState got the version
80 * parameter (VBox 6.0).
81 * 6.5->7.1 Because pfnNotify was added (VBox 6.0).
82 * 7.1->8.1 Because pfnCancelled & pfnIsCallCancelled were added (VBox 6.0).
83 * 8.1->9.1 Because pfnDisconnectClient was (temporarily) removed, and
84 * acMaxClients and acMaxCallsPerClient added (VBox 6.1.26).
85 * 9.1->10.1 Because pfnDisconnectClient was added back (VBox 6.1.28).
86 */
87#define VBOX_HGCM_SVC_VERSION_MAJOR (0x000a)
88#define VBOX_HGCM_SVC_VERSION_MINOR (0x0001)
89#define VBOX_HGCM_SVC_VERSION ((VBOX_HGCM_SVC_VERSION_MAJOR << 16) + VBOX_HGCM_SVC_VERSION_MINOR)
90
91
92/** Typed pointer to distinguish a call to service. */
93struct VBOXHGCMCALLHANDLE_TYPEDEF;
94typedef struct VBOXHGCMCALLHANDLE_TYPEDEF *VBOXHGCMCALLHANDLE;
95
96/** Service helpers pointers table. */
97typedef struct VBOXHGCMSVCHELPERS
98{
99 /** The service has processed the Call request. */
100 DECLR3CALLBACKMEMBER(int, pfnCallComplete, (VBOXHGCMCALLHANDLE callHandle, int32_t rc));
101
102 void *pvInstance;
103
104 /**
105 * The service disconnects the client.
106 *
107 * This can only be used during VBOXHGCMSVCFNTABLE::pfnConnect or
108 * VBOXHGCMSVCFNTABLE::pfnDisconnect and will fail if called out side that
109 * context. Using this on the new client during VBOXHGCMSVCFNTABLE::pfnConnect
110 * is not advisable, it would be better to just return a failure status for that
111 * and it will be done automatically. (It is not possible to call this method
112 * on a client passed to VBOXHGCMSVCFNTABLE::pfnDisconnect.)
113 *
114 * There will be no VBOXHGCMSVCFNTABLE::pfnDisconnect callback for a client
115 * diconnected in this manner.
116 *
117 * @returns VBox status code.
118 * @retval VERR_NOT_FOUND if the client ID was not found.
119 * @retval VERR_INVALID_CONTEXT if not called during connect or disconnect.
120 *
121 * @remarks Used by external parties, so don't remove just because we don't use
122 * it ourselves.
123 */
124 DECLR3CALLBACKMEMBER(int, pfnDisconnectClient, (void *pvInstance, uint32_t idClient));
125
126 /**
127 * Check if the @a callHandle is for a call restored and re-submitted from saved state.
128 *
129 * @returns true if restored, false if not.
130 * @param callHandle The call we're checking up on.
131 */
132 DECLR3CALLBACKMEMBER(bool, pfnIsCallRestored, (VBOXHGCMCALLHANDLE callHandle));
133
134 /**
135 * Check if the @a callHandle is for a cancelled call.
136 *
137 * @returns true if cancelled, false if not.
138 * @param callHandle The call we're checking up on.
139 */
140 DECLR3CALLBACKMEMBER(bool, pfnIsCallCancelled, (VBOXHGCMCALLHANDLE callHandle));
141
142 /** Access to STAMR3RegisterV. */
143 DECLR3CALLBACKMEMBER(int, pfnStamRegisterV,(void *pvInstance, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,
144 STAMUNIT enmUnit, const char *pszDesc, const char *pszName, va_list va)
145 RT_IPRT_FORMAT_ATTR(7, 0));
146 /** Access to STAMR3DeregisterV. */
147 DECLR3CALLBACKMEMBER(int, pfnStamDeregisterV,(void *pvInstance, const char *pszPatFmt, va_list va) RT_IPRT_FORMAT_ATTR(2, 0));
148
149 /** Access to DBGFR3InfoRegisterExternal. */
150 DECLR3CALLBACKMEMBER(int, pfnInfoRegister,(void *pvInstance, const char *pszName, const char *pszDesc,
151 PFNDBGFHANDLEREXT pfnHandler, void *pvUser));
152 /** Access to DBGFR3InfoDeregisterExternal. */
153 DECLR3CALLBACKMEMBER(int, pfnInfoDeregister,(void *pvInstance, const char *pszName));
154
155 /**
156 * Retrieves the VMMDevRequestHeader::fRequestor value.
157 *
158 * @returns The field value, VMMDEV_REQUESTOR_LEGACY if not supported by the
159 * guest, VMMDEV_REQUESTOR_LOWEST if invalid call.
160 * @param hCall The call we're checking up on.
161 */
162 DECLR3CALLBACKMEMBER(uint32_t, pfnGetRequestor, (VBOXHGCMCALLHANDLE hCall));
163
164 /**
165 * Retrieves VMMDevState::idSession.
166 *
167 * @returns current VMMDev session ID value.
168 */
169 DECLR3CALLBACKMEMBER(uint64_t, pfnGetVMMDevSessionId, (void *pvInstance));
170
171} VBOXHGCMSVCHELPERS;
172
173typedef VBOXHGCMSVCHELPERS *PVBOXHGCMSVCHELPERS;
174
175#if defined(IN_RING3) || defined(IN_SLICKEDIT)
176
177/** Wrapper around STAMR3RegisterF. */
178DECLINLINE(int) RT_IPRT_FORMAT_ATTR(7, 8)
179HGCMSvcHlpStamRegister(PVBOXHGCMSVCHELPERS pHlp, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,
180 STAMUNIT enmUnit, const char *pszDesc, const char *pszName, ...)
181{
182 int rc;
183 va_list va;
184 va_start(va, pszName);
185 rc = pHlp->pfnStamRegisterV(pHlp->pvInstance, pvSample, enmType, enmVisibility, enmUnit, pszDesc, pszName, va);
186 va_end(va);
187 return rc;
188}
189
190/** Wrapper around STAMR3RegisterV. */
191DECLINLINE(int) RT_IPRT_FORMAT_ATTR(7, 0)
192HGCMSvcHlpStamRegisterV(PVBOXHGCMSVCHELPERS pHlp, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,
193 STAMUNIT enmUnit, const char *pszDesc, const char *pszName, va_list va)
194{
195 return pHlp->pfnStamRegisterV(pHlp->pvInstance, pvSample, enmType, enmVisibility, enmUnit, pszDesc, pszName, va);
196}
197
198/** Wrapper around STAMR3DeregisterF. */
199DECLINLINE(int) RT_IPRT_FORMAT_ATTR(2, 3) HGCMSvcHlpStamDeregister(PVBOXHGCMSVCHELPERS pHlp, const char *pszPatFmt, ...)
200{
201 int rc;
202 va_list va;
203 va_start(va, pszPatFmt);
204 rc = pHlp->pfnStamDeregisterV(pHlp->pvInstance, pszPatFmt, va);
205 va_end(va);
206 return rc;
207}
208
209/** Wrapper around STAMR3DeregisterV. */
210DECLINLINE(int) RT_IPRT_FORMAT_ATTR(2, 0) HGCMSvcHlpStamDeregisterV(PVBOXHGCMSVCHELPERS pHlp, const char *pszPatFmt, va_list va)
211{
212 return pHlp->pfnStamDeregisterV(pHlp->pvInstance, pszPatFmt, va);
213}
214
215/** Wrapper around DBGFR3InfoRegisterExternal. */
216DECLINLINE(int) HGCMSvcHlpInfoRegister(PVBOXHGCMSVCHELPERS pHlp, const char *pszName, const char *pszDesc,
217 PFNDBGFHANDLEREXT pfnHandler, void *pvUser)
218{
219 return pHlp->pfnInfoRegister(pHlp->pvInstance, pszName, pszDesc, pfnHandler, pvUser);
220}
221
222/** Wrapper around DBGFR3InfoDeregisterExternal. */
223DECLINLINE(int) HGCMSvcHlpInfoDeregister(PVBOXHGCMSVCHELPERS pHlp, const char *pszName)
224{
225 return pHlp->pfnInfoDeregister(pHlp->pvInstance, pszName);
226}
227
228#endif /* IN_RING3 */
229
230
231#define VBOX_HGCM_SVC_PARM_INVALID (0U)
232#define VBOX_HGCM_SVC_PARM_32BIT (1U)
233#define VBOX_HGCM_SVC_PARM_64BIT (2U)
234#define VBOX_HGCM_SVC_PARM_PTR (3U)
235#define VBOX_HGCM_SVC_PARM_PAGES (4U)
236
237/** VBOX_HGCM_SVC_PARM_PAGES specific data. */
238typedef struct VBOXHGCMSVCPARMPAGES
239{
240 uint32_t cb;
241 uint16_t cPages;
242 uint16_t u16Padding;
243 void **papvPages;
244} VBOXHGCMSVCPARMPAGES;
245typedef VBOXHGCMSVCPARMPAGES *PVBOXHGCMSVCPARMPAGES;
246
247typedef struct VBOXHGCMSVCPARM
248{
249 /** VBOX_HGCM_SVC_PARM_* values. */
250 uint32_t type;
251
252 union
253 {
254 uint32_t uint32;
255 uint64_t uint64;
256 struct
257 {
258 uint32_t size;
259 void *addr;
260 } pointer;
261 /** VBOX_HGCM_SVC_PARM_PAGES */
262 VBOXHGCMSVCPARMPAGES Pages;
263 } u;
264} VBOXHGCMSVCPARM;
265
266/** Extract an uint32_t value from an HGCM parameter structure. */
267DECLINLINE(int) HGCMSvcGetU32(VBOXHGCMSVCPARM *pParm, uint32_t *pu32)
268{
269 int rc = VINF_SUCCESS;
270 AssertPtrReturn(pParm, VERR_INVALID_POINTER);
271 AssertPtrReturn(pParm, VERR_INVALID_POINTER);
272 AssertPtrReturn(pu32, VERR_INVALID_POINTER);
273 if (pParm->type != VBOX_HGCM_SVC_PARM_32BIT)
274 rc = VERR_INVALID_PARAMETER;
275 if (RT_SUCCESS(rc))
276 *pu32 = pParm->u.uint32;
277 return rc;
278}
279
280/** Extract an uint64_t value from an HGCM parameter structure. */
281DECLINLINE(int) HGCMSvcGetU64(VBOXHGCMSVCPARM *pParm, uint64_t *pu64)
282{
283 int rc = VINF_SUCCESS;
284 AssertPtrReturn(pParm, VERR_INVALID_POINTER);
285 AssertPtrReturn(pParm, VERR_INVALID_POINTER);
286 AssertPtrReturn(pu64, VERR_INVALID_POINTER);
287 if (pParm->type != VBOX_HGCM_SVC_PARM_64BIT)
288 rc = VERR_INVALID_PARAMETER;
289 if (RT_SUCCESS(rc))
290 *pu64 = pParm->u.uint64;
291 return rc;
292}
293
294/** Extract an pointer value from an HGCM parameter structure. */
295DECLINLINE(int) HGCMSvcGetPv(VBOXHGCMSVCPARM *pParm, void **ppv, uint32_t *pcb)
296{
297 AssertPtrReturn(pParm, VERR_INVALID_POINTER);
298 AssertPtrReturn(ppv, VERR_INVALID_POINTER);
299 AssertPtrReturn(pcb, VERR_INVALID_POINTER);
300 if (pParm->type == VBOX_HGCM_SVC_PARM_PTR)
301 {
302 *ppv = pParm->u.pointer.addr;
303 *pcb = pParm->u.pointer.size;
304 return VINF_SUCCESS;
305 }
306
307 return VERR_INVALID_PARAMETER;
308}
309
310/** Extract a constant pointer value from an HGCM parameter structure. */
311DECLINLINE(int) HGCMSvcGetPcv(VBOXHGCMSVCPARM *pParm, const void **ppv, uint32_t *pcb)
312{
313 AssertPtrReturn(pParm, VERR_INVALID_POINTER);
314 AssertPtrReturn(ppv, VERR_INVALID_POINTER);
315 AssertPtrReturn(pcb, VERR_INVALID_POINTER);
316 if (pParm->type == VBOX_HGCM_SVC_PARM_PTR)
317 {
318 *ppv = (const void *)pParm->u.pointer.addr;
319 *pcb = pParm->u.pointer.size;
320 return VINF_SUCCESS;
321 }
322
323 return VERR_INVALID_PARAMETER;
324}
325
326/** Extract a valid pointer to a non-empty buffer from an HGCM parameter
327 * structure. */
328DECLINLINE(int) HGCMSvcGetBuf(VBOXHGCMSVCPARM *pParm, void **ppv, uint32_t *pcb)
329{
330 AssertPtrReturn(pParm, VERR_INVALID_POINTER);
331 AssertPtrReturn(ppv, VERR_INVALID_POINTER);
332 AssertPtrReturn(pcb, VERR_INVALID_POINTER);
333 if ( pParm->type == VBOX_HGCM_SVC_PARM_PTR
334 && RT_VALID_PTR(pParm->u.pointer.addr)
335 && pParm->u.pointer.size > 0)
336 {
337 *ppv = pParm->u.pointer.addr;
338 *pcb = pParm->u.pointer.size;
339 return VINF_SUCCESS;
340 }
341
342 return VERR_INVALID_PARAMETER;
343}
344
345/** Extract a valid pointer to a non-empty constant buffer from an HGCM
346 * parameter structure. */
347DECLINLINE(int) HGCMSvcGetCBuf(VBOXHGCMSVCPARM *pParm, const void **ppv, uint32_t *pcb)
348{
349 AssertPtrReturn(pParm, VERR_INVALID_POINTER);
350 AssertPtrReturn(ppv, VERR_INVALID_POINTER);
351 AssertPtrReturn(pcb, VERR_INVALID_POINTER);
352 if ( pParm->type == VBOX_HGCM_SVC_PARM_PTR
353 && RT_VALID_PTR(pParm->u.pointer.addr)
354 && pParm->u.pointer.size > 0)
355 {
356 *ppv = (const void *)pParm->u.pointer.addr;
357 *pcb = pParm->u.pointer.size;
358 return VINF_SUCCESS;
359 }
360
361 return VERR_INVALID_PARAMETER;
362}
363
364/** Extract a string value from an HGCM parameter structure. */
365DECLINLINE(int) HGCMSvcGetStr(VBOXHGCMSVCPARM *pParm, char **ppch, uint32_t *pcb)
366{
367 AssertPtrReturn(pParm, VERR_INVALID_POINTER);
368 AssertPtrReturn(ppch, VERR_INVALID_POINTER);
369 AssertPtrReturn(pcb, VERR_INVALID_POINTER);
370 if ( pParm->type == VBOX_HGCM_SVC_PARM_PTR
371 && RT_VALID_PTR(pParm->u.pointer.addr)
372 && pParm->u.pointer.size > 0)
373 {
374 int rc = RTStrValidateEncodingEx((char *)pParm->u.pointer.addr,
375 pParm->u.pointer.size,
376 RTSTR_VALIDATE_ENCODING_ZERO_TERMINATED);
377 if (RT_FAILURE(rc))
378 return rc;
379 *ppch = (char *)pParm->u.pointer.addr;
380 *pcb = pParm->u.pointer.size;
381 return VINF_SUCCESS;
382 }
383
384 return VERR_INVALID_PARAMETER;
385}
386
387/** Extract a constant string value from an HGCM parameter structure. */
388DECLINLINE(int) HGCMSvcGetCStr(VBOXHGCMSVCPARM *pParm, const char **ppch, uint32_t *pcb)
389{
390 AssertPtrReturn(pParm, VERR_INVALID_POINTER);
391 AssertPtrReturn(ppch, VERR_INVALID_POINTER);
392 AssertPtrReturn(pcb, VERR_INVALID_POINTER);
393 if ( pParm->type == VBOX_HGCM_SVC_PARM_PTR
394 && RT_VALID_PTR(pParm->u.pointer.addr)
395 && pParm->u.pointer.size > 0)
396 {
397 int rc = RTStrValidateEncodingEx((char *)pParm->u.pointer.addr,
398 pParm->u.pointer.size,
399 RTSTR_VALIDATE_ENCODING_ZERO_TERMINATED);
400 if (RT_FAILURE(rc))
401 return rc;
402 *ppch = (char *)pParm->u.pointer.addr;
403 *pcb = pParm->u.pointer.size;
404 return VINF_SUCCESS;
405 }
406
407 return VERR_INVALID_PARAMETER;
408}
409
410/** Extract a constant string value from an HGCM parameter structure. */
411DECLINLINE(int) HGCMSvcGetPsz(VBOXHGCMSVCPARM *pParm, const char **ppch, uint32_t *pcb)
412{
413 AssertPtrReturn(pParm, VERR_INVALID_POINTER);
414 AssertPtrReturn(ppch, VERR_INVALID_POINTER);
415 AssertPtrReturn(pcb, VERR_INVALID_POINTER);
416 if ( pParm->type == VBOX_HGCM_SVC_PARM_PTR
417 && RT_VALID_PTR(pParm->u.pointer.addr)
418 && pParm->u.pointer.size > 0)
419 {
420 int rc = RTStrValidateEncodingEx((const char *)pParm->u.pointer.addr,
421 pParm->u.pointer.size,
422 RTSTR_VALIDATE_ENCODING_ZERO_TERMINATED);
423 if (RT_FAILURE(rc))
424 return rc;
425 *ppch = (const char *)pParm->u.pointer.addr;
426 *pcb = pParm->u.pointer.size;
427 return VINF_SUCCESS;
428 }
429
430 return VERR_INVALID_PARAMETER;
431}
432
433/** Set a uint32_t value to an HGCM parameter structure */
434DECLINLINE(void) HGCMSvcSetU32(VBOXHGCMSVCPARM *pParm, uint32_t u32)
435{
436 AssertPtr(pParm);
437 pParm->type = VBOX_HGCM_SVC_PARM_32BIT;
438 pParm->u.uint32 = u32;
439}
440
441/** Set a uint64_t value to an HGCM parameter structure */
442DECLINLINE(void) HGCMSvcSetU64(VBOXHGCMSVCPARM *pParm, uint64_t u64)
443{
444 AssertPtr(pParm);
445 pParm->type = VBOX_HGCM_SVC_PARM_64BIT;
446 pParm->u.uint64 = u64;
447}
448
449/** Set a pointer value to an HGCM parameter structure */
450DECLINLINE(void) HGCMSvcSetPv(VBOXHGCMSVCPARM *pParm, void *pv, uint32_t cb)
451{
452 AssertPtr(pParm);
453 pParm->type = VBOX_HGCM_SVC_PARM_PTR;
454 pParm->u.pointer.addr = pv;
455 pParm->u.pointer.size = cb;
456}
457
458/** Set a pointer value to an HGCM parameter structure */
459DECLINLINE(void) HGCMSvcSetStr(VBOXHGCMSVCPARM *pParm, const char *psz)
460{
461 AssertPtr(pParm);
462 pParm->type = VBOX_HGCM_SVC_PARM_PTR;
463 pParm->u.pointer.addr = (void *)psz;
464 pParm->u.pointer.size = (uint32_t)strlen(psz) + 1;
465}
466
467#ifdef __cplusplus
468# ifdef IPRT_INCLUDED_cpp_ministring_h
469/** Set a const string value to an HGCM parameter structure */
470DECLINLINE(void) HGCMSvcSetRTCStr(VBOXHGCMSVCPARM *pParm, const RTCString &rString)
471{
472 AssertPtr(pParm);
473 pParm->type = VBOX_HGCM_SVC_PARM_PTR;
474 pParm->u.pointer.addr = (void *)rString.c_str();
475 pParm->u.pointer.size = (uint32_t)rString.length() + 1;
476}
477# endif
478#endif
479
480#ifdef IN_RING3
481/**
482 * Puts (serializes) a VBOXHGCMSVCPARM struct into SSM.
483 *
484 * @returns VBox status code.
485 * @param pParm VBOXHGCMSVCPARM to serialize.
486 * @param pSSM SSM handle to serialize to.
487 */
488DECLINLINE(int) HGCMSvcSSMR3Put(VBOXHGCMSVCPARM *pParm, PSSMHANDLE pSSM)
489{
490 int rc;
491
492 AssertPtrReturn(pParm, VERR_INVALID_POINTER);
493 AssertPtrReturn(pSSM, VERR_INVALID_POINTER);
494
495 rc = SSMR3PutU32(pSSM, sizeof(VBOXHGCMSVCPARM));
496 AssertRCReturn(rc, rc);
497 rc = SSMR3PutU32(pSSM, pParm->type);
498 AssertRCReturn(rc, rc);
499
500 switch (pParm->type)
501 {
502 case VBOX_HGCM_SVC_PARM_32BIT:
503 rc = SSMR3PutU32(pSSM, pParm->u.uint32);
504 break;
505 case VBOX_HGCM_SVC_PARM_64BIT:
506 rc = SSMR3PutU64(pSSM, pParm->u.uint64);
507 break;
508 case VBOX_HGCM_SVC_PARM_PTR:
509 rc = SSMR3PutU32(pSSM, pParm->u.pointer.size);
510 if (RT_SUCCESS(rc))
511 rc = SSMR3PutMem(pSSM, pParm->u.pointer.addr, pParm->u.pointer.size);
512 break;
513 default:
514 AssertMsgFailed(("Paramter type %RU32 not implemented yet\n", pParm->type));
515 rc = VERR_NOT_IMPLEMENTED;
516 break;
517 }
518
519 return rc;
520}
521
522/**
523 * Gets (loads) a VBOXHGCMSVCPARM struct from SSM.
524 *
525 * @returns VBox status code.
526 * @param pParm VBOXHGCMSVCPARM to load into. Must be initialied (zero-ed) properly.
527 * @param pSSM SSM handle to load from.
528 */
529DECLINLINE(int) HGCMSvcSSMR3Get(VBOXHGCMSVCPARM *pParm, PSSMHANDLE pSSM)
530{
531 uint32_t cbParm;
532 int rc;
533
534 AssertPtrReturn(pParm, VERR_INVALID_POINTER);
535 AssertPtrReturn(pSSM, VERR_INVALID_POINTER);
536
537 rc = SSMR3GetU32(pSSM, &cbParm);
538 AssertRCReturn(rc, rc);
539 AssertReturn(cbParm == sizeof(VBOXHGCMSVCPARM), VERR_SSM_DATA_UNIT_FORMAT_CHANGED);
540
541 rc = SSMR3GetU32(pSSM, &pParm->type);
542 AssertRCReturn(rc, rc);
543
544 switch (pParm->type)
545 {
546 case VBOX_HGCM_SVC_PARM_32BIT:
547 {
548 rc = SSMR3GetU32(pSSM, &pParm->u.uint32);
549 AssertRCReturn(rc, rc);
550 break;
551 }
552
553 case VBOX_HGCM_SVC_PARM_64BIT:
554 {
555 rc = SSMR3GetU64(pSSM, &pParm->u.uint64);
556 AssertRCReturn(rc, rc);
557 break;
558 }
559
560 case VBOX_HGCM_SVC_PARM_PTR:
561 {
562 AssertMsgReturn(pParm->u.pointer.size == 0,
563 ("Pointer size parameter already in use (or not initialized)\n"), VERR_INVALID_PARAMETER);
564
565 rc = SSMR3GetU32(pSSM, &pParm->u.pointer.size);
566 AssertRCReturn(rc, rc);
567
568 AssertMsgReturn(pParm->u.pointer.addr == NULL,
569 ("Pointer parameter already in use (or not initialized)\n"), VERR_INVALID_PARAMETER);
570
571 pParm->u.pointer.addr = RTMemAlloc(pParm->u.pointer.size);
572 AssertPtrReturn(pParm->u.pointer.addr, VERR_NO_MEMORY);
573 rc = SSMR3GetMem(pSSM, pParm->u.pointer.addr, pParm->u.pointer.size);
574
575 AssertRCReturn(rc, rc);
576 break;
577 }
578
579 default:
580 AssertMsgFailed(("Paramter type %RU32 not implemented yet\n", pParm->type));
581 rc = VERR_NOT_IMPLEMENTED;
582 break;
583 }
584
585 return VINF_SUCCESS;
586}
587#endif /* IN_RING3 */
588
589typedef VBOXHGCMSVCPARM *PVBOXHGCMSVCPARM;
590
591
592/** Service specific extension callback.
593 * This callback is called by the service to perform service specific operation.
594 *
595 * @param pvExtension The extension pointer.
596 * @param u32Function What the callback is supposed to do.
597 * @param pvParm The function parameters.
598 * @param cbParms The size of the function parameters.
599 */
600typedef DECLCALLBACKTYPE(int, FNHGCMSVCEXT,(void *pvExtension, uint32_t u32Function, void *pvParm, uint32_t cbParms));
601typedef FNHGCMSVCEXT *PFNHGCMSVCEXT;
602
603/**
604 * Notification event.
605 */
606typedef enum HGCMNOTIFYEVENT
607{
608 HGCMNOTIFYEVENT_INVALID = 0,
609 HGCMNOTIFYEVENT_POWER_ON,
610 HGCMNOTIFYEVENT_RESUME,
611 HGCMNOTIFYEVENT_SUSPEND,
612 HGCMNOTIFYEVENT_RESET,
613 HGCMNOTIFYEVENT_POWER_OFF,
614 HGCMNOTIFYEVENT_END,
615 HGCMNOTIFYEVENT_32BIT_HACK = 0x7fffffff
616} HGCMNOTIFYEVENT;
617
618/** @name HGCM_CLIENT_CATEGORY_XXX - Client categories
619 * @{ */
620#define HGCM_CLIENT_CATEGORY_KERNEL 0 /**< Guest kernel mode and legacy client. */
621#define HGCM_CLIENT_CATEGORY_ROOT 1 /**< Guest root or admin client. */
622#define HGCM_CLIENT_CATEGORY_USER 2 /**< Regular guest user client. */
623#define HGCM_CLIENT_CATEGORY_MAX 3 /**< Max number of categories. */
624/** @} */
625
626
627/** The Service DLL entry points.
628 *
629 * HGCM will call the DLL "VBoxHGCMSvcLoad"
630 * function and the DLL must fill in the VBOXHGCMSVCFNTABLE
631 * with function pointers.
632 *
633 * @note The structure is used in separately compiled binaries so an explicit
634 * packing is required.
635 */
636typedef struct VBOXHGCMSVCFNTABLE
637{
638 /** @name Filled by HGCM
639 * @{ */
640
641 /** Size of the structure. */
642 uint32_t cbSize;
643
644 /** Version of the structure, including the helpers. (VBOX_HGCM_SVC_VERSION) */
645 uint32_t u32Version;
646
647 PVBOXHGCMSVCHELPERS pHelpers;
648 /** @} */
649
650 /** @name Filled in by the service.
651 * @{ */
652
653 /** Size of client information the service want to have. */
654 uint32_t cbClient;
655
656 /** The maximum number of clients per category. Leave entries as zero for defaults. */
657 uint32_t acMaxClients[HGCM_CLIENT_CATEGORY_MAX];
658 /** The maximum number of concurrent calls per client for each category.
659 * Leave entries as as zero for default. */
660 uint32_t acMaxCallsPerClient[HGCM_CLIENT_CATEGORY_MAX];
661 /** The HGCM_CLIENT_CATEGORY_XXX value for legacy clients.
662 * Defaults to HGCM_CLIENT_CATEGORY_KERNEL. */
663 uint32_t idxLegacyClientCategory;
664
665 /** Uninitialize service */
666 DECLR3CALLBACKMEMBER(int, pfnUnload, (void *pvService));
667
668 /** Inform the service about a client connection. */
669 DECLR3CALLBACKMEMBER(int, pfnConnect, (void *pvService, uint32_t u32ClientID, void *pvClient, uint32_t fRequestor, bool fRestoring));
670
671 /** Inform the service that the client wants to disconnect. */
672 DECLR3CALLBACKMEMBER(int, pfnDisconnect, (void *pvService, uint32_t u32ClientID, void *pvClient));
673
674 /** Service entry point.
675 * Return code is passed to pfnCallComplete callback.
676 */
677 DECLR3CALLBACKMEMBER(void, pfnCall, (void *pvService, VBOXHGCMCALLHANDLE callHandle, uint32_t u32ClientID, void *pvClient,
678 uint32_t function, uint32_t cParms, VBOXHGCMSVCPARM paParms[], uint64_t tsArrival));
679 /** Informs the service that a call was cancelled by the guest (optional).
680 *
681 * This is called for guest calls, connect requests and disconnect requests.
682 * There is unfortunately no way of obtaining the call handle for a guest call
683 * or otherwise identify the request, so that's left to the service to figure
684 * out using VBOXHGCMSVCHELPERS::pfnIsCallCancelled. Because this is an
685 * asynchronous call, the service may have completed the request already.
686 */
687 DECLR3CALLBACKMEMBER(void, pfnCancelled, (void *pvService, uint32_t idClient, void *pvClient));
688
689 /** Host Service entry point meant for privileged features invisible to the guest.
690 * Return code is passed to pfnCallComplete callback.
691 */
692 DECLR3CALLBACKMEMBER(int, pfnHostCall, (void *pvService, uint32_t function, uint32_t cParms, VBOXHGCMSVCPARM paParms[]));
693
694 /** Inform the service about a VM save operation. */
695 DECLR3CALLBACKMEMBER(int, pfnSaveState, (void *pvService, uint32_t u32ClientID, void *pvClient, PSSMHANDLE pSSM));
696
697 /** Inform the service about a VM load operation. */
698 DECLR3CALLBACKMEMBER(int, pfnLoadState, (void *pvService, uint32_t u32ClientID, void *pvClient, PSSMHANDLE pSSM,
699 uint32_t uVersion));
700
701 /** Register a service extension callback. */
702 DECLR3CALLBACKMEMBER(int, pfnRegisterExtension, (void *pvService, PFNHGCMSVCEXT pfnExtension, void *pvExtension));
703
704 /** Notification (VM state). */
705 DECLR3CALLBACKMEMBER(void, pfnNotify, (void *pvService, HGCMNOTIFYEVENT enmEvent));
706
707 /** User/instance data pointer for the service. */
708 void *pvService;
709
710 /** @} */
711} VBOXHGCMSVCFNTABLE;
712
713
714/** @name HGCM saved state
715 * @note Need to be here so we can add saved to service which doesn't have it.
716 * @{ */
717/** HGCM saved state version. */
718#define HGCM_SAVED_STATE_VERSION 3
719/** HGCM saved state version w/o client state indicators. */
720#define HGCM_SAVED_STATE_VERSION_V2 2
721/** @} */
722
723
724/** Service initialization entry point. */
725typedef DECLCALLBACKTYPE(int, FNVBOXHGCMSVCLOAD,(VBOXHGCMSVCFNTABLE *ptable));
726typedef FNVBOXHGCMSVCLOAD *PFNVBOXHGCMSVCLOAD;
727#define VBOX_HGCM_SVCLOAD_NAME "VBoxHGCMSvcLoad"
728
729#endif /* !VBOX_INCLUDED_hgcmsvc_h */
730
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