hgcmsvc.h@ 21644

Last change on this file since 21644 was 21625, checked in by vboxsync, 15 years ago
HostServices: attempt to fix a burn
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 13.6 KB

Line
1	/** @file
2	* Host-Guest Communication Manager (HGCM) - Service library definitions.
3	*/
4
5	/*
6	* Copyright (C) 2006-2007 Sun Microsystems, Inc.
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	* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
26	* Clara, CA 95054 USA or visit http://www.sun.com if you need
27	* additional information or have any questions.
28	*/
29
30	#ifndef ___VBox_hgcm_h
31	#define ___VBox_hgcm_h
32
33	#include <iprt/assert.h>
34	#include <iprt/stdint.h>
35	#include <iprt/string.h>
36	#include <VBox/cdefs.h>
37	#include <VBox/types.h>
38	#include <VBox/err.h>
39	#ifdef VBOX_TEST_HGCM_PARMS
40	# include <iprt/test.h>
41	#endif
42
43	/** @todo proper comments. */
44
45	/**
46	* Service interface version.
47	*
48	* Includes layout of both VBOXHGCMSVCFNTABLE and VBOXHGCMSVCHELPERS.
49	*
50	* A service can work with these structures if major version
51	* is equal and minor version of service is <= version of the
52	* structures.
53	*
54	* For example when a new helper is added at the end of helpers
55	* structure, then the minor version will be increased. All older
56	* services still can work because they have their old helpers
57	* unchanged.
58	*
59	* Revision history.
60	* 1.1->2.1 Because the pfnConnect now also has the pvClient parameter.
61	* 2.1->2.2 Because pfnSaveState and pfnLoadState were added
62	* 2.2->3.1 Because pfnHostCall is now synchronous, returns rc, and parameters were changed
63	* 3.1->3.2 Because pfnRegisterExtension was added
64	* 3.2->3.3 Because pfnDisconnectClient helper was added
65	* 3.3->4.1 Because the pvService entry and parameter was added
66	* 4.1->4.2 Because the VBOX_HGCM_SVC_PARM_CALLBACK parameter type was added
67	* 4.2->5.1 Removed the VBOX_HGCM_SVC_PARM_CALLBACK parameter type, as
68	* this problem is already solved by service extension callbacks
69	*/
70	#define VBOX_HGCM_SVC_VERSION_MAJOR (0x0005)
71	#define VBOX_HGCM_SVC_VERSION_MINOR (0x0001)
72	#define VBOX_HGCM_SVC_VERSION ((VBOX_HGCM_SVC_VERSION_MAJOR << 16) + VBOX_HGCM_SVC_VERSION_MINOR)
73
74
75	/** Typed pointer to distinguish a call to service. */
76	struct VBOXHGCMCALLHANDLE_TYPEDEF;
77	typedef struct VBOXHGCMCALLHANDLE_TYPEDEF *VBOXHGCMCALLHANDLE;
78
79	/** Service helpers pointers table. */
80	typedef struct _VBOXHGCMSVCHELPERS
81	{
82	/** The service has processed the Call request. */
83	DECLR3CALLBACKMEMBER(void, pfnCallComplete, (VBOXHGCMCALLHANDLE callHandle, int32_t rc));
84
85	void *pvInstance;
86
87	/** The service disconnects the client. */
88	DECLR3CALLBACKMEMBER(void, pfnDisconnectClient, (void *pvInstance, uint32_t u32ClientID));
89	} VBOXHGCMSVCHELPERS;
90
91	typedef VBOXHGCMSVCHELPERS *PVBOXHGCMSVCHELPERS;
92
93
94	#define VBOX_HGCM_SVC_PARM_INVALID (0U)
95	#define VBOX_HGCM_SVC_PARM_32BIT (1U)
96	#define VBOX_HGCM_SVC_PARM_64BIT (2U)
97	#define VBOX_HGCM_SVC_PARM_PTR (3U)
98
99	typedef struct VBOXHGCMSVCPARM
100	{
101	/** VBOX_HGCM_SVC_PARM_* values. */
102	uint32_t type;
103
104	union
105	{
106	uint32_t uint32;
107	uint64_t uint64;
108	struct
109	{
110	uint32_t size;
111	void *addr;
112	} pointer;
113	} u;
114	#ifdef __cplusplus
115	/** Extract a uint32_t value from an HGCM parameter structure */
116	int getUInt32 (uint32_t *u32)
117	{
118	AssertPtrReturn(u32, VERR_INVALID_POINTER);
119	int rc = VINF_SUCCESS;
120	if (type != VBOX_HGCM_SVC_PARM_32BIT)
121	rc = VERR_INVALID_PARAMETER;
122	if (RT_SUCCESS(rc))
123	*u32 = u.uint32;
124	return rc;
125	}
126
127	/** Extract a uint64_t value from an HGCM parameter structure */
128	int getUInt64 (uint64_t *u64)
129	{
130	AssertPtrReturn(u64, VERR_INVALID_POINTER);
131	int rc = VINF_SUCCESS;
132	if (type != VBOX_HGCM_SVC_PARM_64BIT)
133	rc = VERR_INVALID_PARAMETER;
134	if (RT_SUCCESS(rc))
135	*u64 = u.uint64;
136	return rc;
137	}
138
139	/** Extract a pointer value from an HGCM parameter structure */
140	int getPointer (void *ppv, uint32_t pcb)
141	{
142	AssertPtrReturn(ppv, VERR_INVALID_POINTER);
143	AssertPtrReturn(pcb, VERR_INVALID_POINTER);
144	if (type == VBOX_HGCM_SVC_PARM_PTR)
145	{
146	*ppv = u.pointer.addr;
147	*pcb = u.pointer.size;
148	return VINF_SUCCESS;
149	}
150
151	return VERR_INVALID_PARAMETER;
152	}
153
154	/** Extract a constant pointer value from an HGCM parameter structure */
155	int getPointer (const void *ppcv, uint32_t pcb)
156	{
157	AssertPtrReturn(ppcv, VERR_INVALID_POINTER);
158	AssertPtrReturn(pcb, VERR_INVALID_POINTER);
159	void *pv;
160	int rc = getPointer(&pv, pcb);
161	*ppcv = pv;
162	return rc;
163	}
164
165	/** Extract a pointer value to a non-empty buffer from an HGCM parameter
166	* structure */
167	int getBuffer (void *ppv, uint32_t pcb)
168	{
169	AssertPtrReturn(ppv, VERR_INVALID_POINTER);
170	AssertPtrReturn(pcb, VERR_INVALID_POINTER);
171	void *pv = NULL;
172	uint32_t cb = 0;
173	int rc = getPointer(&pv, &cb);
174	if ( RT_SUCCESS(rc)
175	&& VALID_PTR(pv)
176	&& cb > 0)
177	{
178	*ppv = pv;
179	*pcb = cb;
180	return VINF_SUCCESS;
181	}
182
183	return VERR_INVALID_PARAMETER;
184	}
185
186	/** Extract a pointer value to a non-empty constant buffer from an HGCM
187	* parameter structure */
188	int getBuffer (const void *ppcv, uint32_t pcb)
189	{
190	AssertPtrReturn(ppcv, VERR_INVALID_POINTER);
191	AssertPtrReturn(pcb, VERR_INVALID_POINTER);
192	void *pcv = NULL;
193	int rc = getBuffer(&pcv, pcb);
194	*ppcv = pcv;
195	return rc;
196	}
197
198	/** Extract a string value from an HGCM parameter structure */
199	int getString (char *ppch, uint32_t pcb)
200	{
201	uint32_t cb = 0;
202	char *pch = NULL;
203	int rc = getBuffer((void **)&pch, &cb);
204	if (RT_FAILURE(rc))
205	return rc;
206	rc = RTStrValidateEncodingEx(pch, cb,
207	RTSTR_VALIDATE_ENCODING_ZERO_TERMINATED);
208	*ppch = pch;
209	*pcb = cb;
210	return rc;
211	}
212
213	/** Extract a constant string value from an HGCM parameter structure */
214	int getString (const char *ppcch, uint32_t pcb)
215	{
216	char *pch = NULL;
217	int rc = getString(&pch, pcb);
218	*ppcch = pch;
219	return rc;
220	}
221
222	/** Set a uint32_t value to an HGCM parameter structure */
223	void setUInt32(uint32_t u32)
224	{
225	type = VBOX_HGCM_SVC_PARM_32BIT;
226	u.uint32 = u32;
227	}
228
229	/** Set a uint64_t value to an HGCM parameter structure */
230	void setUInt64(uint64_t u64)
231	{
232	type = VBOX_HGCM_SVC_PARM_64BIT;
233	u.uint64 = u64;
234	}
235
236	/** Set a pointer value to an HGCM parameter structure */
237	void setPointer(void *pv, uint32_t cb)
238	{
239	type = VBOX_HGCM_SVC_PARM_PTR;
240	u.pointer.addr = pv;
241	u.pointer.size = cb;
242	}
243
244	#ifdef VBOX_TEST_HGCM_PARMS
245	/** Test the getString member function. Indirectly tests the getPointer
246	* and getBuffer APIs.
247	* @param hTest an running IPRT test
248	* @param aType the type that the parameter should be set to before
249	* calling getString
250	* @param apcc the value that the parameter should be set to before
251	* calling getString, and also the address (!) which we
252	* expect getString to return. Stricter than needed of
253	* course, but I was feeling lazy.
254	* @param acb the size that the parameter should be set to before
255	* calling getString, and also the size which we expect
256	* getString to return.
257	* @param rcExp the expected return value of the call to getString.
258	*/
259	void doTestGetString(RTTEST hTest, uint32_t aType, const char *apcc,
260	uint32_t acb, int rcExp)
261	{
262	/* An RTTest API like this, which would print out an additional line
263	* of context if a test failed, would be nice. This is because the
264	* line number alone doesn't help much here, given that this is a
265	* subroutine called many times. */
266	/*
267	RTTestContextF(hTest,
268	("doTestGetString, aType=%u, apcc=%p, acp=%u, rcExp=%Rrc",
269	aType, apcc, acp, rcExp));
270	*/
271	setPointer((void *)apcc, acb);
272	type = aType; /* in case we don't want VBOX_HGCM_SVC_PARM_PTR */
273	const char *pcc = NULL;
274	uint32_t cb = 0;
275	int rc = getString(&pcc, &cb);
276	RTTEST_CHECK_RC(hTest, rc, rcExp);
277	if (RT_SUCCESS(rcExp))
278	{
279	RTTEST_CHECK_MSG_RETV(hTest, (pcc == apcc),
280	(hTest, "expected %p, got %p", apcc, pcc));
281	RTTEST_CHECK_MSG_RETV(hTest, (cb == acb),
282	(hTest, "expected %u, got %u", acb, cb));
283	}
284	}
285
286	/** Run some unit tests on the getString method and indirectly test
287	* getPointer and getBuffer as well. */
288	void testGetString(RTTEST hTest)
289	{
290	RTTestSub(hTest, "HGCM string parameter handling");
291	doTestGetString(hTest, VBOX_HGCM_SVC_PARM_32BIT, "test", 3,
292	VERR_INVALID_PARAMETER);
293	doTestGetString(hTest, VBOX_HGCM_SVC_PARM_PTR, "test", 5,
294	VINF_SUCCESS);
295	doTestGetString(hTest, VBOX_HGCM_SVC_PARM_PTR, "test", 3,
296	VERR_BUFFER_OVERFLOW);
297	doTestGetString(hTest, VBOX_HGCM_SVC_PARM_PTR, "test\xf0", 6,
298	VERR_INVALID_UTF8_ENCODING);
299	doTestGetString(hTest, VBOX_HGCM_SVC_PARM_PTR, "test", 0,
300	VERR_INVALID_PARAMETER);
301	doTestGetString(hTest, VBOX_HGCM_SVC_PARM_PTR, (const char *)0x1, 5,
302	VERR_INVALID_PARAMETER);
303	RTTestSubDone(hTest);
304	}
305	#endif
306
307	VBOXHGCMSVCPARM() : type(VBOX_HGCM_SVC_PARM_INVALID) {}
308	#endif
309	} VBOXHGCMSVCPARM;
310
311	typedef VBOXHGCMSVCPARM *PVBOXHGCMSVCPARM;
312
313	/** Service specific extension callback.
314	* This callback is called by the service to perform service specific operation.
315	*
316	* @param pvExtension The extension pointer.
317	* @param u32Function What the callback is supposed to do.
318	* @param pvParm The function parameters.
319	* @param cbParm The size of the function parameters.
320	*/
321	typedef DECLCALLBACK(int) FNHGCMSVCEXT(void pvExtension, uint32_t u32Function, void pvParm, uint32_t cbParms);
322	typedef FNHGCMSVCEXT *PFNHGCMSVCEXT;
323
324	/** The Service DLL entry points.
325	*
326	* HGCM will call the DLL "VBoxHGCMSvcLoad"
327	* function and the DLL must fill in the VBOXHGCMSVCFNTABLE
328	* with function pointers.
329	*/
330
331	/* The structure is used in separately compiled binaries so an explicit packing is required. */
332	#pragma pack(1)
333	typedef struct _VBOXHGCMSVCFNTABLE
334	{
335	/** Filled by HGCM */
336
337	/** Size of the structure. */
338	uint32_t cbSize;
339
340	/** Version of the structure, including the helpers. */
341	uint32_t u32Version;
342
343	PVBOXHGCMSVCHELPERS pHelpers;
344
345	/** Filled by the service. */
346
347	/** Size of client information the service want to have. */
348	uint32_t cbClient;
349	#if ARCH_BITS == 64
350	/** Ensure that the following pointers are properly aligned on 64-bit system. */
351	uint32_t u32Alignment0;
352	#endif
353
354	/** Uninitialize service */
355	DECLR3CALLBACKMEMBER(int, pfnUnload, (void *pvService));
356
357	/** Inform the service about a client connection. */
358	DECLR3CALLBACKMEMBER(int, pfnConnect, (void pvService, uint32_t u32ClientID, void pvClient));
359
360	/** Inform the service that the client wants to disconnect. */
361	DECLR3CALLBACKMEMBER(int, pfnDisconnect, (void pvService, uint32_t u32ClientID, void pvClient));
362
363	/** Service entry point.
364	* Return code is passed to pfnCallComplete callback.
365	*/
366	DECLR3CALLBACKMEMBER(void, pfnCall, (void pvService, VBOXHGCMCALLHANDLE callHandle, uint32_t u32ClientID, void pvClient, uint32_t function, uint32_t cParms, VBOXHGCMSVCPARM paParms[]));
367
368	/** Host Service entry point meant for privileged features invisible to the guest.
369	* Return code is passed to pfnCallComplete callback.
370	*/
371	DECLR3CALLBACKMEMBER(int, pfnHostCall, (void *pvService, uint32_t function, uint32_t cParms, VBOXHGCMSVCPARM paParms[]));
372
373	/** Inform the service about a VM save operation. */
374	DECLR3CALLBACKMEMBER(int, pfnSaveState, (void pvService, uint32_t u32ClientID, void pvClient, PSSMHANDLE pSSM));
375
376	/** Inform the service about a VM load operation. */
377	DECLR3CALLBACKMEMBER(int, pfnLoadState, (void pvService, uint32_t u32ClientID, void pvClient, PSSMHANDLE pSSM));
378
379	/** Register a service extension callback. */
380	DECLR3CALLBACKMEMBER(int, pfnRegisterExtension, (void pvService, PFNHGCMSVCEXT pfnExtension, void pvExtension));
381
382	/** User/instance data pointer for the service. */
383	void *pvService;
384
385	} VBOXHGCMSVCFNTABLE;
386	#pragma pack()
387
388
389	/** Service initialization entry point. */
390	typedef DECLCALLBACK(int) VBOXHGCMSVCLOAD(VBOXHGCMSVCFNTABLE *ptable);
391	typedef VBOXHGCMSVCLOAD *PFNVBOXHGCMSVCLOAD;
392	#define VBOX_HGCM_SVCLOAD_NAME "VBoxHGCMSvcLoad"
393
394	#endif

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

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

Download in other formats: