hgcmsvc.h@ 93971

Last change on this file since 93971 was 93971, checked in by vboxsync, 3 years ago
VBox/hgcmsvc.h: Fixed typos.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 26.1 KB

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

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: