VBoxGuestR3LibGuestProp.cpp@ 68550

Last change on this file since 68550 was 68550, checked in by vboxsync, 7 years ago
merging vbglioc r117689: Initial VBoxGuest I/O control changes.
Property svn:eol-style set to `native` Property svn:keywords set to `Id Revision`
File size: 34.1 KB

Line
1	/* $Id: VBoxGuestR3LibGuestProp.cpp 68550 2017-08-31 12:09:41Z vboxsync $ */
2	/** @file
3	* VBoxGuestR3Lib - Ring-3 Support Library for VirtualBox guest additions, guest properties.
4	*/
5
6	/*
7	* Copyright (C) 2007-2016 Oracle Corporation
8	*
9	* This file is part of VirtualBox Open Source Edition (OSE), as
10	* available from http://www.virtualbox.org. This file is free software;
11	* you can redistribute it and/or modify it under the terms of the GNU
12	* General Public License (GPL) as published by the Free Software
13	* Foundation, in version 2 as it comes in the "COPYING" file of the
14	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16	*
17	* The contents of this file may alternatively be used under the terms
18	* of the Common Development and Distribution License Version 1.0
19	* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
20	* VirtualBox OSE distribution, in which case the provisions of the
21	* CDDL are applicable instead of those of the GPL.
22	*
23	* You may elect to license modified versions of this file under the
24	* terms and conditions of either the GPL or the CDDL or both.
25	*/
26
27	#if defined(VBOX_VBGLR3_XFREE86) \|\| defined(VBOX_VBGLR3_XORG)
28	# define VBOX_VBGLR3_XSERVER
29	#endif
30
31
32	/*********************************************************************************************************************************
33	* Header Files *
34	*********************************************************************************************************************************/
35	#include <iprt/string.h>
36	#ifndef VBOX_VBGLR3_XSERVER
37	# include <iprt/mem.h>
38	#endif
39	#include <iprt/assert.h>
40	#include <iprt/stdarg.h>
41	#include <VBox/log.h>
42	#include <VBox/HostServices/GuestPropertySvc.h>
43
44	#include "VBGLR3Internal.h"
45
46	#ifdef VBOX_VBGLR3_XFREE86
47	/* Rather than try to resolve all the header file conflicts, I will just
48	prototype what we need here. */
49	extern "C" char* xf86strcpy(char,const char);
50	# undef strcpy
51	# define strcpy xf86strcpy
52	extern "C" void* xf86memchr(const void*,int,xf86size_t);
53	# undef memchr
54	# define memchr xf86memchr
55	extern "C" void* xf86memset(const void*,int,xf86size_t);
56	# undef memset
57	# define memset xf86memset
58
59	#endif /* VBOX_VBGLR3_XFREE86 */
60
61	#ifdef VBOX_VBGLR3_XSERVER
62
63	# undef RTStrEnd
64	# define RTStrEnd xf86RTStrEnd
65
66	DECLINLINE(char const ) RTStrEnd(char const pszString, size_t cchMax)
67	{
68	/* Avoid potential issues with memchr seen in glibc.
69	* See sysdeps/x86_64/memchr.S in glibc versions older than 2.11 */
70	while (cchMax > RTSTR_MEMCHR_MAX)
71	{
72	char const pszRet = (char const )memchr(pszString, '\0', RTSTR_MEMCHR_MAX);
73	if (RT_LIKELY(pszRet))
74	return pszRet;
75	pszString += RTSTR_MEMCHR_MAX;
76	cchMax -= RTSTR_MEMCHR_MAX;
77	}
78	return (char const *)memchr(pszString, '\0', cchMax);
79	}
80
81	DECLINLINE(char ) RTStrEnd(char pszString, size_t cchMax)
82	{
83	/* Avoid potential issues with memchr seen in glibc.
84	* See sysdeps/x86_64/memchr.S in glibc versions older than 2.11 */
85	while (cchMax > RTSTR_MEMCHR_MAX)
86	{
87	char pszRet = (char )memchr(pszString, '\0', RTSTR_MEMCHR_MAX);
88	if (RT_LIKELY(pszRet))
89	return pszRet;
90	pszString += RTSTR_MEMCHR_MAX;
91	cchMax -= RTSTR_MEMCHR_MAX;
92	}
93	return (char *)memchr(pszString, '\0', cchMax);
94	}
95
96	#endif /* VBOX_VBGLR3_XSERVER */
97
98
99	/*********************************************************************************************************************************
100	* Structures and Typedefs *
101	*********************************************************************************************************************************/
102	/**
103	* Structure containing information needed to enumerate through guest
104	* properties.
105	*
106	* @remarks typedef in VBoxGuestLib.h.
107	*/
108	struct VBGLR3GUESTPROPENUM
109	{
110	/** @todo add a magic and validate the handle. */
111	/** The buffer containing the raw enumeration data */
112	char *pchBuf;
113	/** The end of the buffer */
114	char *pchBufEnd;
115	/** Pointer to the next entry to enumerate inside the buffer */
116	char *pchNext;
117	};
118
119	using namespace guestProp;
120
121	/**
122	* Connects to the guest property service.
123	*
124	* @returns VBox status code
125	* @returns VERR_NOT_SUPPORTED if guest properties are not available on the host.
126	* @param pidClient Where to put the client ID on success. The client ID
127	* must be passed to all the other calls to the service.
128	*/
129	VBGLR3DECL(int) VbglR3GuestPropConnect(HGCMCLIENTID *pidClient)
130	{
131	int rc = VbglR3HGCMConnect("VBoxGuestPropSvc", pidClient);
132	if (rc == VERR_NOT_IMPLEMENTED \|\| rc == VERR_HGCM_SERVICE_NOT_FOUND)
133	rc = VERR_NOT_SUPPORTED;
134	return rc;
135	}
136
137
138	/**
139	* Disconnect from the guest property service.
140	*
141	* @returns VBox status code.
142	* @param idClient The client id returned by VbglR3InfoSvcConnect().
143	*/
144	VBGLR3DECL(int) VbglR3GuestPropDisconnect(HGCMCLIENTID idClient)
145	{
146	return VbglR3HGCMDisconnect(idClient);
147	}
148
149
150	/**
151	* Write a property value.
152	*
153	* @returns VBox status code.
154	* @param idClient The client id returned by VbglR3InvsSvcConnect().
155	* @param pszName The property to save to. Utf8
156	* @param pszValue The value to store. Utf8. If this is NULL then
157	* the property will be removed.
158	* @param pszFlags The flags for the property
159	*/
160	VBGLR3DECL(int) VbglR3GuestPropWrite(HGCMCLIENTID idClient, const char pszName, const char pszValue, const char *pszFlags)
161	{
162	int rc;
163
164	if (pszValue != NULL)
165	{
166	SetProperty Msg;
167	VBGL_HGCM_HDR_INIT(&Msg.hdr, idClient, SET_PROP_VALUE, 3);
168	VbglHGCMParmPtrSetString(&Msg.name, pszName);
169	VbglHGCMParmPtrSetString(&Msg.value, pszValue);
170	VbglHGCMParmPtrSetString(&Msg.flags, pszFlags);
171	rc = VbglR3HGCMCall(&Msg.hdr, sizeof(Msg));
172	}
173	else
174	{
175	DelProperty Msg;
176	VBGL_HGCM_HDR_INIT(&Msg.hdr, idClient, DEL_PROP, 1);
177	VbglHGCMParmPtrSetString(&Msg.name, pszName);
178	rc = VbglR3HGCMCall(&Msg.hdr, sizeof(Msg));
179	}
180	return rc;
181	}
182
183
184	/**
185	* Write a property value.
186	*
187	* @returns VBox status code.
188	*
189	* @param idClient The client id returned by VbglR3InvsSvcConnect().
190	* @param pszName The property to save to. Must be valid UTF-8.
191	* @param pszValue The value to store. Must be valid UTF-8.
192	* If this is NULL then the property will be removed.
193	*
194	* @note if the property already exists and pszValue is not NULL then the
195	* property's flags field will be left unchanged
196	*/
197	VBGLR3DECL(int) VbglR3GuestPropWriteValue(HGCMCLIENTID idClient, const char pszName, const char pszValue)
198	{
199	int rc;
200
201	if (pszValue != NULL)
202	{
203	SetPropertyValue Msg;
204	VBGL_HGCM_HDR_INIT(&Msg.hdr, idClient, SET_PROP_VALUE, 2);
205	VbglHGCMParmPtrSetString(&Msg.name, pszName);
206	VbglHGCMParmPtrSetString(&Msg.value, pszValue);
207	rc = VbglR3HGCMCall(&Msg.hdr, sizeof(Msg));
208	}
209	else
210	{
211	DelProperty Msg;
212	VBGL_HGCM_HDR_INIT(&Msg.hdr, idClient, DEL_PROP, 1);
213	VbglHGCMParmPtrSetString(&Msg.name, pszName);
214	rc = VbglR3HGCMCall(&Msg.hdr, sizeof(Msg));
215	}
216	return rc;
217	}
218
219	#ifndef VBOX_VBGLR3_XSERVER
220	/**
221	* Write a property value where the value is formatted in RTStrPrintfV fashion.
222	*
223	* @returns The same as VbglR3GuestPropWriteValue with the addition of VERR_NO_STR_MEMORY.
224	*
225	* @param idClient The client ID returned by VbglR3InvsSvcConnect().
226	* @param pszName The property to save to. Must be valid UTF-8.
227	* @param pszValueFormat The value format. This must be valid UTF-8 when fully formatted.
228	* @param va The format arguments.
229	*/
230	VBGLR3DECL(int) VbglR3GuestPropWriteValueV(HGCMCLIENTID idClient, const char pszName, const char pszValueFormat, va_list va)
231	{
232	/*
233	* Format the value and pass it on to the setter.
234	*/
235	int rc = VERR_NO_STR_MEMORY;
236	char *pszValue;
237	if (RTStrAPrintfV(&pszValue, pszValueFormat, va) >= 0)
238	{
239	rc = VbglR3GuestPropWriteValue(idClient, pszName, pszValue);
240	RTStrFree(pszValue);
241	}
242	return rc;
243	}
244
245
246	/**
247	* Write a property value where the value is formatted in RTStrPrintf fashion.
248	*
249	* @returns The same as VbglR3GuestPropWriteValue with the addition of VERR_NO_STR_MEMORY.
250	*
251	* @param idClient The client ID returned by VbglR3InvsSvcConnect().
252	* @param pszName The property to save to. Must be valid UTF-8.
253	* @param pszValueFormat The value format. This must be valid UTF-8 when fully formatted.
254	* @param ... The format arguments.
255	*/
256	VBGLR3DECL(int) VbglR3GuestPropWriteValueF(HGCMCLIENTID idClient, const char pszName, const char pszValueFormat, ...)
257	{
258	va_list va;
259	va_start(va, pszValueFormat);
260	int rc = VbglR3GuestPropWriteValueV(idClient, pszName, pszValueFormat, va);
261	va_end(va);
262	return rc;
263	}
264	#endif /* VBOX_VBGLR3_XSERVER */
265
266	/**
267	* Retrieve a property.
268	*
269	* @returns VBox status code.
270	* @retval VINF_SUCCESS on success, pszValue, pu64Timestamp and pszFlags
271	* containing valid data.
272	* @retval VERR_BUFFER_OVERFLOW if the scratch buffer @a pcBuf is not large
273	* enough. In this case the size needed will be placed in
274	* @a pcbBufActual if it is not NULL.
275	* @retval VERR_NOT_FOUND if the key wasn't found.
276	*
277	* @param idClient The client id returned by VbglR3GuestPropConnect().
278	* @param pszName The value to read. Utf8
279	* @param pvBuf A scratch buffer to store the data retrieved into.
280	* The returned data is only valid for it's lifetime.
281	* @a ppszValue will point to the start of this buffer.
282	* @param cbBuf The size of @a pcBuf
283	* @param ppszValue Where to store the pointer to the value retrieved.
284	* Optional.
285	* @param pu64Timestamp Where to store the timestamp. Optional.
286	* @param ppszFlags Where to store the pointer to the flags. Optional.
287	* @param pcbBufActual If @a pcBuf is not large enough, the size needed.
288	* Optional.
289	*/
290	VBGLR3DECL(int) VbglR3GuestPropRead(HGCMCLIENTID idClient, const char *pszName,
291	void *pvBuf, uint32_t cbBuf,
292	char *ppszValue, uint64_t pu64Timestamp,
293	char **ppszFlags,
294	uint32_t *pcbBufActual)
295	{
296	/*
297	* Create the GET_PROP message and call the host.
298	*/
299	GetProperty Msg;
300	VBGL_HGCM_HDR_INIT(&Msg.hdr, idClient, GET_PROP, 4);
301	VbglHGCMParmPtrSetString(&Msg.name, pszName);
302	VbglHGCMParmPtrSet(&Msg.buffer, pvBuf, cbBuf);
303	VbglHGCMParmUInt64Set(&Msg.timestamp, 0);
304	VbglHGCMParmUInt32Set(&Msg.size, 0);
305
306	int rc = VbglR3HGCMCall(&Msg.hdr, sizeof(Msg));
307
308	/*
309	* The cbBufActual parameter is also returned on overflow so the call can
310	* adjust his/her buffer.
311	*/
312	if ( rc == VERR_BUFFER_OVERFLOW
313	\|\| pcbBufActual != NULL)
314	{
315	int rc2 = VbglHGCMParmUInt32Get(&Msg.size, pcbBufActual);
316	AssertRCReturn(rc2, RT_FAILURE(rc) ? rc : rc2);
317	}
318	if (RT_FAILURE(rc))
319	return rc;
320
321	/*
322	* Buffer layout: Value\0Flags\0.
323	*
324	* If the caller cares about any of these strings, make sure things are
325	* properly terminated (paranoia).
326	*/
327	if ( RT_SUCCESS(rc)
328	&& (ppszValue != NULL \|\| ppszFlags != NULL))
329	{
330	/* Validate / skip 'Name'. */
331	char pszFlags = RTStrEnd((char )pvBuf, cbBuf) + 1;
332	AssertPtrReturn(pszFlags, VERR_TOO_MUCH_DATA);
333	if (ppszValue)
334	ppszValue = (char )pvBuf;
335
336	if (ppszFlags)
337	{
338	/* Validate 'Flags'. */
339	char pszEos = RTStrEnd(pszFlags, cbBuf - (pszFlags - (char )pvBuf));
340	AssertPtrReturn(pszEos, VERR_TOO_MUCH_DATA);
341	*ppszFlags = pszFlags;
342	}
343	}
344
345	/* And the timestamp, if requested. */
346	if (pu64Timestamp != NULL)
347	{
348	rc = VbglHGCMParmUInt64Get(&Msg.timestamp, pu64Timestamp);
349	AssertRCReturn(rc, rc);
350	}
351
352	return VINF_SUCCESS;
353	}
354
355	#ifndef VBOX_VBGLR3_XSERVER
356	/**
357	* Retrieve a property value, allocating space for it.
358	*
359	* @returns VBox status code.
360	* @retval VINF_SUCCESS on success, *ppszValue containing valid data.
361	* @retval VERR_NOT_FOUND if the key wasn't found.
362	* @retval VERR_TOO_MUCH_DATA if we were unable to determine the right size
363	* to allocate for the buffer. This can happen as the result of a
364	* race between our allocating space and the host changing the
365	* property value.
366	*
367	* @param idClient The client id returned by VbglR3GuestPropConnect().
368	* @param pszName The value to read. Must be valid UTF-8.
369	* @param ppszValue Where to store the pointer to the value returned.
370	* This is always set to NULL or to the result, even
371	* on failure.
372	*/
373	VBGLR3DECL(int) VbglR3GuestPropReadValueAlloc(HGCMCLIENTID idClient, const char pszName, char *ppszValue)
374	{
375	/*
376	* Quick input validation.
377	*/
378	AssertPtr(ppszValue);
379	*ppszValue = NULL;
380	AssertPtrReturn(pszName, VERR_INVALID_PARAMETER);
381
382	/*
383	* There is a race here between our reading the property size and the
384	* host changing the value before we read it. Try up to ten times and
385	* report the problem if that fails.
386	*/
387	char *pszValue = NULL;
388	void *pvBuf = NULL;
389	uint32_t cchBuf = MAX_VALUE_LEN;
390	int rc = VERR_BUFFER_OVERFLOW;
391	for (unsigned i = 0; i < 10 && rc == VERR_BUFFER_OVERFLOW; ++i)
392	{
393	/* We leave a bit of space here in case the maximum value is raised. */
394	cchBuf += 1024;
395	void *pvTmpBuf = RTMemRealloc(pvBuf, cchBuf);
396	if (pvTmpBuf)
397	{
398	pvBuf = pvTmpBuf;
399	rc = VbglR3GuestPropRead(idClient, pszName, pvBuf, cchBuf,
400	&pszValue, NULL, NULL, &cchBuf);
401	}
402	else
403	rc = VERR_NO_MEMORY;
404	}
405	if (RT_SUCCESS(rc))
406	{
407	Assert(pszValue == (char *)pvBuf);
408	*ppszValue = pszValue;
409	}
410	else
411	{
412	RTMemFree(pvBuf);
413	if (rc == VERR_BUFFER_OVERFLOW)
414	/* VERR_BUFFER_OVERFLOW has a different meaning here as a
415	* return code, but we need to report the race. */
416	rc = VERR_TOO_MUCH_DATA;
417	}
418
419	return rc;
420	}
421
422
423	/**
424	* Free the memory used by VbglR3GuestPropReadValueAlloc for returning a
425	* value.
426	*
427	* @param pszValue the memory to be freed. NULL pointers will be ignored.
428	*/
429	VBGLR3DECL(void) VbglR3GuestPropReadValueFree(char *pszValue)
430	{
431	RTMemFree(pszValue);
432	}
433	#endif /* VBOX_VBGLR3_XSERVER */
434
435	/**
436	* Retrieve a property value, using a user-provided buffer to store it.
437	*
438	* @returns VBox status code.
439	* @retval VINF_SUCCESS on success, pszValue containing valid data.
440	* @retval VERR_BUFFER_OVERFLOW and the size needed in pcchValueActual if the
441	* buffer provided was too small
442	* @retval VERR_NOT_FOUND if the key wasn't found.
443	*
444	* @note There is a race here between obtaining the size of the buffer
445	* needed to hold the value and the value being updated.
446	*
447	* @param idClient The client id returned by VbglR3GuestPropConnect().
448	* @param pszName The value to read. Utf8
449	* @param pszValue Where to store the value retrieved.
450	* @param cchValue The size of the buffer pointed to by @a pszValue
451	* @param pcchValueActual Where to store the size of the buffer needed if
452	* the buffer supplied is too small. Optional.
453	*/
454	VBGLR3DECL(int) VbglR3GuestPropReadValue(HGCMCLIENTID idClient, const char *pszName,
455	char *pszValue, uint32_t cchValue,
456	uint32_t *pcchValueActual)
457	{
458	void *pvBuf = pszValue;
459	uint32_t cchValueActual;
460	int rc = VbglR3GuestPropRead(idClient, pszName, pvBuf, cchValue, &pszValue, NULL, NULL, &cchValueActual);
461	if (pcchValueActual != NULL)
462	*pcchValueActual = cchValueActual;
463	return rc;
464	}
465
466
467	#ifndef VBOX_VBGLR3_XSERVER
468	/**
469	* Raw API for enumerating guest properties which match a given pattern.
470	*
471	* @returns VBox status code.
472	* @retval VINF_SUCCESS on success and pcBuf points to a packed array
473	* of the form \<name\>, \<value\>, \<timestamp string\>, \<flags\>,
474	* terminated by four empty strings. pcbBufActual will contain the
475	* total size of the array.
476	* @retval VERR_BUFFER_OVERFLOW if the buffer provided was too small. In
477	* this case pcbBufActual will contain the size of the buffer needed.
478	* @returns IPRT error code in other cases, and pchBufActual is undefined.
479	*
480	* @param idClient The client ID returned by VbglR3GuestPropConnect
481	* @param pszzPatterns A packed array of zero terminated strings, terminated
482	* by an empty string.
483	* @param pcBuf The buffer to store the results to.
484	* @param cbBuf The size of the buffer
485	* @param pcbBufActual Where to store the size of the returned data on
486	* success or the buffer size needed if @a pcBuf is too
487	* small.
488	*/
489	VBGLR3DECL(int) VbglR3GuestPropEnumRaw(HGCMCLIENTID idClient,
490	const char *pszzPatterns,
491	char *pcBuf,
492	uint32_t cbBuf,
493	uint32_t *pcbBufActual)
494	{
495	EnumProperties Msg;
496	VBGL_HGCM_HDR_INIT(&Msg.hdr, idClient, ENUM_PROPS, 3);
497
498	/* Get the length of the patterns array... */
499	size_t cchPatterns = 0;
500	for (size_t cchCurrent = strlen(pszzPatterns); cchCurrent != 0;
501	cchCurrent = strlen(pszzPatterns + cchPatterns))
502	cchPatterns += cchCurrent + 1;
503	/* ...including the terminator. */
504	++cchPatterns;
505	VbglHGCMParmPtrSet(&Msg.patterns, (char *)pszzPatterns, (uint32_t)cchPatterns);
506	VbglHGCMParmPtrSet(&Msg.strings, pcBuf, cbBuf);
507	VbglHGCMParmUInt32Set(&Msg.size, 0);
508
509	int rc = VbglR3HGCMCall(&Msg.hdr, sizeof(Msg));
510	if ( pcbBufActual
511	&& ( RT_SUCCESS(rc)
512	\|\| rc == VERR_BUFFER_OVERFLOW))
513	{
514	int rc2 = VbglHGCMParmUInt32Get(&Msg.size, pcbBufActual);
515	if (RT_FAILURE(rc2))
516	rc = rc2;
517	}
518	return rc;
519	}
520
521
522	/**
523	* Start enumerating guest properties which match a given pattern.
524	*
525	* This function creates a handle which can be used to continue enumerating.
526	*
527	* @returns VBox status code.
528	* @retval VINF_SUCCESS on success, *ppHandle points to a handle for continuing
529	* the enumeration and ppszName, ppszValue, *pu64Timestamp and
530	* *ppszFlags are set.
531	* @retval VERR_TOO_MUCH_DATA if it was not possible to determine the amount
532	* of local space needed to store all the enumeration data. This is
533	* due to a race between allocating space and the host adding new
534	* data, so retrying may help here. Other parameters are left
535	* uninitialised
536	*
537	* @param idClient The client id returned by VbglR3InfoSvcConnect().
538	* @param papszPatterns The patterns against which the properties are
539	* matched. Pass NULL if everything should be matched.
540	* @param cPatterns The number of patterns in @a papszPatterns. 0 means
541	* match everything.
542	* @param ppHandle where the handle for continued enumeration is stored
543	* on success. This must be freed with
544	* VbglR3GuestPropEnumFree when it is no longer needed.
545	* @param ppszName Where to store the next property name. This will be
546	* set to NULL if there are no more properties to
547	* enumerate. This pointer should not be freed. Optional.
548	* @param ppszValue Where to store the next property value. This will be
549	* set to NULL if there are no more properties to
550	* enumerate. This pointer should not be freed. Optional.
551	* @param pu64Timestamp Where to store the next property timestamp. This
552	* will be set to zero if there are no more properties
553	* to enumerate. Optional.
554	* @param ppszFlags Where to store the next property flags. This will be
555	* set to NULL if there are no more properties to
556	* enumerate. This pointer should not be freed. Optional.
557	*
558	* @remarks While all output parameters are optional, you need at least one to
559	* figure out when to stop.
560	*/
561	VBGLR3DECL(int) VbglR3GuestPropEnum(HGCMCLIENTID idClient,
562	char const * const *papszPatterns,
563	uint32_t cPatterns,
564	PVBGLR3GUESTPROPENUM *ppHandle,
565	char const **ppszName,
566	char const **ppszValue,
567	uint64_t *pu64Timestamp,
568	char const **ppszFlags)
569	{
570	/* Create the handle. */
571	PVBGLR3GUESTPROPENUM pHandle = (PVBGLR3GUESTPROPENUM)RTMemAllocZ(sizeof(VBGLR3GUESTPROPENUM));
572	if (RT_LIKELY(pHandle))
573	{/* likely */}
574	else
575	return VERR_NO_MEMORY;
576
577	/* Get the length of the pattern string, including the final terminator. */
578	size_t cbPatterns = 1;
579	for (uint32_t i = 0; i < cPatterns; ++i)
580	cbPatterns += strlen(papszPatterns[i]) + 1;
581
582	/* Pack the pattern array. */
583	char pszzPatterns = (char )RTMemAlloc(cbPatterns);
584	size_t off = 0;
585	for (uint32_t i = 0; i < cPatterns; ++i)
586	{
587	size_t cb = strlen(papszPatterns[i]) + 1;
588	memcpy(&pszzPatterns[off], papszPatterns[i], cb);
589	off += cb;
590	}
591	pszzPatterns[off] = '\0';
592
593	/* In reading the guest property data we are racing against the host
594	* adding more of it, so loop a few times and retry on overflow. */
595	uint32_t cbBuf = 4096; /* picked out of thin air */
596	char *pchBuf = NULL;
597	int rc = VINF_SUCCESS;
598	for (int i = 0; i < 10; ++i)
599	{
600	void *pvNew = RTMemRealloc(pchBuf, cbBuf);
601	if (pvNew)
602	pchBuf = (char *)pvNew;
603	else
604	{
605	rc = VERR_NO_MEMORY;
606	break;
607	}
608	rc = VbglR3GuestPropEnumRaw(idClient, pszzPatterns, pchBuf, cbBuf, &cbBuf);
609	if (rc != VERR_BUFFER_OVERFLOW)
610	break;
611	cbBuf += 4096; /* Just to increase our chances */
612	}
613	RTMemFree(pszzPatterns);
614	if (RT_SUCCESS(rc))
615	{
616	/*
617	* Complete the handle and call VbglR3GuestPropEnumNext to retrieve the first entry.
618	*/
619	pHandle->pchNext = pchBuf;
620	pHandle->pchBuf = pchBuf;
621	pHandle->pchBufEnd = pchBuf + cbBuf;
622
623	const char *pszNameTmp;
624	if (!ppszName)
625	ppszName = &pszNameTmp;
626	rc = VbglR3GuestPropEnumNext(pHandle, ppszName, ppszValue, pu64Timestamp, ppszFlags);
627	if (RT_SUCCESS(rc))
628	{
629	*ppHandle = pHandle;
630	return rc;
631	}
632	}
633	else if (rc == VERR_BUFFER_OVERFLOW)
634	rc = VERR_TOO_MUCH_DATA;
635	RTMemFree(pchBuf);
636	RTMemFree(pHandle);
637	return rc;
638	}
639
640
641	/**
642	* Get the next guest property.
643	*
644	* See @a VbglR3GuestPropEnum.
645	*
646	* @returns VBox status code.
647	*
648	* @param pHandle Handle obtained from @a VbglR3GuestPropEnum.
649	* @param ppszName Where to store the next property name. This will be
650	* set to NULL if there are no more properties to
651	* enumerate. This pointer should not be freed. Optional.
652	* @param ppszValue Where to store the next property value. This will be
653	* set to NULL if there are no more properties to
654	* enumerate. This pointer should not be freed. Optional.
655	* @param pu64Timestamp Where to store the next property timestamp. This
656	* will be set to zero if there are no more properties
657	* to enumerate. Optional.
658	* @param ppszFlags Where to store the next property flags. This will be
659	* set to NULL if there are no more properties to
660	* enumerate. This pointer should not be freed. Optional.
661	*
662	* @remarks While all output parameters are optional, you need at least one to
663	* figure out when to stop.
664	*/
665	VBGLR3DECL(int) VbglR3GuestPropEnumNext(PVBGLR3GUESTPROPENUM pHandle,
666	char const **ppszName,
667	char const **ppszValue,
668	uint64_t *pu64Timestamp,
669	char const **ppszFlags)
670	{
671	/*
672	* The VBGLR3GUESTPROPENUM structure contains a buffer containing the raw
673	* properties data and a pointer into the buffer which tracks how far we
674	* have parsed so far. The buffer contains packed strings in groups of
675	* four - name, value, timestamp (as a decimal string) and flags. It is
676	* terminated by four empty strings. We can rely on this layout unless
677	* the caller has been poking about in the structure internals, in which
678	* case they must take responsibility for the results.
679	*
680	* Layout:
681	* Name\0Value\0Timestamp\0Flags\0
682	*/
683	char pchNext = pHandle->pchNext; / The cursor. */
684	char pchEnd = pHandle->pchBufEnd; / End of buffer, for size calculations. */
685
686	char *pszName = pchNext;
687	char *pszValue = pchNext = RTStrEnd(pchNext, pchEnd - pchNext) + 1;
688	AssertPtrReturn(pchNext, VERR_PARSE_ERROR); /* 0x1 is also an invalid pointer :) */
689
690	char *pszTimestamp = pchNext = RTStrEnd(pchNext, pchEnd - pchNext) + 1;
691	AssertPtrReturn(pchNext, VERR_PARSE_ERROR);
692
693	char *pszFlags = pchNext = RTStrEnd(pchNext, pchEnd - pchNext) + 1;
694	AssertPtrReturn(pchNext, VERR_PARSE_ERROR);
695
696	/*
697	* Don't move the index pointer if we found the terminating "\0\0\0\0" entry.
698	* Don't try convert the timestamp either.
699	*/
700	uint64_t u64Timestamp;
701	if (*pszName != '\0')
702	{
703	pchNext = RTStrEnd(pchNext, pchEnd - pchNext) + 1;
704	AssertPtrReturn(pchNext, VERR_PARSE_ERROR);
705
706	/* Convert the timestamp string into a number. */
707	int rc = RTStrToUInt64Full(pszTimestamp, 0, &u64Timestamp);
708	AssertRCSuccessReturn(rc, VERR_PARSE_ERROR);
709
710	pHandle->pchNext = pchNext;
711	AssertPtr(pchNext);
712	}
713	else
714	{
715	u64Timestamp = 0;
716	AssertMsgReturn(!pszValue && !pszTimestamp && !*pszFlags,
717	("'%s' '%s' '%s'\n", pszValue, pszTimestamp, pszFlags),
718	VERR_PARSE_ERROR);
719	}
720
721	/*
722	* Everything is fine, set the return values.
723	*/
724	if (ppszName)
725	ppszName = pszName != '\0' ? pszName : NULL;
726	if (ppszValue)
727	ppszValue = pszValue != '\0' ? pszValue : NULL;
728	if (pu64Timestamp)
729	*pu64Timestamp = u64Timestamp;
730	if (ppszFlags)
731	ppszFlags = pszFlags != '\0' ? pszFlags : NULL;
732	return VINF_SUCCESS;
733	}
734
735
736	/**
737	* Free an enumeration handle returned by @a VbglR3GuestPropEnum.
738	* @param pHandle the handle to free
739	*/
740	VBGLR3DECL(void) VbglR3GuestPropEnumFree(PVBGLR3GUESTPROPENUM pHandle)
741	{
742	if (!pHandle)
743	return;
744	RTMemFree(pHandle->pchBuf);
745	RTMemFree(pHandle);
746	}
747
748
749	/**
750	* Deletes a guest property.
751	*
752	* @returns VBox status code.
753	* @param idClient The client id returned by VbglR3InvsSvcConnect().
754	* @param pszName The property to delete. Utf8
755	*/
756	VBGLR3DECL(int) VbglR3GuestPropDelete(HGCMCLIENTID idClient, const char *pszName)
757	{
758	AssertPtrReturn(pszName, VERR_INVALID_POINTER);
759
760	DelProperty Msg;
761	VBGL_HGCM_HDR_INIT(&Msg.hdr, idClient, DEL_PROP, 1);
762	VbglHGCMParmPtrSetString(&Msg.name, pszName);
763	return VbglR3HGCMCall(&Msg.hdr, sizeof(Msg));
764	}
765
766
767	/**
768	* Deletes a set of keys.
769	*
770	* The set is specified in the same way as for VbglR3GuestPropEnum.
771	*
772	* @returns VBox status code. Stops on first failure.
773	* See also VbglR3GuestPropEnum.
774	*
775	* @param idClient The client id returned by VbglR3InfoSvcConnect().
776	* @param papszPatterns The patterns against which the properties are
777	* matched. Pass NULL if everything should be matched.
778	* @param cPatterns The number of patterns in @a papszPatterns. 0 means
779	* match everything.
780	*/
781	VBGLR3DECL(int) VbglR3GuestPropDelSet(HGCMCLIENTID idClient,
782	const char * const *papszPatterns,
783	uint32_t cPatterns)
784	{
785	PVBGLR3GUESTPROPENUM pHandle;
786	char const pszName, pszValue, *pszFlags;
787	uint64_t pu64Timestamp;
788	int rc = VbglR3GuestPropEnum(idClient,
789	(char )papszPatterns, / @todo fix this cast. */
790	cPatterns,
791	&pHandle,
792	&pszName,
793	&pszValue,
794	&pu64Timestamp,
795	&pszFlags);
796
797	while (RT_SUCCESS(rc) && pszName)
798	{
799	rc = VbglR3GuestPropWriteValue(idClient, pszName, NULL);
800	if (RT_FAILURE(rc))
801	break;
802
803	rc = VbglR3GuestPropEnumNext(pHandle,
804	&pszName,
805	&pszValue,
806	&pu64Timestamp,
807	&pszFlags);
808	}
809
810	VbglR3GuestPropEnumFree(pHandle);
811	return rc;
812	}
813
814
815	/**
816	* Wait for notification of changes to a guest property. If this is called in
817	* a loop, the timestamp of the last notification seen can be passed as a
818	* parameter to be sure that no notifications are missed.
819	*
820	* @returns VBox status code.
821	* @retval VINF_SUCCESS on success, @a ppszName, @a ppszValue,
822	* @a pu64Timestamp and @a ppszFlags containing valid data.
823	* @retval VINF_NOT_FOUND if no previous notification could be found with the
824	* timestamp supplied. This will normally mean that a large number
825	* of notifications occurred in between.
826	* @retval VERR_BUFFER_OVERFLOW if the scratch buffer @a pvBuf is not large
827	* enough. In this case the size needed will be placed in
828	* @a pcbBufActual if it is not NULL.
829	* @retval VERR_TIMEOUT if a timeout occurred before a notification was seen.
830	*
831	* @param idClient The client id returned by VbglR3GuestPropConnect().
832	* @param pszPatterns The patterns that the property names must matchfor
833	* the change to be reported.
834	* @param pvBuf A scratch buffer to store the data retrieved into.
835	* The returned data is only valid for it's lifetime.
836	* @a ppszValue will point to the start of this buffer.
837	* @param cbBuf The size of @a pvBuf
838	* @param u64Timestamp The timestamp of the last event seen. Pass zero
839	* to wait for the next event.
840	* @param cMillies Timeout in milliseconds. Use RT_INDEFINITE_WAIT
841	* to wait indefinitely.
842	* @param ppszName Where to store the pointer to the name retrieved.
843	* Optional.
844	* @param ppszValue Where to store the pointer to the value retrieved.
845	* Optional.
846	* @param pu64Timestamp Where to store the timestamp. Optional.
847	* @param ppszFlags Where to store the pointer to the flags. Optional.
848	* @param pcbBufActual If @a pcBuf is not large enough, the size needed.
849	* Optional.
850	*/
851	VBGLR3DECL(int) VbglR3GuestPropWait(HGCMCLIENTID idClient,
852	const char *pszPatterns,
853	void *pvBuf, uint32_t cbBuf,
854	uint64_t u64Timestamp, uint32_t cMillies,
855	char ppszName, char ppszValue,
856	uint64_t pu64Timestamp, char *ppszFlags,
857	uint32_t *pcbBufActual)
858	{
859	/*
860	* Create the GET_NOTIFICATION message and call the host.
861	*/
862	GetNotification Msg;
863	VBGL_HGCM_HDR_INIT_TIMED(&Msg.hdr, idClient, GET_NOTIFICATION, 4, cMillies);
864
865	VbglHGCMParmPtrSetString(&Msg.patterns, pszPatterns);
866	Msg.buffer.SetPtr(pvBuf, cbBuf);
867	Msg.timestamp.SetUInt64(u64Timestamp);
868	Msg.size.SetUInt32(0);
869
870	int rc = VbglR3HGCMCall(&Msg.hdr, sizeof(Msg));
871
872	/*
873	* The cbBufActual parameter is also returned on overflow so the caller can
874	* adjust their buffer.
875	*/
876	if ( rc == VERR_BUFFER_OVERFLOW
877	\|\| pcbBufActual != NULL)
878	{
879	int rc2 = Msg.size.GetUInt32(pcbBufActual);
880	AssertRCReturn(rc2, RT_FAILURE(rc) ? rc : rc2);
881	}
882	if (RT_FAILURE(rc))
883	return rc;
884
885	/*
886	* Buffer layout: Name\0Value\0Flags\0.
887	*
888	* If the caller cares about any of these strings, make sure things are
889	* properly terminated (paranoia).
890	*/
891	if ( RT_SUCCESS(rc)
892	&& (ppszName != NULL \|\| ppszValue != NULL \|\| ppszFlags != NULL))
893	{
894	/* Validate / skip 'Name'. */
895	char pszValue = RTStrEnd((char )pvBuf, cbBuf) + 1;
896	AssertPtrReturn(pszValue, VERR_TOO_MUCH_DATA);
897	if (ppszName)
898	ppszName = (char )pvBuf;
899
900	/* Validate / skip 'Value'. */
901	char pszFlags = RTStrEnd(pszValue, cbBuf - (pszValue - (char )pvBuf)) + 1;
902	AssertPtrReturn(pszFlags, VERR_TOO_MUCH_DATA);
903	if (ppszValue)
904	*ppszValue = pszValue;
905
906	if (ppszFlags)
907	{
908	/* Validate 'Flags'. */
909	char pszEos = RTStrEnd(pszFlags, cbBuf - (pszFlags - (char )pvBuf));
910	AssertPtrReturn(pszEos, VERR_TOO_MUCH_DATA);
911	*ppszFlags = pszFlags;
912	}
913	}
914
915	/* And the timestamp, if requested. */
916	if (pu64Timestamp != NULL)
917	{
918	rc = Msg.timestamp.GetUInt64(pu64Timestamp);
919	AssertRCReturn(rc, rc);
920	}
921
922	return VINF_SUCCESS;
923	}
924	#endif /* VBOX_VBGLR3_XSERVER */

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

source: vbox/trunk/src/VBox/Additions/common/VBoxGuestLib/VBoxGuestR3LibGuestProp.cpp@ 68550

Download in other formats: