VirtualBox

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

Last change on this file since 80632 was 80632, checked in by vboxsync, 5 years ago

VBox/hgcmsvc.h: Added HGCMSvcSSMR3Get() / HGCMSvcSSMR3Put() for serializing VBOXHGCMSVCPARM to saved states.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 23.8 KB
Line 
1/** @file
2 * Host-Guest Communication Manager (HGCM) - Service library definitions.
3 */
4
5/*
6 * Copyright (C) 2006-2019 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 */
84#define VBOX_HGCM_SVC_VERSION_MAJOR (0x0008)
85#define VBOX_HGCM_SVC_VERSION_MINOR (0x0001)
86#define VBOX_HGCM_SVC_VERSION ((VBOX_HGCM_SVC_VERSION_MAJOR << 16) + VBOX_HGCM_SVC_VERSION_MINOR)
87
88
89/** Typed pointer to distinguish a call to service. */
90struct VBOXHGCMCALLHANDLE_TYPEDEF;
91typedef struct VBOXHGCMCALLHANDLE_TYPEDEF *VBOXHGCMCALLHANDLE;
92
93/** Service helpers pointers table. */
94typedef struct VBOXHGCMSVCHELPERS
95{
96 /** The service has processed the Call request. */
97 DECLR3CALLBACKMEMBER(int, pfnCallComplete, (VBOXHGCMCALLHANDLE callHandle, int32_t rc));
98
99 void *pvInstance;
100
101 /** The service disconnects the client. */
102 DECLR3CALLBACKMEMBER(void, pfnDisconnectClient, (void *pvInstance, uint32_t u32ClientID));
103
104 /**
105 * Check if the @a callHandle is for a call restored and re-submitted from saved state.
106 *
107 * @returns true if restored, false if not.
108 * @param callHandle The call we're checking up on.
109 */
110 DECLR3CALLBACKMEMBER(bool, pfnIsCallRestored, (VBOXHGCMCALLHANDLE callHandle));
111
112 /**
113 * Check if the @a callHandle is for a cancelled call.
114 *
115 * @returns true if cancelled, false if not.
116 * @param callHandle The call we're checking up on.
117 */
118 DECLR3CALLBACKMEMBER(bool, pfnIsCallCancelled, (VBOXHGCMCALLHANDLE callHandle));
119
120 /** Access to STAMR3RegisterV. */
121 DECLR3CALLBACKMEMBER(int, pfnStamRegisterV,(void *pvInstance, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,
122 STAMUNIT enmUnit, const char *pszDesc, const char *pszName, va_list va)
123 RT_IPRT_FORMAT_ATTR(7, 0));
124 /** Access to STAMR3DeregisterV. */
125 DECLR3CALLBACKMEMBER(int, pfnStamDeregisterV,(void *pvInstance, const char *pszPatFmt, va_list va) RT_IPRT_FORMAT_ATTR(2, 0));
126
127 /** Access to DBGFR3InfoRegisterExternal. */
128 DECLR3CALLBACKMEMBER(int, pfnInfoRegister,(void *pvInstance, const char *pszName, const char *pszDesc,
129 PFNDBGFHANDLEREXT pfnHandler, void *pvUser));
130 /** Access to DBGFR3InfoDeregisterExternal. */
131 DECLR3CALLBACKMEMBER(int, pfnInfoDeregister,(void *pvInstance, const char *pszName));
132
133 /**
134 * Retrieves the VMMDevRequestHeader::fRequestor value.
135 *
136 * @returns The field value, VMMDEV_REQUESTOR_LEGACY if not supported by the
137 * guest, VMMDEV_REQUESTOR_LOWEST if invalid call.
138 * @param hCall The call we're checking up on.
139 */
140 DECLR3CALLBACKMEMBER(uint32_t, pfnGetRequestor, (VBOXHGCMCALLHANDLE hCall));
141
142 /**
143 * Retrieves VMMDevState::idSession.
144 *
145 * @returns current VMMDev session ID value.
146 */
147 DECLR3CALLBACKMEMBER(uint64_t, pfnGetVMMDevSessionId, (void *pvInstance));
148
149} VBOXHGCMSVCHELPERS;
150
151typedef VBOXHGCMSVCHELPERS *PVBOXHGCMSVCHELPERS;
152
153#if defined(IN_RING3) || defined(IN_SLICKEDIT)
154
155/** Wrapper around STAMR3RegisterF. */
156DECLINLINE(int) RT_IPRT_FORMAT_ATTR(7, 8)
157HGCMSvcHlpStamRegister(PVBOXHGCMSVCHELPERS pHlp, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,
158 STAMUNIT enmUnit, const char *pszDesc, const char *pszName, ...)
159{
160 int rc;
161 va_list va;
162 va_start(va, pszName);
163 rc = pHlp->pfnStamRegisterV(pHlp->pvInstance, pvSample, enmType, enmVisibility, enmUnit, pszDesc, pszName, va);
164 va_end(va);
165 return rc;
166}
167
168/** Wrapper around STAMR3RegisterV. */
169DECLINLINE(int) RT_IPRT_FORMAT_ATTR(7, 0)
170HGCMSvcHlpStamRegisterV(PVBOXHGCMSVCHELPERS pHlp, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,
171 STAMUNIT enmUnit, const char *pszDesc, const char *pszName, va_list va)
172{
173 return pHlp->pfnStamRegisterV(pHlp->pvInstance, pvSample, enmType, enmVisibility, enmUnit, pszDesc, pszName, va);
174}
175
176/** Wrapper around STAMR3DeregisterF. */
177DECLINLINE(int) RT_IPRT_FORMAT_ATTR(2, 3) HGCMSvcHlpStamDeregister(PVBOXHGCMSVCHELPERS pHlp, const char *pszPatFmt, ...)
178{
179 int rc;
180 va_list va;
181 va_start(va, pszPatFmt);
182 rc = pHlp->pfnStamDeregisterV(pHlp->pvInstance, pszPatFmt, va);
183 va_end(va);
184 return rc;
185}
186
187/** Wrapper around STAMR3DeregisterV. */
188DECLINLINE(int) RT_IPRT_FORMAT_ATTR(2, 0) HGCMSvcHlpStamDeregisterV(PVBOXHGCMSVCHELPERS pHlp, const char *pszPatFmt, va_list va)
189{
190 return pHlp->pfnStamDeregisterV(pHlp->pvInstance, pszPatFmt, va);
191}
192
193/** Wrapper around DBGFR3InfoRegisterExternal. */
194DECLINLINE(int) HGCMSvcHlpInfoRegister(PVBOXHGCMSVCHELPERS pHlp, const char *pszName, const char *pszDesc,
195 PFNDBGFHANDLEREXT pfnHandler, void *pvUser)
196{
197 return pHlp->pfnInfoRegister(pHlp->pvInstance, pszName, pszDesc, pfnHandler, pvUser);
198}
199
200/** Wrapper around DBGFR3InfoDeregisterExternal. */
201DECLINLINE(int) HGCMSvcHlpInfoDeregister(PVBOXHGCMSVCHELPERS pHlp, const char *pszName)
202{
203 return pHlp->pfnInfoDeregister(pHlp->pvInstance, pszName);
204}
205
206#endif /* IN_RING3 */
207
208
209#define VBOX_HGCM_SVC_PARM_INVALID (0U)
210#define VBOX_HGCM_SVC_PARM_32BIT (1U)
211#define VBOX_HGCM_SVC_PARM_64BIT (2U)
212#define VBOX_HGCM_SVC_PARM_PTR (3U)
213#define VBOX_HGCM_SVC_PARM_PAGES (4U)
214
215/** VBOX_HGCM_SVC_PARM_PAGES specific data. */
216typedef struct VBOXHGCMSVCPARMPAGES
217{
218 uint32_t cb;
219 uint16_t cPages;
220 uint16_t u16Padding;
221 void **papvPages;
222} VBOXHGCMSVCPARMPAGES;
223typedef VBOXHGCMSVCPARMPAGES *PVBOXHGCMSVCPARMPAGES;
224
225typedef struct VBOXHGCMSVCPARM
226{
227 /** VBOX_HGCM_SVC_PARM_* values. */
228 uint32_t type;
229
230 union
231 {
232 uint32_t uint32;
233 uint64_t uint64;
234 struct
235 {
236 uint32_t size;
237 void *addr;
238 } pointer;
239 /** VBOX_HGCM_SVC_PARM_PAGES */
240 VBOXHGCMSVCPARMPAGES Pages;
241 } u;
242} VBOXHGCMSVCPARM;
243
244/** Extract an uint32_t value from an HGCM parameter structure. */
245DECLINLINE(int) HGCMSvcGetU32(VBOXHGCMSVCPARM *pParm, uint32_t *pu32)
246{
247 int rc = VINF_SUCCESS;
248 AssertPtrReturn(pParm, VERR_INVALID_POINTER);
249 AssertPtrReturn(pParm, VERR_INVALID_POINTER);
250 AssertPtrReturn(pu32, VERR_INVALID_POINTER);
251 if (pParm->type != VBOX_HGCM_SVC_PARM_32BIT)
252 rc = VERR_INVALID_PARAMETER;
253 if (RT_SUCCESS(rc))
254 *pu32 = pParm->u.uint32;
255 return rc;
256}
257
258/** Extract an uint64_t value from an HGCM parameter structure. */
259DECLINLINE(int) HGCMSvcGetU64(VBOXHGCMSVCPARM *pParm, uint64_t *pu64)
260{
261 int rc = VINF_SUCCESS;
262 AssertPtrReturn(pParm, VERR_INVALID_POINTER);
263 AssertPtrReturn(pParm, VERR_INVALID_POINTER);
264 AssertPtrReturn(pu64, VERR_INVALID_POINTER);
265 if (pParm->type != VBOX_HGCM_SVC_PARM_64BIT)
266 rc = VERR_INVALID_PARAMETER;
267 if (RT_SUCCESS(rc))
268 *pu64 = pParm->u.uint64;
269 return rc;
270}
271
272/** Extract an pointer value from an HGCM parameter structure. */
273DECLINLINE(int) HGCMSvcGetPv(VBOXHGCMSVCPARM *pParm, void **ppv, uint32_t *pcb)
274{
275 AssertPtrReturn(pParm, VERR_INVALID_POINTER);
276 AssertPtrReturn(ppv, VERR_INVALID_POINTER);
277 AssertPtrReturn(pcb, VERR_INVALID_POINTER);
278 if (pParm->type == VBOX_HGCM_SVC_PARM_PTR)
279 {
280 *ppv = pParm->u.pointer.addr;
281 *pcb = pParm->u.pointer.size;
282 return VINF_SUCCESS;
283 }
284
285 return VERR_INVALID_PARAMETER;
286}
287
288/** Extract a constant pointer value from an HGCM parameter structure. */
289DECLINLINE(int) HGCMSvcGetPcv(VBOXHGCMSVCPARM *pParm, const void **ppv, uint32_t *pcb)
290{
291 AssertPtrReturn(pParm, VERR_INVALID_POINTER);
292 AssertPtrReturn(ppv, VERR_INVALID_POINTER);
293 AssertPtrReturn(pcb, VERR_INVALID_POINTER);
294 if (pParm->type == VBOX_HGCM_SVC_PARM_PTR)
295 {
296 *ppv = (const void *)pParm->u.pointer.addr;
297 *pcb = pParm->u.pointer.size;
298 return VINF_SUCCESS;
299 }
300
301 return VERR_INVALID_PARAMETER;
302}
303
304/** Extract a valid pointer to a non-empty buffer from an HGCM parameter
305 * structure. */
306DECLINLINE(int) HGCMSvcGetBuf(VBOXHGCMSVCPARM *pParm, void **ppv, uint32_t *pcb)
307{
308 AssertPtrReturn(pParm, VERR_INVALID_POINTER);
309 AssertPtrReturn(ppv, VERR_INVALID_POINTER);
310 AssertPtrReturn(pcb, VERR_INVALID_POINTER);
311 if ( pParm->type == VBOX_HGCM_SVC_PARM_PTR
312 && VALID_PTR(pParm->u.pointer.addr)
313 && pParm->u.pointer.size > 0)
314 {
315 *ppv = pParm->u.pointer.addr;
316 *pcb = pParm->u.pointer.size;
317 return VINF_SUCCESS;
318 }
319
320 return VERR_INVALID_PARAMETER;
321}
322
323/** Extract a valid pointer to a non-empty constant buffer from an HGCM
324 * parameter structure. */
325DECLINLINE(int) HGCMSvcGetCBuf(VBOXHGCMSVCPARM *pParm, const void **ppv, uint32_t *pcb)
326{
327 AssertPtrReturn(pParm, VERR_INVALID_POINTER);
328 AssertPtrReturn(ppv, VERR_INVALID_POINTER);
329 AssertPtrReturn(pcb, VERR_INVALID_POINTER);
330 if ( pParm->type == VBOX_HGCM_SVC_PARM_PTR
331 && VALID_PTR(pParm->u.pointer.addr)
332 && pParm->u.pointer.size > 0)
333 {
334 *ppv = (const void *)pParm->u.pointer.addr;
335 *pcb = pParm->u.pointer.size;
336 return VINF_SUCCESS;
337 }
338
339 return VERR_INVALID_PARAMETER;
340}
341
342/** Extract a string value from an HGCM parameter structure. */
343DECLINLINE(int) HGCMSvcGetStr(VBOXHGCMSVCPARM *pParm, char **ppch, uint32_t *pcb)
344{
345 AssertPtrReturn(pParm, VERR_INVALID_POINTER);
346 AssertPtrReturn(ppch, VERR_INVALID_POINTER);
347 AssertPtrReturn(pcb, VERR_INVALID_POINTER);
348 if ( pParm->type == VBOX_HGCM_SVC_PARM_PTR
349 && VALID_PTR(pParm->u.pointer.addr)
350 && pParm->u.pointer.size > 0)
351 {
352 int rc = RTStrValidateEncodingEx((char *)pParm->u.pointer.addr,
353 pParm->u.pointer.size,
354 RTSTR_VALIDATE_ENCODING_ZERO_TERMINATED);
355 if (RT_FAILURE(rc))
356 return rc;
357 *ppch = (char *)pParm->u.pointer.addr;
358 *pcb = pParm->u.pointer.size;
359 return VINF_SUCCESS;
360 }
361
362 return VERR_INVALID_PARAMETER;
363}
364
365/** Extract a constant string value from an HGCM parameter structure. */
366DECLINLINE(int) HGCMSvcGetCStr(VBOXHGCMSVCPARM *pParm, const char **ppch, uint32_t *pcb)
367{
368 AssertPtrReturn(pParm, VERR_INVALID_POINTER);
369 AssertPtrReturn(ppch, VERR_INVALID_POINTER);
370 AssertPtrReturn(pcb, VERR_INVALID_POINTER);
371 if ( pParm->type == VBOX_HGCM_SVC_PARM_PTR
372 && VALID_PTR(pParm->u.pointer.addr)
373 && pParm->u.pointer.size > 0)
374 {
375 int rc = RTStrValidateEncodingEx((char *)pParm->u.pointer.addr,
376 pParm->u.pointer.size,
377 RTSTR_VALIDATE_ENCODING_ZERO_TERMINATED);
378 if (RT_FAILURE(rc))
379 return rc;
380 *ppch = (char *)pParm->u.pointer.addr;
381 *pcb = pParm->u.pointer.size;
382 return VINF_SUCCESS;
383 }
384
385 return VERR_INVALID_PARAMETER;
386}
387
388/** Extract a constant string value from an HGCM parameter structure. */
389DECLINLINE(int) HGCMSvcGetPsz(VBOXHGCMSVCPARM *pParm, const char **ppch, uint32_t *pcb)
390{
391 AssertPtrReturn(pParm, VERR_INVALID_POINTER);
392 AssertPtrReturn(ppch, VERR_INVALID_POINTER);
393 AssertPtrReturn(pcb, VERR_INVALID_POINTER);
394 if ( pParm->type == VBOX_HGCM_SVC_PARM_PTR
395 && VALID_PTR(pParm->u.pointer.addr)
396 && pParm->u.pointer.size > 0)
397 {
398 int rc = RTStrValidateEncodingEx((const char *)pParm->u.pointer.addr,
399 pParm->u.pointer.size,
400 RTSTR_VALIDATE_ENCODING_ZERO_TERMINATED);
401 if (RT_FAILURE(rc))
402 return rc;
403 *ppch = (const char *)pParm->u.pointer.addr;
404 *pcb = pParm->u.pointer.size;
405 return VINF_SUCCESS;
406 }
407
408 return VERR_INVALID_PARAMETER;
409}
410
411/** Set a uint32_t value to an HGCM parameter structure */
412DECLINLINE(void) HGCMSvcSetU32(VBOXHGCMSVCPARM *pParm, uint32_t u32)
413{
414 AssertPtr(pParm);
415 pParm->type = VBOX_HGCM_SVC_PARM_32BIT;
416 pParm->u.uint32 = u32;
417}
418
419/** Set a uint64_t value to an HGCM parameter structure */
420DECLINLINE(void) HGCMSvcSetU64(VBOXHGCMSVCPARM *pParm, uint64_t u64)
421{
422 AssertPtr(pParm);
423 pParm->type = VBOX_HGCM_SVC_PARM_64BIT;
424 pParm->u.uint64 = u64;
425}
426
427/** Set a pointer value to an HGCM parameter structure */
428DECLINLINE(void) HGCMSvcSetPv(VBOXHGCMSVCPARM *pParm, void *pv, uint32_t cb)
429{
430 AssertPtr(pParm);
431 pParm->type = VBOX_HGCM_SVC_PARM_PTR;
432 pParm->u.pointer.addr = pv;
433 pParm->u.pointer.size = cb;
434}
435
436/** Set a pointer value to an HGCM parameter structure */
437DECLINLINE(void) HGCMSvcSetStr(VBOXHGCMSVCPARM *pParm, const char *psz)
438{
439 AssertPtr(pParm);
440 pParm->type = VBOX_HGCM_SVC_PARM_PTR;
441 pParm->u.pointer.addr = (void *)psz;
442 pParm->u.pointer.size = (uint32_t)strlen(psz) + 1;
443}
444
445#ifdef __cplusplus
446# ifdef IPRT_INCLUDED_cpp_ministring_h
447/** Set a const string value to an HGCM parameter structure */
448DECLINLINE(void) HGCMSvcSetRTCStr(VBOXHGCMSVCPARM *pParm, const RTCString &rString)
449{
450 AssertPtr(pParm);
451 pParm->type = VBOX_HGCM_SVC_PARM_PTR;
452 pParm->u.pointer.addr = (void *)rString.c_str();
453 pParm->u.pointer.size = (uint32_t)rString.length() + 1;
454}
455# endif
456#endif
457
458#ifdef IN_RING3
459/**
460 * Puts (serializes) a VBOXHGCMSVCPARM struct into SSM.
461 *
462 * @returns VBox status code.
463 * @param pParm VBOXHGCMSVCPARM to serialize.
464 * @param pSSM SSM handle to serialize to.
465 */
466DECLINLINE(int) HGCMSvcSSMR3Put(VBOXHGCMSVCPARM *pParm, PSSMHANDLE pSSM)
467{
468 AssertPtrReturn(pParm, VERR_INVALID_POINTER);
469 AssertPtrReturn(pSSM, VERR_INVALID_POINTER);
470
471 int rc = SSMR3PutU32(pSSM, sizeof(VBOXHGCMSVCPARM));
472 AssertRCReturn(rc, rc);
473 rc = SSMR3PutU32(pSSM, pParm->type);
474 AssertRCReturn(rc, rc);
475
476 switch (pParm->type)
477 {
478 case VBOX_HGCM_SVC_PARM_32BIT:
479 rc = SSMR3PutU32(pSSM, pParm->u.uint32);
480 break;
481 case VBOX_HGCM_SVC_PARM_64BIT:
482 rc = SSMR3PutU32(pSSM, pParm->u.uint64);
483 break;
484 case VBOX_HGCM_SVC_PARM_PTR:
485 rc = SSMR3PutU32(pSSM, pParm->u.pointer.size);
486 if (RT_SUCCESS(rc))
487 rc = SSMR3PutMem(pSSM, pParm->u.pointer.addr, pParm->u.pointer.size);
488 break;
489 default:
490 AssertMsgFailed(("Paramter type %RU32 not implemented yet\n", pParm->type));
491 rc = VERR_NOT_IMPLEMENTED;
492 break;
493 }
494
495 return rc;
496}
497
498/**
499 * Gets (loads) a VBOXHGCMSVCPARM struct from SSM.
500 *
501 * @returns VBox status code.
502 * @param pParm VBOXHGCMSVCPARM to load into. Must be initialied (zero-ed) properly.
503 * @param pSSM SSM handle to load from.
504 */
505DECLINLINE(int) HGCMSvcSSMR3Get(VBOXHGCMSVCPARM *pParm, PSSMHANDLE pSSM)
506{
507 AssertPtrReturn(pParm, VERR_INVALID_POINTER);
508 AssertPtrReturn(pSSM, VERR_INVALID_POINTER);
509
510 uint32_t cbParm;
511 int rc = SSMR3GetU32(pSSM, &cbParm);
512 AssertRCReturn(rc, rc);
513 AssertReturn(cbParm == sizeof(VBOXHGCMSVCPARM), VERR_SSM_DATA_UNIT_FORMAT_CHANGED);
514
515 rc = SSMR3GetU32(pSSM, &pParm->type);
516 AssertRCReturn(rc, rc);
517
518 switch (pParm->type)
519 {
520 case VBOX_HGCM_SVC_PARM_32BIT:
521 {
522 rc = SSMR3GetU32(pSSM, &pParm->u.uint32);
523 AssertRCReturn(rc, rc);
524 break;
525 }
526
527 case VBOX_HGCM_SVC_PARM_64BIT:
528 {
529 rc = SSMR3GetU64(pSSM, &pParm->u.uint64);
530 AssertRCReturn(rc, rc);
531 break;
532 }
533
534 case VBOX_HGCM_SVC_PARM_PTR:
535 {
536 AssertMsgReturn(pParm->u.pointer.size == 0,
537 ("Pointer size parameter already in use (or not initialized)\n"), VERR_INVALID_PARAMETER);
538
539 rc = SSMR3GetU32(pSSM, &pParm->u.pointer.size);
540 AssertRCReturn(rc, rc);
541
542 AssertMsgReturn(pParm->u.pointer.addr == NULL,
543 ("Pointer parameter already in use (or not initialized)\n"), VERR_INVALID_PARAMETER);
544
545 pParm->u.pointer.addr = RTMemAlloc(pParm->u.pointer.size);
546 AssertPtrReturn(pParm->u.pointer.addr, VERR_NO_MEMORY);
547 rc = SSMR3GetMem(pSSM, pParm->u.pointer.addr, pParm->u.pointer.size);
548
549 AssertRCReturn(rc, rc);
550 break;
551 }
552
553 default:
554 AssertMsgFailed(("Paramter type %RU32 not implemented yet\n", pParm->type));
555 rc = VERR_NOT_IMPLEMENTED;
556 break;
557 }
558
559 return VINF_SUCCESS;
560}
561#endif /* IN_RING3 */
562
563typedef VBOXHGCMSVCPARM *PVBOXHGCMSVCPARM;
564
565
566/** Service specific extension callback.
567 * This callback is called by the service to perform service specific operation.
568 *
569 * @param pvExtension The extension pointer.
570 * @param u32Function What the callback is supposed to do.
571 * @param pvParm The function parameters.
572 * @param cbParm The size of the function parameters.
573 */
574typedef DECLCALLBACK(int) FNHGCMSVCEXT(void *pvExtension, uint32_t u32Function, void *pvParm, uint32_t cbParms);
575typedef FNHGCMSVCEXT *PFNHGCMSVCEXT;
576
577/**
578 * Notification event.
579 */
580typedef enum HGCMNOTIFYEVENT
581{
582 HGCMNOTIFYEVENT_INVALID = 0,
583 HGCMNOTIFYEVENT_POWER_ON,
584 HGCMNOTIFYEVENT_RESUME,
585 HGCMNOTIFYEVENT_SUSPEND,
586 HGCMNOTIFYEVENT_RESET,
587 HGCMNOTIFYEVENT_POWER_OFF,
588 HGCMNOTIFYEVENT_END,
589 HGCMNOTIFYEVENT_32BIT_HACK = 0x7fffffff
590} HGCMNOTIFYEVENT;
591
592
593/** The Service DLL entry points.
594 *
595 * HGCM will call the DLL "VBoxHGCMSvcLoad"
596 * function and the DLL must fill in the VBOXHGCMSVCFNTABLE
597 * with function pointers.
598 *
599 * @note The structure is used in separately compiled binaries so an explicit
600 * packing is required.
601 */
602typedef struct VBOXHGCMSVCFNTABLE
603{
604 /** @name Filled by HGCM
605 * @{ */
606
607 /** Size of the structure. */
608 uint32_t cbSize;
609
610 /** Version of the structure, including the helpers. */
611 uint32_t u32Version;
612
613 PVBOXHGCMSVCHELPERS pHelpers;
614 /** @} */
615
616 /** @name Filled in by the service.
617 * @{ */
618
619 /** Size of client information the service want to have. */
620 uint32_t cbClient;
621#if ARCH_BITS == 64
622 /** Ensure that the following pointers are properly aligned on 64-bit system. */
623 uint32_t u32Alignment0;
624#endif
625
626 /** Uninitialize service */
627 DECLR3CALLBACKMEMBER(int, pfnUnload, (void *pvService));
628
629 /** Inform the service about a client connection. */
630 DECLR3CALLBACKMEMBER(int, pfnConnect, (void *pvService, uint32_t u32ClientID, void *pvClient, uint32_t fRequestor, bool fRestoring));
631
632 /** Inform the service that the client wants to disconnect. */
633 DECLR3CALLBACKMEMBER(int, pfnDisconnect, (void *pvService, uint32_t u32ClientID, void *pvClient));
634
635 /** Service entry point.
636 * Return code is passed to pfnCallComplete callback.
637 */
638 DECLR3CALLBACKMEMBER(void, pfnCall, (void *pvService, VBOXHGCMCALLHANDLE callHandle, uint32_t u32ClientID, void *pvClient,
639 uint32_t function, uint32_t cParms, VBOXHGCMSVCPARM paParms[], uint64_t tsArrival));
640 /** Informs the service that a call was cancelled by the guest (optional).
641 *
642 * This is called for guest calls, connect requests and disconnect requests.
643 * There is unfortunately no way of obtaining the call handle for a guest call
644 * or otherwise identify the request, so that's left to the service to figure
645 * out using VBOXHGCMSVCHELPERS::pfnIsCallCancelled. Because this is an
646 * asynchronous call, the service may have completed the request already.
647 */
648 DECLR3CALLBACKMEMBER(void, pfnCancelled, (void *pvService, uint32_t idClient, void *pvClient));
649
650 /** Host Service entry point meant for privileged features invisible to the guest.
651 * Return code is passed to pfnCallComplete callback.
652 */
653 DECLR3CALLBACKMEMBER(int, pfnHostCall, (void *pvService, uint32_t function, uint32_t cParms, VBOXHGCMSVCPARM paParms[]));
654
655 /** Inform the service about a VM save operation. */
656 DECLR3CALLBACKMEMBER(int, pfnSaveState, (void *pvService, uint32_t u32ClientID, void *pvClient, PSSMHANDLE pSSM));
657
658 /** Inform the service about a VM load operation. */
659 DECLR3CALLBACKMEMBER(int, pfnLoadState, (void *pvService, uint32_t u32ClientID, void *pvClient, PSSMHANDLE pSSM,
660 uint32_t uVersion));
661
662 /** Register a service extension callback. */
663 DECLR3CALLBACKMEMBER(int, pfnRegisterExtension, (void *pvService, PFNHGCMSVCEXT pfnExtension, void *pvExtension));
664
665 /** Notification (VM state). */
666 DECLR3CALLBACKMEMBER(void, pfnNotify, (void *pvService, HGCMNOTIFYEVENT enmEvent));
667
668 /** User/instance data pointer for the service. */
669 void *pvService;
670
671 /** @} */
672} VBOXHGCMSVCFNTABLE;
673
674
675/** @name HGCM saved state
676 * @note Need to be here so we can add saved to service which doesn't have it.
677 * @{ */
678/** HGCM saved state version. */
679#define HGCM_SAVED_STATE_VERSION 3
680/** HGCM saved state version w/o client state indicators. */
681#define HGCM_SAVED_STATE_VERSION_V2 2
682/** @} */
683
684
685/** Service initialization entry point. */
686typedef DECLCALLBACK(int) VBOXHGCMSVCLOAD(VBOXHGCMSVCFNTABLE *ptable);
687typedef VBOXHGCMSVCLOAD *PFNVBOXHGCMSVCLOAD;
688#define VBOX_HGCM_SVCLOAD_NAME "VBoxHGCMSvcLoad"
689
690#endif /* !VBOX_INCLUDED_hgcmsvc_h */
691
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