GuestCtrlImplPrivate.h@ 99320

Last change on this file since 99320 was 99262, checked in by vboxsync, 2 years ago
Guest Control: Implements IGuestSession::fsQueryInfo() and IGuestSession::fsQueryFreeSpace(). bugref:10414
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 51.2 KB

Line
1	/* $Id: GuestCtrlImplPrivate.h 99262 2023-04-03 15:17:07Z vboxsync $ */
2	/** @file
3	* Internal helpers/structures for guest control functionality.
4	*/
5
6	/*
7	* Copyright (C) 2011-2023 Oracle and/or its affiliates.
8	*
9	* This file is part of VirtualBox base platform packages, as
10	* available from https://www.virtualbox.org.
11	*
12	* This program is free software; you can redistribute it and/or
13	* modify it under the terms of the GNU General Public License
14	* as published by the Free Software Foundation, in version 3 of the
15	* License.
16	*
17	* This program is distributed in the hope that it will be useful, but
18	* WITHOUT ANY WARRANTY; without even the implied warranty of
19	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20	* General Public License for more details.
21	*
22	* You should have received a copy of the GNU General Public License
23	* along with this program; if not, see <https://www.gnu.org/licenses>.
24	*
25	* SPDX-License-Identifier: GPL-3.0-only
26	*/
27
28	#ifndef MAIN_INCLUDED_GuestCtrlImplPrivate_h
29	#define MAIN_INCLUDED_GuestCtrlImplPrivate_h
30	#ifndef RT_WITHOUT_PRAGMA_ONCE
31	# pragma once
32	#endif
33
34	#include "ConsoleImpl.h"
35	#include "Global.h"
36
37	#include <iprt/asm.h>
38	#include <iprt/env.h>
39	#include <iprt/semaphore.h>
40	#include <iprt/cpp/utils.h>
41
42	#include <VBox/com/com.h>
43	#include <VBox/com/ErrorInfo.h>
44	#include <VBox/com/string.h>
45	#include <VBox/com/VirtualBox.h>
46	#include <VBox/err.h> /* VERR_GSTCTL_GUEST_ERROR */
47
48	#include <map>
49	#include <vector>
50
51	using namespace com;
52
53	#ifdef VBOX_WITH_GUEST_CONTROL
54	# include <VBox/GuestHost/GuestControl.h>
55	# include <VBox/HostServices/GuestControlSvc.h>
56	using namespace guestControl;
57	#endif
58
59	/** Vector holding a process' CPU affinity. */
60	typedef std::vector<LONG> ProcessAffinity;
61	/** Vector holding process startup arguments. */
62	typedef std::vector<Utf8Str> ProcessArguments;
63
64	class GuestToolboxStreamBlock;
65	class GuestSession;
66
67
68	/**
69	* Simple structure mantaining guest credentials.
70	*/
71	struct GuestCredentials
72	{
73	Utf8Str mUser;
74	Utf8Str mPassword;
75	Utf8Str mDomain;
76	};
77
78
79	/**
80	* Wrapper around the RTEnv API, unusable base class.
81	*
82	* @remarks Feel free to elevate this class to iprt/cpp/env.h as RTCEnv.
83	*/
84	class GuestEnvironmentBase
85	{
86	public:
87	/**
88	* Default constructor.
89	*
90	* The user must invoke one of the init methods before using the object.
91	*/
92	GuestEnvironmentBase(void)
93	: m_hEnv(NIL_RTENV)
94	, m_cRefs(1)
95	, m_fFlags(0)
96	{ }
97
98	/**
99	* Destructor.
100	*/
101	virtual ~GuestEnvironmentBase(void)
102	{
103	Assert(m_cRefs <= 1);
104	int vrc = RTEnvDestroy(m_hEnv); AssertRC(vrc);
105	m_hEnv = NIL_RTENV;
106	}
107
108	/**
109	* Retains a reference to this object.
110	* @returns New reference count.
111	* @remarks Sharing an object is currently only safe if no changes are made to
112	* it because RTENV does not yet implement any locking. For the only
113	* purpose we need this, implementing IGuestProcess::environment by
114	* using IGuestSession::environmentBase, that's fine as the session
115	* base environment is immutable.
116	*/
117	uint32_t retain(void)
118	{
119	uint32_t cRefs = ASMAtomicIncU32(&m_cRefs);
120	Assert(cRefs > 1); Assert(cRefs < _1M);
121	return cRefs;
122
123	}
124	/** Useful shortcut. */
125	uint32_t retainConst(void) const { return unconst(this)->retain(); }
126
127	/**
128	* Releases a reference to this object, deleting the object when reaching zero.
129	* @returns New reference count.
130	*/
131	uint32_t release(void)
132	{
133	uint32_t cRefs = ASMAtomicDecU32(&m_cRefs);
134	Assert(cRefs < _1M);
135	if (cRefs == 0)
136	delete this;
137	return cRefs;
138	}
139
140	/** Useful shortcut. */
141	uint32_t releaseConst(void) const { return unconst(this)->retain(); }
142
143	/**
144	* Checks if the environment has been successfully initialized or not.
145	*
146	* @returns @c true if initialized, @c false if not.
147	*/
148	bool isInitialized(void) const
149	{
150	return m_hEnv != NIL_RTENV;
151	}
152
153	/**
154	* Returns the variable count.
155	* @return Number of variables.
156	* @sa RTEnvCountEx
157	*/
158	uint32_t count(void) const
159	{
160	return RTEnvCountEx(m_hEnv);
161	}
162
163	/**
164	* Deletes the environment change record entirely.
165	*
166	* The count() method will return zero after this call.
167	*
168	* @sa RTEnvReset
169	*/
170	void reset(void)
171	{
172	int vrc = RTEnvReset(m_hEnv);
173	AssertRC(vrc);
174	}
175
176	/**
177	* Exports the environment change block as an array of putenv style strings.
178	*
179	*
180	* @returns VINF_SUCCESS or VERR_NO_MEMORY.
181	* @param pArray The output array.
182	*/
183	int queryPutEnvArray(std::vector<com::Utf8Str> *pArray) const
184	{
185	uint32_t cVars = RTEnvCountEx(m_hEnv);
186	try
187	{
188	pArray->resize(cVars);
189	for (uint32_t iVar = 0; iVar < cVars; iVar++)
190	{
191	const char *psz = RTEnvGetByIndexRawEx(m_hEnv, iVar);
192	AssertReturn(psz, VERR_INTERNAL_ERROR_3); /* someone is racing us! */
193	(*pArray)[iVar] = psz;
194	}
195	return VINF_SUCCESS;
196	}
197	catch (std::bad_alloc &)
198	{
199	return VERR_NO_MEMORY;
200	}
201	}
202
203	/**
204	* Applies an array of putenv style strings.
205	*
206	* @returns IPRT status code.
207	* @param rArray The array with the putenv style strings.
208	* @param pidxError Where to return the index causing trouble on
209	* failure. Optional.
210	* @sa RTEnvPutEx
211	*/
212	int applyPutEnvArray(const std::vector<com::Utf8Str> &rArray, size_t *pidxError = NULL)
213	{
214	size_t const cArray = rArray.size();
215	for (size_t i = 0; i < cArray; i++)
216	{
217	int vrc = RTEnvPutEx(m_hEnv, rArray[i].c_str());
218	if (RT_FAILURE(vrc))
219	{
220	if (pidxError)
221	*pidxError = i;
222	return vrc;
223	}
224	}
225	return VINF_SUCCESS;
226	}
227
228	/**
229	* Applies the changes from another environment to this.
230	*
231	* @returns IPRT status code.
232	* @param rChanges Reference to an environment which variables will be
233	* imported and, if it's a change record, schedule
234	* variable unsets will be applied.
235	* @sa RTEnvApplyChanges
236	*/
237	int applyChanges(const GuestEnvironmentBase &rChanges)
238	{
239	return RTEnvApplyChanges(m_hEnv, rChanges.m_hEnv);
240	}
241
242	/**
243	* See RTEnvQueryUtf8Block for details.
244	* @returns IPRT status code.
245	* @param ppszzBlock Where to return the block pointer.
246	* @param pcbBlock Where to optionally return the block size.
247	* @sa RTEnvQueryUtf8Block
248	*/
249	int queryUtf8Block(char *ppszzBlock, size_t pcbBlock)
250	{
251	return RTEnvQueryUtf8Block(m_hEnv, true /fSorted/, ppszzBlock, pcbBlock);
252	}
253
254	/**
255	* Frees what queryUtf8Block returned, NULL ignored.
256	* @sa RTEnvFreeUtf8Block
257	*/
258	static void freeUtf8Block(char *pszzBlock)
259	{
260	return RTEnvFreeUtf8Block(pszzBlock);
261	}
262
263	/**
264	* Applies a block on the format returned by queryUtf8Block.
265	*
266	* @returns IPRT status code.
267	* @param pszzBlock Pointer to the block.
268	* @param cbBlock The size of the block.
269	* @param fNoEqualMeansUnset Whether the lack of a '=' (equal) sign in a
270	* string means it should be unset (@c true), or if
271	* it means the variable should be defined with an
272	* empty value (@c false, the default).
273	* @todo move this to RTEnv!
274	*/
275	int copyUtf8Block(const char *pszzBlock, size_t cbBlock, bool fNoEqualMeansUnset = false)
276	{
277	int vrc = VINF_SUCCESS;
278	while (cbBlock > 0 && *pszzBlock != '\0')
279	{
280	const char pszEnd = (const char )memchr(pszzBlock, '\0', cbBlock);
281	if (!pszEnd)
282	return VERR_BUFFER_UNDERFLOW;
283	int vrc2;
284	if (fNoEqualMeansUnset \|\| strchr(pszzBlock, '='))
285	vrc2 = RTEnvPutEx(m_hEnv, pszzBlock);
286	else
287	vrc2 = RTEnvSetEx(m_hEnv, pszzBlock, "");
288	if (RT_FAILURE(vrc2) && RT_SUCCESS(vrc))
289	vrc = vrc2;
290
291	/* Advance. */
292	cbBlock -= pszEnd - pszzBlock;
293	if (cbBlock < 2)
294	return VERR_BUFFER_UNDERFLOW;
295	cbBlock--;
296	pszzBlock = pszEnd + 1;
297	}
298
299	/* The remainder must be zero padded. */
300	if (RT_SUCCESS(vrc))
301	{
302	if (ASMMemIsZero(pszzBlock, cbBlock))
303	return VINF_SUCCESS;
304	return VERR_TOO_MUCH_DATA;
305	}
306	return vrc;
307	}
308
309	/**
310	* Get an environment variable.
311	*
312	* @returns IPRT status code.
313	* @param rName The variable name.
314	* @param pValue Where to return the value.
315	* @sa RTEnvGetEx
316	*/
317	int getVariable(const com::Utf8Str &rName, com::Utf8Str *pValue) const
318	{
319	size_t cchNeeded;
320	int vrc = RTEnvGetEx(m_hEnv, rName.c_str(), NULL, 0, &cchNeeded);
321	if ( RT_SUCCESS(vrc)
322	\|\| vrc == VERR_BUFFER_OVERFLOW)
323	{
324	try
325	{
326	pValue->reserve(cchNeeded + 1);
327	vrc = RTEnvGetEx(m_hEnv, rName.c_str(), pValue->mutableRaw(), pValue->capacity(), NULL);
328	pValue->jolt();
329	}
330	catch (std::bad_alloc &)
331	{
332	vrc = VERR_NO_STR_MEMORY;
333	}
334	}
335	return vrc;
336	}
337
338	/**
339	* Checks if the given variable exists.
340	*
341	* @returns @c true if it exists, @c false if not or if it's an scheduled unset
342	* in a environment change record.
343	* @param rName The variable name.
344	* @sa RTEnvExistEx
345	*/
346	bool doesVariableExist(const com::Utf8Str &rName) const
347	{
348	return RTEnvExistEx(m_hEnv, rName.c_str());
349	}
350
351	/**
352	* Set an environment variable.
353	*
354	* @returns IPRT status code.
355	* @param rName The variable name.
356	* @param rValue The value of the variable.
357	* @sa RTEnvSetEx
358	*/
359	int setVariable(const com::Utf8Str &rName, const com::Utf8Str &rValue)
360	{
361	return RTEnvSetEx(m_hEnv, rName.c_str(), rValue.c_str());
362	}
363
364	/**
365	* Unset an environment variable.
366	*
367	* @returns IPRT status code.
368	* @param rName The variable name.
369	* @sa RTEnvUnsetEx
370	*/
371	int unsetVariable(const com::Utf8Str &rName)
372	{
373	return RTEnvUnsetEx(m_hEnv, rName.c_str());
374	}
375
376	protected:
377	/**
378	* Copy constructor.
379	* @throws HRESULT
380	*/
381	GuestEnvironmentBase(const GuestEnvironmentBase &rThat, bool fChangeRecord, uint32_t fFlags = 0)
382	: m_hEnv(NIL_RTENV)
383	, m_cRefs(1)
384	, m_fFlags(fFlags)
385	{
386	int vrc = cloneCommon(rThat, fChangeRecord);
387	if (RT_FAILURE(vrc))
388	throw Global::vboxStatusCodeToCOM(vrc);
389	}
390
391	/**
392	* Common clone/copy method with type conversion abilities.
393	*
394	* @returns IPRT status code.
395	* @param rThat The object to clone.
396	* @param fChangeRecord Whether the this instance is a change record (true)
397	* or normal (false) environment.
398	*/
399	int cloneCommon(const GuestEnvironmentBase &rThat, bool fChangeRecord)
400	{
401	int vrc = VINF_SUCCESS;
402	RTENV hNewEnv = NIL_RTENV;
403	if (rThat.m_hEnv != NIL_RTENV)
404	{
405	/*
406	* Clone it.
407	*/
408	if (RTEnvIsChangeRecord(rThat.m_hEnv) == fChangeRecord)
409	vrc = RTEnvClone(&hNewEnv, rThat.m_hEnv);
410	else
411	{
412	/* Need to type convert it. */
413	if (fChangeRecord)
414	vrc = RTEnvCreateChangeRecordEx(&hNewEnv, rThat.m_fFlags);
415	else
416	vrc = RTEnvCreateEx(&hNewEnv, rThat.m_fFlags);
417	if (RT_SUCCESS(vrc))
418	{
419	vrc = RTEnvApplyChanges(hNewEnv, rThat.m_hEnv);
420	if (RT_FAILURE(vrc))
421	RTEnvDestroy(hNewEnv);
422	}
423	}
424	}
425	else
426	{
427	/*
428	* Create an empty one so the object works smoothly.
429	* (Relevant for GuestProcessStartupInfo and internal commands.)
430	*/
431	if (fChangeRecord)
432	vrc = RTEnvCreateChangeRecordEx(&hNewEnv, rThat.m_fFlags);
433	else
434	vrc = RTEnvCreateEx(&hNewEnv, rThat.m_fFlags);
435	}
436	if (RT_SUCCESS(vrc))
437	{
438	RTEnvDestroy(m_hEnv);
439	m_hEnv = hNewEnv;
440	m_fFlags = rThat.m_fFlags;
441	}
442	return vrc;
443	}
444
445
446	/** The environment change record. */
447	RTENV m_hEnv;
448	/** Reference counter. */
449	uint32_t volatile m_cRefs;
450	/** RTENV_CREATE_F_XXX. */
451	uint32_t m_fFlags;
452	};
453
454	class GuestEnvironmentChanges;
455
456
457	/**
458	* Wrapper around the RTEnv API for a normal environment.
459	*/
460	class GuestEnvironment : public GuestEnvironmentBase
461	{
462	public:
463	/**
464	* Default constructor.
465	*
466	* The user must invoke one of the init methods before using the object.
467	*/
468	GuestEnvironment(void)
469	: GuestEnvironmentBase()
470	{ }
471
472	/**
473	* Copy operator.
474	* @param rThat The object to copy.
475	* @throws HRESULT
476	*/
477	GuestEnvironment(const GuestEnvironment &rThat)
478	: GuestEnvironmentBase(rThat, false /fChangeRecord/)
479	{ }
480
481	/**
482	* Copy operator.
483	* @param rThat The object to copy.
484	* @throws HRESULT
485	*/
486	GuestEnvironment(const GuestEnvironmentBase &rThat)
487	: GuestEnvironmentBase(rThat, false /fChangeRecord/)
488	{ }
489
490	/**
491	* Initialize this as a normal environment block.
492	* @returns IPRT status code.
493	* @param fFlags RTENV_CREATE_F_XXX
494	*/
495	int initNormal(uint32_t fFlags)
496	{
497	AssertReturn(m_hEnv == NIL_RTENV, VERR_WRONG_ORDER);
498	m_fFlags = fFlags;
499	return RTEnvCreateEx(&m_hEnv, fFlags);
500	}
501
502	/**
503	* Replaces this environemnt with that in @a rThat.
504	*
505	* @returns IPRT status code
506	* @param rThat The environment to copy. If it's a different type
507	* we'll convert the data to a normal environment block.
508	*/
509	int copy(const GuestEnvironmentBase &rThat)
510	{
511	return cloneCommon(rThat, false /fChangeRecord/);
512	}
513
514	/**
515	* @copydoc copy()
516	*/
517	GuestEnvironment &operator=(const GuestEnvironmentBase &rThat)
518	{
519	int vrc = copy(rThat);
520	if (RT_FAILURE(vrc))
521	throw Global::vboxStatusCodeToCOM(vrc);
522	return *this;
523	}
524
525	/** @copydoc copy() */
526	GuestEnvironment &operator=(const GuestEnvironment &rThat)
527	{ return operator=((const GuestEnvironmentBase &)rThat); }
528
529	/** @copydoc copy() */
530	GuestEnvironment &operator=(const GuestEnvironmentChanges &rThat)
531	{ return operator=((const GuestEnvironmentBase &)rThat); }
532
533	};
534
535
536	/**
537	* Wrapper around the RTEnv API for a environment change record.
538	*
539	* This class is used as a record of changes to be applied to a different
540	* environment block (in VBoxService before launching a new process).
541	*/
542	class GuestEnvironmentChanges : public GuestEnvironmentBase
543	{
544	public:
545	/**
546	* Default constructor.
547	*
548	* The user must invoke one of the init methods before using the object.
549	*/
550	GuestEnvironmentChanges(void)
551	: GuestEnvironmentBase()
552	{ }
553
554	/**
555	* Copy operator.
556	* @param rThat The object to copy.
557	* @throws HRESULT
558	*/
559	GuestEnvironmentChanges(const GuestEnvironmentChanges &rThat)
560	: GuestEnvironmentBase(rThat, true /fChangeRecord/)
561	{ }
562
563	/**
564	* Copy operator.
565	* @param rThat The object to copy.
566	* @throws HRESULT
567	*/
568	GuestEnvironmentChanges(const GuestEnvironmentBase &rThat)
569	: GuestEnvironmentBase(rThat, true /fChangeRecord/)
570	{ }
571
572	/**
573	* Initialize this as a environment change record.
574	* @returns IPRT status code.
575	* @param fFlags RTENV_CREATE_F_XXX
576	*/
577	int initChangeRecord(uint32_t fFlags)
578	{
579	AssertReturn(m_hEnv == NIL_RTENV, VERR_WRONG_ORDER);
580	m_fFlags = fFlags;
581	return RTEnvCreateChangeRecordEx(&m_hEnv, fFlags);
582	}
583
584	/**
585	* Replaces this environemnt with that in @a rThat.
586	*
587	* @returns IPRT status code
588	* @param rThat The environment to copy. If it's a different type
589	* we'll convert the data to a set of changes.
590	*/
591	int copy(const GuestEnvironmentBase &rThat)
592	{
593	return cloneCommon(rThat, true /fChangeRecord/);
594	}
595
596	/**
597	* @copydoc copy()
598	*/
599	GuestEnvironmentChanges &operator=(const GuestEnvironmentBase &rThat)
600	{
601	int vrc = copy(rThat);
602	if (RT_FAILURE(vrc))
603	throw Global::vboxStatusCodeToCOM(vrc);
604	return *this;
605	}
606
607	/** @copydoc copy() */
608	GuestEnvironmentChanges &operator=(const GuestEnvironmentChanges &rThat)
609	{ return operator=((const GuestEnvironmentBase &)rThat); }
610
611	/** @copydoc copy() */
612	GuestEnvironmentChanges &operator=(const GuestEnvironment &rThat)
613	{ return operator=((const GuestEnvironmentBase &)rThat); }
614	};
615
616	/**
617	* Class for keeping guest error information.
618	*/
619	class GuestErrorInfo
620	{
621	public:
622
623	/**
624	* Enumeration for specifying the guest error type.
625	*/
626	enum Type
627	{
628	/** Guest error is anonymous. Avoid this. */
629	Type_Anonymous = 0,
630	/** Guest error is from a guest session. */
631	Type_Session,
632	/** Guest error is from a guest process. */
633	Type_Process,
634	/** Guest error is from a guest file object. */
635	Type_File,
636	/** Guest error is from a guest directory object. */
637	Type_Directory,
638	/** Guest error is from a file system operation. */
639	Type_Fs,
640	#ifdef VBOX_WITH_GSTCTL_TOOLBOX_SUPPORT
641	/** Guest error is from a the built-in toolbox "vbox_ls" command. */
642	Type_ToolLs,
643	/** Guest error is from a the built-in toolbox "vbox_rm" command. */
644	Type_ToolRm,
645	/** Guest error is from a the built-in toolbox "vbox_mkdir" command. */
646	Type_ToolMkDir,
647	/** Guest error is from a the built-in toolbox "vbox_mktemp" command. */
648	Type_ToolMkTemp,
649	/** Guest error is from a the built-in toolbox "vbox_stat" command. */
650	Type_ToolStat,
651	#endif /* VBOX_WITH_GSTCTL_TOOLBOX_SUPPORT */
652	/** The usual 32-bit hack. */
653	Type_32BIT_HACK = 0x7fffffff
654	};
655
656	/**
657	* Initialization constructor.
658	*
659	* @param eType Error type to use.
660	* @param vrc VBox status code to use.
661	* @param pcszWhat Subject to use.
662	*/
663	GuestErrorInfo(GuestErrorInfo::Type eType, int vrc, const char *pcszWhat)
664	{
665	int vrc2 = setV(eType, vrc, pcszWhat);
666	if (RT_FAILURE(vrc2))
667	throw vrc2;
668	}
669
670	/**
671	* Returns the VBox status code for this error.
672	*
673	* @returns VBox status code.
674	*/
675	int getVrc(void) const { return mVrc; }
676
677	/**
678	* Returns the type of this error.
679	*
680	* @returns Error type.
681	*/
682	Type getType(void) const { return mType; }
683
684	/**
685	* Returns the subject of this error.
686	*
687	* @returns Subject as a string.
688	*/
689	Utf8Str getWhat(void) const { return mWhat; }
690
691	/**
692	* Sets the error information using a variable arguments list (va_list).
693	*
694	* @returns VBox status code.
695	* @param eType Error type to use.
696	* @param vrc VBox status code to use.
697	* @param pcszWhat Subject to use.
698	*/
699	int setV(GuestErrorInfo::Type eType, int vrc, const char *pcszWhat)
700	{
701	mType = eType;
702	mVrc = vrc;
703	mWhat = pcszWhat;
704
705	return VINF_SUCCESS;
706	}
707
708	protected:
709
710	/** Error type. */
711	Type mType;
712	/** VBox status (error) code. */
713	int mVrc;
714	/** Subject string related to this error. */
715	Utf8Str mWhat;
716	};
717
718	/**
719	* Structure for keeping all the relevant guest directory
720	* information around.
721	*/
722	struct GuestDirectoryOpenInfo
723	{
724	GuestDirectoryOpenInfo(void)
725	: menmFilter(GSTCTLDIRFILTER_NONE)
726	, mFlags(0) { }
727
728	/** The directory path. */
729	Utf8Str mPath;
730	/** The filter to use (wildcard style). */
731	Utf8Str mFilter;
732	/** The filter option to use. */
733	GSTCTLDIRFILTER menmFilter;
734	/** Opening flags (of type GSTCTLDIRFILTER_XXX). */
735	uint32_t mFlags;
736	};
737
738
739	/**
740	* Structure for keeping all the relevant guest file
741	* information around.
742	*/
743	struct GuestFileOpenInfo
744	{
745	GuestFileOpenInfo(void)
746	: mAccessMode((FileAccessMode_T)0)
747	, mOpenAction((FileOpenAction_T)0)
748	, mSharingMode((FileSharingMode_T)0)
749	, mCreationMode(0)
750	, mfOpenEx(0) { }
751
752	/**
753	* Validates a file open info.
754	*
755	* @returns \c true if valid, \c false if not.
756	*/
757	bool IsValid(void) const
758	{
759	if (mfOpenEx) /** @todo Open flags not implemented yet. */
760	return false;
761
762	switch (mOpenAction)
763	{
764	case FileOpenAction_OpenExisting:
765	break;
766	case FileOpenAction_OpenOrCreate:
767	break;
768	case FileOpenAction_CreateNew:
769	break;
770	case FileOpenAction_CreateOrReplace:
771	break;
772	case FileOpenAction_OpenExistingTruncated:
773	{
774	if ( mAccessMode == FileAccessMode_ReadOnly
775	\|\| mAccessMode == FileAccessMode_AppendOnly
776	\|\| mAccessMode == FileAccessMode_AppendRead)
777	return false;
778	break;
779	}
780	case FileOpenAction_AppendOrCreate: /* Deprecated, do not use. */
781	break;
782	default:
783	AssertFailedReturn(false);
784	break;
785	}
786
787	return true; /** @todo Do we need more checks here? */
788	}
789
790	/** The filename. */
791	Utf8Str mFilename;
792	/** The file access mode. */
793	FileAccessMode_T mAccessMode;
794	/** The file open action. */
795	FileOpenAction_T mOpenAction;
796	/** The file sharing mode. */
797	FileSharingMode_T mSharingMode;
798	/** Octal creation mode. */
799	uint32_t mCreationMode;
800	/** Extended open flags (currently none defined). */
801	uint32_t mfOpenEx;
802	};
803
804
805	/**
806	* Helper class for guest file system operations.
807	*/
808	class GuestFs
809	{
810	DECLARE_TRANSLATE_METHODS(GuestFs)
811
812	private:
813
814	/* Not directly instantiable. */
815	GuestFs(void) { }
816
817	public:
818
819	static Utf8Str guestErrorToString(const GuestErrorInfo &guestErrorInfo);
820	};
821
822
823	/**
824	* Structure representing information of a
825	* file system object.
826	*/
827	struct GuestFsObjData
828	{
829	GuestFsObjData(const Utf8Str &strName = "")
830	: mType(FsObjType_Unknown)
831	, mObjectSize(0)
832	, mAllocatedSize(0)
833	, mAccessTime(0)
834	, mBirthTime(0)
835	, mChangeTime(0)
836	, mModificationTime(0)
837	, mUID(0)
838	, mGID(0)
839	, mNodeID(0)
840	, mNodeIDDevice(0)
841	, mNumHardLinks(0)
842	, mDeviceNumber(0)
843	, mGenerationID(0)
844	, mUserFlags(0) { mName = strName; }
845
846	void Init(const Utf8Str &strName) { mName = strName; }
847
848	#ifdef VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS
849	int FromGuestDirEntryEx(PCGSTCTLDIRENTRYEX pDirEntryEx, const Utf8Str &strUser = "", const Utf8Str &strGroups = "");
850	int FromGuestFsObjInfo(PCGSTCTLFSOBJINFO pFsObjInfo, const Utf8Str &strUser = "", const Utf8Str &strGroups = "");
851	#endif
852
853	#ifdef VBOX_WITH_GSTCTL_TOOLBOX_SUPPORT
854	/** @name Helper functions to extract the data from a certin VBoxService tool's guest stream block.
855	* @{ */
856	int FromToolboxLs(const GuestToolboxStreamBlock &strmBlk, bool fLong);
857	int FromToolboxRm(const GuestToolboxStreamBlock &strmBlk);
858	int FromToolboxStat(const GuestToolboxStreamBlock &strmBlk);
859	int FromToolboxMkTemp(const GuestToolboxStreamBlock &strmBlk);
860	/** @} */
861	#endif
862
863	#ifdef VBOX_WITH_GSTCTL_TOOLBOX_SUPPORT
864	/** @name Static helper functions to work with time from stream block keys.
865	* @{ */
866	static PRTTIMESPEC TimeSpecFromKey(const GuestToolboxStreamBlock &strmBlk, const Utf8Str &strKey, PRTTIMESPEC pTimeSpec);
867	static int64_t UnixEpochNsFromKey(const GuestToolboxStreamBlock &strmBlk, const Utf8Str &strKey);
868	/** @} */
869	#endif
870
871	/** @name helper functions to work with IPRT stuff.
872	* @{ */
873	RTFMODE GetFileMode(void) const;
874	/** @} */
875
876	Utf8Str mName;
877	FsObjType_T mType;
878	Utf8Str mFileAttrs;
879	int64_t mObjectSize;
880	int64_t mAllocatedSize;
881	int64_t mAccessTime;
882	int64_t mBirthTime;
883	int64_t mChangeTime;
884	int64_t mModificationTime;
885	Utf8Str mUserName;
886	int32_t mUID;
887	int32_t mGID;
888	Utf8Str mGroupName;
889	Utf8Str mACL;
890	int64_t mNodeID;
891	uint32_t mNodeIDDevice;
892	uint32_t mNumHardLinks;
893	uint32_t mDeviceNumber;
894	uint32_t mGenerationID;
895	uint32_t mUserFlags;
896	};
897
898
899	/**
900	* Structure for keeping all the relevant guest session
901	* startup parameters around.
902	*/
903	class GuestSessionStartupInfo
904	{
905	public:
906
907	GuestSessionStartupInfo(void)
908	: mID(UINT32_MAX)
909	, mIsInternal(false /* Non-internal session */)
910	, mOpenTimeoutMS(30 * 1000 /* 30s opening timeout */)
911	, mOpenFlags(0 /* No opening flags set */) { }
912
913	/** The session's friendly name. Optional. */
914	Utf8Str mName;
915	/** The session's unique ID. Used to encode a context ID.
916	* UINT32_MAX if not initialized. */
917	uint32_t mID;
918	/** Flag indicating if this is an internal session
919	* or not. Internal session are not accessible by
920	* public API clients. */
921	bool mIsInternal;
922	/** Timeout (in ms) used for opening the session. */
923	uint32_t mOpenTimeoutMS;
924	/** Session opening flags. */
925	uint32_t mOpenFlags;
926	};
927
928
929	/**
930	* Structure for keeping all the relevant guest process
931	* startup parameters around.
932	*/
933	class GuestProcessStartupInfo
934	{
935	public:
936
937	GuestProcessStartupInfo(void)
938	: mFlags(ProcessCreateFlag_None)
939	, mTimeoutMS(UINT32_MAX /* No timeout by default */)
940	, mPriority(ProcessPriority_Default)
941	, mAffinity(0) { }
942
943	/** The process' friendly name. */
944	Utf8Str mName;
945	/** The executable. */
946	Utf8Str mExecutable;
947	/** The working directory. Optional, can be empty if not used. */
948	Utf8Str mCwd;
949	/** Arguments vector (starting with argument \#0). */
950	ProcessArguments mArguments;
951	/** The process environment change record. */
952	GuestEnvironmentChanges mEnvironmentChanges;
953	/** Process creation flags. */
954	uint32_t mFlags;
955	/** Timeout (in ms) the process is allowed to run.
956	* Specify UINT32_MAX if no timeout (unlimited run time) is given. */
957	ULONG mTimeoutMS;
958	/** Process priority. */
959	ProcessPriority_T mPriority;
960	/** Process affinity. At the moment we
961	* only support 64 VCPUs. API and
962	* guest can do more already! */
963	uint64_t mAffinity;
964	};
965
966
967	/**
968	* Class representing the "value" side of a "key=value" pair.
969	*/
970	class GuestToolboxStreamValue
971	{
972	public:
973
974	GuestToolboxStreamValue(void) { }
975	GuestToolboxStreamValue(const char *pszValue)
976	: mValue(pszValue) {}
977
978	GuestToolboxStreamValue(const GuestToolboxStreamValue& aThat)
979	: mValue(aThat.mValue) { }
980
981	/** Copy assignment operator. */
982	GuestToolboxStreamValue &operator=(GuestToolboxStreamValue const &a_rThat) RT_NOEXCEPT
983	{
984	mValue = a_rThat.mValue;
985
986	return *this;
987	}
988
989	Utf8Str mValue;
990	};
991
992	/** Map containing "key=value" pairs of a guest process stream. */
993	typedef std::pair< Utf8Str, GuestToolboxStreamValue > GuestCtrlStreamPair;
994	typedef std::map < Utf8Str, GuestToolboxStreamValue > GuestCtrlStreamPairMap;
995	typedef std::map < Utf8Str, GuestToolboxStreamValue >::iterator GuestCtrlStreamPairMapIter;
996	typedef std::map < Utf8Str, GuestToolboxStreamValue >::const_iterator GuestCtrlStreamPairMapIterConst;
997
998	/**
999	* Class representing a block of stream pairs (key=value). Each block in a raw guest
1000	* output stream is separated by "\0\0", each pair is separated by "\0". The overall
1001	* end of a guest stream is marked by "\0\0\0\0".
1002	*
1003	* Only used for the busybox-like toolbox commands within VBoxService.
1004	* Deprecated, do not use anymore.
1005	*/
1006	class GuestToolboxStreamBlock
1007	{
1008	public:
1009
1010	GuestToolboxStreamBlock(void);
1011
1012	virtual ~GuestToolboxStreamBlock(void);
1013
1014	public:
1015
1016	void Clear(void);
1017
1018	#ifdef DEBUG
1019	void DumpToLog(void) const;
1020	#endif
1021
1022	const char GetString(const char pszKey) const;
1023	size_t GetCount(void) const;
1024	int GetVrc(bool fSucceedIfNotFound = false) const;
1025	int GetInt64Ex(const char pszKey, int64_t piVal) const;
1026	int64_t GetInt64(const char *pszKey) const;
1027	int GetUInt32Ex(const char pszKey, uint32_t puVal) const;
1028	uint32_t GetUInt32(const char *pszKey, uint32_t uDefault = 0) const;
1029	int32_t GetInt32(const char *pszKey, int32_t iDefault = 0) const;
1030
1031	bool IsEmpty(void) { return mPairs.empty(); }
1032
1033	int SetValue(const char pszKey, const char pszValue);
1034
1035	protected:
1036
1037	GuestCtrlStreamPairMap mPairs;
1038	};
1039
1040	/** Vector containing multiple allocated stream pair objects. */
1041	typedef std::vector< GuestToolboxStreamBlock > GuestCtrlStreamObjects;
1042	typedef std::vector< GuestToolboxStreamBlock >::iterator GuestCtrlStreamObjectsIter;
1043	typedef std::vector< GuestToolboxStreamBlock >::const_iterator GuestCtrlStreamObjectsIterConst;
1044
1045	/**
1046	* Class for parsing machine-readable guest process output by VBoxService'
1047	* toolbox commands ("vbox_ls", "vbox_stat" etc), aka "guest stream".
1048	*
1049	* Deprecated, do not use anymore.
1050	*/
1051	class GuestToolboxStream
1052	{
1053
1054	public:
1055
1056	GuestToolboxStream();
1057
1058	virtual ~GuestToolboxStream();
1059
1060	public:
1061
1062	int AddData(const BYTE *pbData, size_t cbData);
1063
1064	void Destroy();
1065
1066	#ifdef DEBUG
1067	void Dump(const char *pszFile);
1068	#endif
1069
1070	size_t GetOffset() { return m_offBuffer; }
1071
1072	size_t GetSize() { return m_cbUsed; }
1073
1074	int ParseBlock(GuestToolboxStreamBlock &streamBlock);
1075
1076	protected:
1077
1078	/** Maximum allowed size the stream buffer can grow to.
1079	* Defaults to 32 MB. */
1080	size_t m_cbMax;
1081	/** Currently allocated size of internal stream buffer. */
1082	size_t m_cbAllocated;
1083	/** Currently used size at m_offBuffer. */
1084	size_t m_cbUsed;
1085	/** Current byte offset within the internal stream buffer. */
1086	size_t m_offBuffer;
1087	/** Internal stream buffer. */
1088	BYTE *m_pbBuffer;
1089	};
1090
1091	class Guest;
1092	class Progress;
1093
1094	class GuestWaitEventPayload
1095	{
1096
1097	public:
1098
1099	GuestWaitEventPayload(void)
1100	: uType(0)
1101	, cbData(0)
1102	, pvData(NULL)
1103	{ }
1104
1105	/**
1106	* Initialization constructor.
1107	*
1108	* @throws VBox status code (vrc).
1109	*
1110	* @param uTypePayload Payload type to set.
1111	* @param pvPayload Pointer to payload data to set (deep copy).
1112	* @param cbPayload Size (in bytes) of payload data to set.
1113	*/
1114	GuestWaitEventPayload(uint32_t uTypePayload, const void *pvPayload, uint32_t cbPayload)
1115	: uType(0)
1116	, cbData(0)
1117	, pvData(NULL)
1118	{
1119	int vrc = copyFrom(uTypePayload, pvPayload, cbPayload);
1120	if (RT_FAILURE(vrc))
1121	throw vrc;
1122	}
1123
1124	virtual ~GuestWaitEventPayload(void)
1125	{
1126	Clear();
1127	}
1128
1129	GuestWaitEventPayload& operator=(const GuestWaitEventPayload &that)
1130	{
1131	CopyFromDeep(that);
1132	return *this;
1133	}
1134
1135	public:
1136
1137	void Clear(void)
1138	{
1139	if (pvData)
1140	{
1141	Assert(cbData);
1142	RTMemFree(pvData);
1143	cbData = 0;
1144	pvData = NULL;
1145	}
1146	uType = 0;
1147	}
1148
1149	int CopyFromDeep(const GuestWaitEventPayload &payload)
1150	{
1151	return copyFrom(payload.uType, payload.pvData, payload.cbData);
1152	}
1153
1154	const void* Raw(void) const { return pvData; }
1155
1156	size_t Size(void) const { return cbData; }
1157
1158	uint32_t Type(void) const { return uType; }
1159
1160	void* MutableRaw(void) { return pvData; }
1161
1162	Utf8Str ToString(void)
1163	{
1164	const char pszStr = (const char )pvData;
1165	size_t cbStr = cbData;
1166
1167	if (RT_FAILURE(RTStrValidateEncodingEx(pszStr, cbStr,
1168	RTSTR_VALIDATE_ENCODING_ZERO_TERMINATED \| RTSTR_VALIDATE_ENCODING_EXACT_LENGTH)))
1169	{
1170	AssertFailed();
1171	return "";
1172	}
1173
1174	return Utf8Str(pszStr, cbStr);
1175	}
1176
1177	protected:
1178
1179	int copyFrom(uint32_t uTypePayload, const void *pvPayload, uint32_t cbPayload)
1180	{
1181	if (cbPayload > _64K) /* Paranoia. */
1182	return VERR_TOO_MUCH_DATA;
1183
1184	Clear();
1185
1186	int vrc = VINF_SUCCESS;
1187	if (cbPayload)
1188	{
1189	pvData = RTMemAlloc(cbPayload);
1190	if (pvData)
1191	{
1192	uType = uTypePayload;
1193
1194	memcpy(pvData, pvPayload, cbPayload);
1195	cbData = cbPayload;
1196	}
1197	else
1198	vrc = VERR_NO_MEMORY;
1199	}
1200	else
1201	{
1202	uType = uTypePayload;
1203
1204	pvData = NULL;
1205	cbData = 0;
1206	}
1207
1208	return vrc;
1209	}
1210
1211	protected:
1212
1213	/** Type of payload. */
1214	uint32_t uType;
1215	/** Size (in bytes) of payload. */
1216	uint32_t cbData;
1217	/** Pointer to actual payload data. */
1218	void *pvData;
1219	};
1220
1221	class GuestWaitEventBase
1222	{
1223
1224	protected:
1225
1226	GuestWaitEventBase(void);
1227	virtual ~GuestWaitEventBase(void);
1228
1229	public:
1230
1231	uint32_t ContextID(void) const { return mCID; };
1232	int GuestResult(void) const { return mGuestRc; }
1233	bool HasGuestError(void) const { return mVrc == VERR_GSTCTL_GUEST_ERROR; }
1234	int Result(void) const { return mVrc; }
1235	GuestWaitEventPayload &Payload(void) { return mPayload; }
1236	int SignalInternal(int vrc, int vrcGuest, const GuestWaitEventPayload *pPayload);
1237	int Wait(RTMSINTERVAL uTimeoutMS);
1238
1239	protected:
1240
1241	int Init(uint32_t uCID);
1242
1243	protected:
1244
1245	/** Shutdown indicator. */
1246	bool mfAborted;
1247	/** Associated context ID (CID). */
1248	uint32_t mCID;
1249	/** The event semaphore for triggering the actual event. */
1250	RTSEMEVENT mEventSem;
1251	/** The event's overall result.
1252	* If set to VERR_GSTCTL_GUEST_ERROR, mGuestRc will contain the actual
1253	* error code from the guest side. */
1254	int mVrc;
1255	/** The event'S overall result from the guest side.
1256	* If used, mVrc must be set to VERR_GSTCTL_GUEST_ERROR. */
1257	int mGuestRc;
1258	/** The event's payload data. Optional. */
1259	GuestWaitEventPayload mPayload;
1260	};
1261
1262	/** List of public guest event types. */
1263	typedef std::list < VBoxEventType_T > GuestEventTypes;
1264
1265	class GuestWaitEvent : public GuestWaitEventBase
1266	{
1267
1268	public:
1269
1270	GuestWaitEvent(void);
1271	virtual ~GuestWaitEvent(void);
1272
1273	public:
1274
1275	int Init(uint32_t uCID);
1276	int Init(uint32_t uCID, const GuestEventTypes &lstEvents);
1277	int Cancel(void);
1278	const ComPtr<IEvent> Event(void) const { return mEvent; }
1279	int SignalExternal(IEvent *pEvent);
1280	const GuestEventTypes &Types(void) const { return mEventTypes; }
1281	size_t TypeCount(void) const { return mEventTypes.size(); }
1282
1283	protected:
1284
1285	/** List of public event types this event should
1286	* be signalled on. Optional. */
1287	GuestEventTypes mEventTypes;
1288	/** Pointer to the actual public event, if any. */
1289	ComPtr<IEvent> mEvent;
1290	};
1291	/** Map of pointers to guest events. The primary key
1292	* contains the context ID. */
1293	typedef std::map < uint32_t, GuestWaitEvent* > GuestWaitEvents;
1294	/** Map of wait events per public guest event. Nice for
1295	* faster lookups when signalling a whole event group. */
1296	typedef std::map < VBoxEventType_T, GuestWaitEvents > GuestEventGroup;
1297
1298	class GuestBase
1299	{
1300
1301	public:
1302
1303	GuestBase(void);
1304	virtual ~GuestBase(void);
1305
1306	public:
1307
1308	/** Signals a wait event using a public guest event; also used for
1309	* for external event listeners. */
1310	int signalWaitEvent(VBoxEventType_T aType, IEvent *aEvent);
1311	/** Signals a wait event using a guest vrc. */
1312	int signalWaitEventInternal(PVBOXGUESTCTRLHOSTCBCTX pCbCtx, int vrcGuest, const GuestWaitEventPayload *pPayload);
1313	/** Signals a wait event without letting public guest events know,
1314	* extended director's cut version. */
1315	int signalWaitEventInternalEx(PVBOXGUESTCTRLHOSTCBCTX pCbCtx, int vrc, int vrcGuest, const GuestWaitEventPayload *pPayload);
1316
1317	public:
1318
1319	int baseInit(void);
1320	void baseUninit(void);
1321	int cancelWaitEvents(void);
1322	int dispatchGeneric(PVBOXGUESTCTRLHOSTCBCTX pCtxCb, PVBOXGUESTCTRLHOSTCALLBACK pSvcCb);
1323	int generateContextID(uint32_t uSessionID, uint32_t uObjectID, uint32_t *puContextID);
1324	int registerWaitEvent(uint32_t uSessionID, uint32_t uObjectID, GuestWaitEvent **ppEvent);
1325	int registerWaitEventEx(uint32_t uSessionID, uint32_t uObjectID, const GuestEventTypes &lstEvents, GuestWaitEvent **ppEvent);
1326	int unregisterWaitEvent(GuestWaitEvent *pEvent);
1327	int waitForEvent(GuestWaitEvent pEvent, uint32_t uTimeoutMS, VBoxEventType_T pType, IEvent **ppEvent);
1328
1329	public:
1330
1331	static FsObjType_T fileModeToFsObjType(RTFMODE fMode);
1332	static const char *fsObjTypeToStr(FsObjType_T enmType);
1333	static const char *pathStyleToStr(PathStyle_T enmPathStyle);
1334	static Utf8Str getErrorAsString(const Utf8Str &strAction, const GuestErrorInfo& guestErrorInfo);
1335	static Utf8Str getErrorAsString(const GuestErrorInfo &guestErrorInfo);
1336
1337	protected:
1338
1339	/** Pointer to the console object. Needed
1340	* for HGCM (VMMDev) communication. */
1341	Console *mConsole;
1342	/** The next context ID counter component for this object. */
1343	uint32_t mNextContextID;
1344	/** Local listener for handling the waiting events
1345	* internally. */
1346	ComPtr<IEventListener> mLocalListener;
1347	/** Critical section for wait events access. */
1348	RTCRITSECT mWaitEventCritSect;
1349	/** Map of registered wait events per event group. */
1350	GuestEventGroup mWaitEventGroups;
1351	/** Map of registered wait events. */
1352	GuestWaitEvents mWaitEvents;
1353	};
1354
1355	/**
1356	* Virtual class (interface) for guest objects (processes, files, ...) --
1357	* contains all per-object callback management.
1358	*/
1359	class GuestObject : public GuestBase
1360	{
1361	friend class GuestSession;
1362
1363	public:
1364
1365	GuestObject(void);
1366	virtual ~GuestObject(void);
1367
1368	public:
1369
1370	ULONG getObjectID(void) { return mObjectID; }
1371
1372	protected:
1373
1374	/**
1375	* Called by IGuestSession when the session status has been changed.
1376	*
1377	* @returns VBox status code.
1378	* @param enmSessionStatus New session status.
1379	*/
1380	virtual int i_onSessionStatusChange(GuestSessionStatus_T enmSessionStatus) = 0;
1381
1382	/**
1383	* Called by IGuestSession right before this object gets
1384	* unregistered (removed) from the public object list.
1385	*/
1386	virtual int i_onUnregister(void) = 0;
1387
1388	/** Callback dispatcher -- must be implemented by the actual object. */
1389	virtual int i_callbackDispatcher(PVBOXGUESTCTRLHOSTCBCTX pCbCtx, PVBOXGUESTCTRLHOSTCALLBACK pSvcCb) = 0;
1390
1391	protected:
1392
1393	int bindToSession(Console pConsole, GuestSession pSession, uint32_t uObjectID);
1394	int registerWaitEvent(const GuestEventTypes &lstEvents, GuestWaitEvent **ppEvent);
1395	int sendMessage(uint32_t uFunction, uint32_t cParms, PVBOXHGCMSVCPARM paParms);
1396
1397	protected:
1398
1399	/** @name Common parameters for all derived objects. They have their own
1400	* mData structure to keep their specific data around.
1401	* @{ */
1402	/** Pointer to parent session. Per definition
1403	* this objects always lives shorter than the
1404	* parent.
1405	* @todo r=bird: When wanting to use mSession in the
1406	* IGuestProcess::getEnvironment() implementation I wanted to access
1407	* GuestSession::mData::mpBaseEnvironment. Seeing the comment in
1408	* GuestProcess::terminate() saying:
1409	* "Now only API clients still can hold references to it."
1410	* and recalling seeing similar things in VirtualBox.xidl or some such place,
1411	* I'm wondering how this "per definition" behavior is enforced. Is there any
1412	* GuestProcess:uninit() call or similar magic that invalidates objects that
1413	* GuestSession loses track of in place like GuestProcess::terminate() that I've
1414	* failed to spot?
1415	*
1416	* Please enlighten me.
1417	*/
1418	GuestSession *mSession;
1419	/** The object ID -- must be unique for each guest
1420	* object and is encoded into the context ID. Must
1421	* be set manually when initializing the object.
1422	*
1423	* For guest processes this is the internal PID,
1424	* for guest files this is the internal file ID. */
1425	uint32_t mObjectID;
1426	/** @} */
1427	};
1428
1429	/** Returns the path separator based on \a a_enmPathStyle as a C-string. */
1430	#define PATH_STYLE_SEP_STR(a_enmPathStyle) (a_enmPathStyle == PathStyle_DOS ? "\\" : "/")
1431	#if defined(RT_OS_WINDOWS) \|\| defined(RT_OS_OS2)
1432	# define PATH_STYLE_NATIVE PathStyle_DOS
1433	#else
1434	# define PATH_STYLE_NATIVE PathStyle_UNIX
1435	#endif
1436
1437	/**
1438	* Class for handling guest / host path functions.
1439	*/
1440	class GuestPath
1441	{
1442	private:
1443
1444	/**
1445	* Default constructor.
1446	*
1447	* Not directly instantiable (yet).
1448	*/
1449	GuestPath(void) { }
1450
1451	public:
1452
1453	/** @name Static helper functions.
1454	* @{ */
1455	static int BuildDestinationPath(const Utf8Str &strSrcPath, PathStyle_T enmSrcPathStyle, Utf8Str &strDstPath, PathStyle_T enmDstPathStyle);
1456	static int Translate(Utf8Str &strPath, PathStyle_T enmSrcPathStyle, PathStyle_T enmDstPathStyle, bool fForce = false);
1457	/** @} */
1458	};
1459
1460
1461	/*********************************************************************************************************************************
1462	* Callback data structures. *
1463	* *
1464	* These structures make up the actual low level HGCM callback data sent from *
1465	* the guest back to the host. *
1466	********************************************************************************************************************************/
1467
1468	/**
1469	* The guest control callback data header. Must come first
1470	* on each callback structure defined below this struct.
1471	*/
1472	typedef struct CALLBACKDATA_HEADER
1473	{
1474	/** Context ID to identify callback data. This is
1475	* and must be the very first parameter in this
1476	* structure to still be backwards compatible. */
1477	uint32_t uContextID;
1478	} CALLBACKDATA_HEADER;
1479	/** Pointer to a CALLBACKDATA_HEADER struct. */
1480	typedef CALLBACKDATA_HEADER *PCALLBACKDATA_HEADER;
1481
1482	/**
1483	* Host service callback data when a HGCM client disconnected.
1484	*/
1485	typedef struct CALLBACKDATA_CLIENT_DISCONNECTED
1486	{
1487	/** Callback data header. */
1488	CALLBACKDATA_HEADER hdr;
1489	} CALLBACKDATA_CLIENT_DISCONNECTED;
1490	/** Pointer to a CALLBACKDATA_CLIENT_DISCONNECTED struct. */
1491	typedef CALLBACKDATA_CLIENT_DISCONNECTED *PCALLBACKDATA_CLIENT_DISCONNECTED;
1492
1493	/**
1494	* Host service callback data for a generic guest reply.
1495	*/
1496	typedef struct CALLBACKDATA_MSG_REPLY
1497	{
1498	/** Callback data header. */
1499	CALLBACKDATA_HEADER hdr;
1500	/** Notification type. */
1501	uint32_t uType;
1502	/** Notification result. Note: int vs. uint32! */
1503	uint32_t rc;
1504	/** Pointer to optional payload. */
1505	void *pvPayload;
1506	/** Payload size (in bytes). */
1507	uint32_t cbPayload;
1508	} CALLBACKDATA_MSG_REPLY;
1509	/** Pointer to a CALLBACKDATA_MSG_REPLY struct. */
1510	typedef CALLBACKDATA_MSG_REPLY *PCALLBACKDATA_MSG_REPLY;
1511
1512	/**
1513	* Host service callback data for guest session notifications.
1514	*/
1515	typedef struct CALLBACKDATA_SESSION_NOTIFY
1516	{
1517	/** Callback data header. */
1518	CALLBACKDATA_HEADER hdr;
1519	/** Notification type. */
1520	uint32_t uType;
1521	/** Notification result. Note: int vs. uint32! */
1522	uint32_t uResult;
1523	} CALLBACKDATA_SESSION_NOTIFY;
1524	/** Pointer to a CALLBACKDATA_SESSION_NOTIFY struct. */
1525	typedef CALLBACKDATA_SESSION_NOTIFY *PCALLBACKDATA_SESSION_NOTIFY;
1526
1527	/**
1528	* Host service callback data for guest process status notifications.
1529	*/
1530	typedef struct CALLBACKDATA_PROC_STATUS
1531	{
1532	/** Callback data header. */
1533	CALLBACKDATA_HEADER hdr;
1534	/** The process ID (PID). */
1535	uint32_t uPID;
1536	/** The process status. */
1537	uint32_t uStatus;
1538	/** Optional flags, varies, based on u32Status. */
1539	uint32_t uFlags;
1540	/** Optional data buffer (not used atm). */
1541	void *pvData;
1542	/** Size of optional data buffer (not used atm). */
1543	uint32_t cbData;
1544	} CALLBACKDATA_PROC_STATUS;
1545	/** Pointer to a CALLBACKDATA_PROC_OUTPUT struct. */
1546	typedef CALLBACKDATA_PROC_STATUS* PCALLBACKDATA_PROC_STATUS;
1547
1548	/**
1549	* Host service callback data for guest process output notifications.
1550	*/
1551	typedef struct CALLBACKDATA_PROC_OUTPUT
1552	{
1553	/** Callback data header. */
1554	CALLBACKDATA_HEADER hdr;
1555	/** The process ID (PID). */
1556	uint32_t uPID;
1557	/** The handle ID (stdout/stderr). */
1558	uint32_t uHandle;
1559	/** Optional flags (not used atm). */
1560	uint32_t uFlags;
1561	/** Optional data buffer. */
1562	void *pvData;
1563	/** Size (in bytes) of optional data buffer. */
1564	uint32_t cbData;
1565	} CALLBACKDATA_PROC_OUTPUT;
1566	/** Pointer to a CALLBACKDATA_PROC_OUTPUT struct. */
1567	typedef CALLBACKDATA_PROC_OUTPUT *PCALLBACKDATA_PROC_OUTPUT;
1568
1569	/**
1570	* Host service callback data guest process input notifications.
1571	*/
1572	typedef struct CALLBACKDATA_PROC_INPUT
1573	{
1574	/** Callback data header. */
1575	CALLBACKDATA_HEADER hdr;
1576	/** The process ID (PID). */
1577	uint32_t uPID;
1578	/** Current input status. */
1579	uint32_t uStatus;
1580	/** Optional flags. */
1581	uint32_t uFlags;
1582	/** Size (in bytes) of processed input data. */
1583	uint32_t uProcessed;
1584	} CALLBACKDATA_PROC_INPUT;
1585	/** Pointer to a CALLBACKDATA_PROC_INPUT struct. */
1586	typedef CALLBACKDATA_PROC_INPUT *PCALLBACKDATA_PROC_INPUT;
1587
1588	/**
1589	* General guest file notification callback.
1590	*/
1591	typedef struct CALLBACKDATA_FILE_NOTIFY
1592	{
1593	/** Callback data header. */
1594	CALLBACKDATA_HEADER hdr;
1595	/** Notification type. */
1596	uint32_t uType;
1597	/** IPRT result of overall operation. */
1598	uint32_t rc;
1599	union
1600	{
1601	struct
1602	{
1603	/** Guest file handle. */
1604	uint32_t uHandle;
1605	} open;
1606	/** Note: Close does not have any additional data (yet). */
1607	struct
1608	{
1609	/** How much data (in bytes) have been read. */
1610	uint32_t cbData;
1611	/** Actual data read (if any). */
1612	void *pvData;
1613	} read;
1614	struct
1615	{
1616	/** How much data (in bytes) have been successfully written. */
1617	uint32_t cbWritten;
1618	} write;
1619	struct
1620	{
1621	/** New file offset after successful seek. */
1622	uint64_t uOffActual;
1623	} seek;
1624	struct
1625	{
1626	/** New file offset after successful tell. */
1627	uint64_t uOffActual;
1628	} tell;
1629	struct
1630	{
1631	/** The new file siz.e */
1632	uint64_t cbSize;
1633	} SetSize;
1634	} u;
1635	} CALLBACKDATA_FILE_NOTIFY;
1636	/** Pointer to a CALLBACKDATA_FILE_NOTIFY, struct. */
1637	typedef CALLBACKDATA_FILE_NOTIFY *PCALLBACKDATA_FILE_NOTIFY;
1638
1639	/**
1640	* Callback data for a single GSTCTLDIRENTRYEX entry.
1641	*/
1642	typedef struct CALLBACKDATA_DIR_ENTRY
1643	{
1644	/** Pointer to directory entry information. */
1645	PGSTCTLDIRENTRYEX pDirEntryEx;
1646	/** Size (in bytes) of directory entry information. */
1647	uint32_t cbDirEntryEx;
1648	/** Resolved user name.
1649	* This is the object owner for UNIX-y Oses. */
1650	char *pszUser;
1651	/** Size (in bytes) of \a pszUser. */
1652	uint32_t cbUser;
1653	/** Resolved user group(s). */
1654	char *pszGroups;
1655	/** Size (in bytes) of \a pszGroups. */
1656	uint32_t cbGroups;
1657	} CALLBACKDATA_DIR_ENTRY;
1658	/** Pointer to a CALLBACKDATA_DIR_ENTRY struct. */
1659	typedef CALLBACKDATA_DIR_ENTRY *PCALLBACKDATA_DIR_ENTRY;
1660
1661	/**
1662	* Callback data for guest directory operations.
1663	*/
1664	typedef struct CALLBACKDATA_DIR_NOTIFY
1665	{
1666	/** Callback data header. */
1667	CALLBACKDATA_HEADER hdr;
1668	/** Notification type. */
1669	uint32_t uType;
1670	/** IPRT result of overall operation. */
1671	uint32_t rc;
1672	union
1673	{
1674	struct
1675	{
1676	/** Pointer to directory information. */
1677	PGSTCTLFSOBJINFO pObjInfo;
1678	} info;
1679	struct
1680	{
1681	/** Guest directory handle. */
1682	uint32_t uHandle;
1683	} open;
1684	/** Note: Close does not have any additional data (yet). */
1685	struct
1686	{
1687	/** Single entry read. */
1688	CALLBACKDATA_DIR_ENTRY Entry;
1689	} read;
1690	struct
1691	{
1692	/** Number of entries in \a paEntries. */
1693	uint32_t cEntries;
1694	/** Array of entries read. */
1695	CALLBACKDATA_DIR_ENTRY **paEntries;
1696	} list;
1697	} u;
1698	} CALLBACKDATA_DIR_NOTIFY;
1699	/** Pointer to a CALLBACKDATA_DIR_NOTIFY struct. */
1700	typedef CALLBACKDATA_DIR_NOTIFY *PCALLBACKDATA_DIR_NOTIFY;
1701
1702	/**
1703	* Callback data for guest file system operations.
1704	*/
1705	typedef struct CALLBACKDATA_FS_NOTIFY
1706	{
1707	/** Callback data header. */
1708	CALLBACKDATA_HEADER hdr;
1709	/** Notification type (of type GUEST_FS_NOTIFYTYPE_XXX). */
1710	uint32_t uType;
1711	/** IPRT result of overall operation. */
1712	uint32_t rc;
1713	union
1714	{
1715	/** Holds information for GUEST_FS_NOTIFYTYPE_CREATE_TEMP. */
1716	struct
1717	{
1718	/** Path of created temporary file / directory. */
1719	char *pszPath;
1720	/** Size (in bytes) of \a pszPath. */
1721	uint32_t cbPath;
1722	} CreateTemp;
1723	/** Holds information for GUEST_FS_NOTIFYTYPE_QUERY_OBJ_INFO. */
1724	struct
1725	{
1726	GSTCTLFSOBJINFO objInfo;
1727	/** Resolved user name. */
1728	char *pszUser;
1729	/** Size (in bytes) of \a pszUser. */
1730	uint32_t cbUser;
1731	/** Resolved user group(s). */
1732	char *pszGroups;
1733	/** Size (in bytes) of \a pszGroups. */
1734	uint32_t cbGroups;
1735	} QueryObjInfo;
1736	/** Holds information for GUEST_FS_NOTIFYTYPE_QUERY_INFO. */
1737	struct
1738	{
1739	/** The actual filesystem information. */
1740	GSTCTLFSINFO fsInfo;
1741	} QueryInfo;
1742	} u;
1743	} CALLBACKDATA_FS_NOTIFY;
1744	/** Pointer to a CALLBACKDATA_FS_NOTIFY struct. */
1745	typedef CALLBACKDATA_FS_NOTIFY *PCALLBACKDATA_FS_NOTIFY;
1746	#endif /* !MAIN_INCLUDED_GuestCtrlImplPrivate_h */
1747

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

source: vbox/trunk/src/VBox/Main/include/GuestCtrlImplPrivate.h@ 99320

Download in other formats: