VirtualBox

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

Last change on this file since 86506 was 84857, checked in by vboxsync, 4 years ago

Guest Control/Main: Added another GuestBase::getErrorAsString() convenience function. bugref:9320
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 39.9 KB
Line 
1/* $Id: GuestCtrlImplPrivate.h 84857 2020-06-17 07:46:06Z vboxsync $ */
2/** @file
3 * Internal helpers/structures for guest control functionality.
4 */
5
6/*
7 * Copyright (C) 2011-2020 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
18#ifndef MAIN_INCLUDED_GuestCtrlImplPrivate_h
19#define MAIN_INCLUDED_GuestCtrlImplPrivate_h
20#ifndef RT_WITHOUT_PRAGMA_ONCE
21# pragma once
22#endif
23
24#include "ConsoleImpl.h"
25#include "Global.h"
26
27#include <iprt/asm.h>
28#include <iprt/env.h>
29#include <iprt/semaphore.h>
30#include <iprt/cpp/utils.h>
31
32#include <VBox/com/com.h>
33#include <VBox/com/ErrorInfo.h>
34#include <VBox/com/string.h>
35#include <VBox/com/VirtualBox.h>
36#include <VBox/err.h> /* VERR_GSTCTL_GUEST_ERROR */
37
38#include <map>
39#include <vector>
40
41using namespace com;
42
43#ifdef VBOX_WITH_GUEST_CONTROL
44# include <VBox/GuestHost/GuestControl.h>
45# include <VBox/HostServices/GuestControlSvc.h>
46using namespace guestControl;
47#endif
48
49/** Vector holding a process' CPU affinity. */
50typedef std::vector <LONG> ProcessAffinity;
51/** Vector holding process startup arguments. */
52typedef std::vector <Utf8Str> ProcessArguments;
53
54class GuestProcessStreamBlock;
55class GuestSession;
56
57
58/**
59 * Simple structure mantaining guest credentials.
60 */
61struct GuestCredentials
62{
63 Utf8Str mUser;
64 Utf8Str mPassword;
65 Utf8Str mDomain;
66};
67
68
69/**
70 * Wrapper around the RTEnv API, unusable base class.
71 *
72 * @remarks Feel free to elevate this class to iprt/cpp/env.h as RTCEnv.
73 */
74class GuestEnvironmentBase
75{
76public:
77 /**
78 * Default constructor.
79 *
80 * The user must invoke one of the init methods before using the object.
81 */
82 GuestEnvironmentBase(void)
83 : m_hEnv(NIL_RTENV)
84 , m_cRefs(1)
85 , m_fFlags(0)
86 { }
87
88 /**
89 * Destructor.
90 */
91 virtual ~GuestEnvironmentBase(void)
92 {
93 Assert(m_cRefs <= 1);
94 int rc = RTEnvDestroy(m_hEnv); AssertRC(rc);
95 m_hEnv = NIL_RTENV;
96 }
97
98 /**
99 * Retains a reference to this object.
100 * @returns New reference count.
101 * @remarks Sharing an object is currently only safe if no changes are made to
102 * it because RTENV does not yet implement any locking. For the only
103 * purpose we need this, implementing IGuestProcess::environment by
104 * using IGuestSession::environmentBase, that's fine as the session
105 * base environment is immutable.
106 */
107 uint32_t retain(void)
108 {
109 uint32_t cRefs = ASMAtomicIncU32(&m_cRefs);
110 Assert(cRefs > 1); Assert(cRefs < _1M);
111 return cRefs;
112
113 }
114 /** Useful shortcut. */
115 uint32_t retainConst(void) const { return unconst(this)->retain(); }
116
117 /**
118 * Releases a reference to this object, deleting the object when reaching zero.
119 * @returns New reference count.
120 */
121 uint32_t release(void)
122 {
123 uint32_t cRefs = ASMAtomicDecU32(&m_cRefs);
124 Assert(cRefs < _1M);
125 if (cRefs == 0)
126 delete this;
127 return cRefs;
128 }
129
130 /** Useful shortcut. */
131 uint32_t releaseConst(void) const { return unconst(this)->retain(); }
132
133 /**
134 * Checks if the environment has been successfully initialized or not.
135 *
136 * @returns @c true if initialized, @c false if not.
137 */
138 bool isInitialized(void) const
139 {
140 return m_hEnv != NIL_RTENV;
141 }
142
143 /**
144 * Returns the variable count.
145 * @return Number of variables.
146 * @sa RTEnvCountEx
147 */
148 uint32_t count(void) const
149 {
150 return RTEnvCountEx(m_hEnv);
151 }
152
153 /**
154 * Deletes the environment change record entirely.
155 *
156 * The count() method will return zero after this call.
157 *
158 * @sa RTEnvReset
159 */
160 void reset(void)
161 {
162 int rc = RTEnvReset(m_hEnv);
163 AssertRC(rc);
164 }
165
166 /**
167 * Exports the environment change block as an array of putenv style strings.
168 *
169 *
170 * @returns VINF_SUCCESS or VERR_NO_MEMORY.
171 * @param pArray The output array.
172 */
173 int queryPutEnvArray(std::vector<com::Utf8Str> *pArray) const
174 {
175 uint32_t cVars = RTEnvCountEx(m_hEnv);
176 try
177 {
178 pArray->resize(cVars);
179 for (uint32_t iVar = 0; iVar < cVars; iVar++)
180 {
181 const char *psz = RTEnvGetByIndexRawEx(m_hEnv, iVar);
182 AssertReturn(psz, VERR_INTERNAL_ERROR_3); /* someone is racing us! */
183 (*pArray)[iVar] = psz;
184 }
185 return VINF_SUCCESS;
186 }
187 catch (std::bad_alloc &)
188 {
189 return VERR_NO_MEMORY;
190 }
191 }
192
193 /**
194 * Applies an array of putenv style strings.
195 *
196 * @returns IPRT status code.
197 * @param rArray The array with the putenv style strings.
198 * @param pidxError Where to return the index causing trouble on
199 * failure. Optional.
200 * @sa RTEnvPutEx
201 */
202 int applyPutEnvArray(const std::vector<com::Utf8Str> &rArray, size_t *pidxError = NULL)
203 {
204 size_t const cArray = rArray.size();
205 for (size_t i = 0; i < cArray; i++)
206 {
207 int rc = RTEnvPutEx(m_hEnv, rArray[i].c_str());
208 if (RT_FAILURE(rc))
209 {
210 if (pidxError)
211 *pidxError = i;
212 return rc;
213 }
214 }
215 return VINF_SUCCESS;
216 }
217
218 /**
219 * Applies the changes from another environment to this.
220 *
221 * @returns IPRT status code.
222 * @param rChanges Reference to an environment which variables will be
223 * imported and, if it's a change record, schedule
224 * variable unsets will be applied.
225 * @sa RTEnvApplyChanges
226 */
227 int applyChanges(const GuestEnvironmentBase &rChanges)
228 {
229 return RTEnvApplyChanges(m_hEnv, rChanges.m_hEnv);
230 }
231
232 /**
233 * See RTEnvQueryUtf8Block for details.
234 * @returns IPRT status code.
235 * @param ppszzBlock Where to return the block pointer.
236 * @param pcbBlock Where to optionally return the block size.
237 * @sa RTEnvQueryUtf8Block
238 */
239 int queryUtf8Block(char **ppszzBlock, size_t *pcbBlock)
240 {
241 return RTEnvQueryUtf8Block(m_hEnv, true /*fSorted*/, ppszzBlock, pcbBlock);
242 }
243
244 /**
245 * Frees what queryUtf8Block returned, NULL ignored.
246 * @sa RTEnvFreeUtf8Block
247 */
248 static void freeUtf8Block(char *pszzBlock)
249 {
250 return RTEnvFreeUtf8Block(pszzBlock);
251 }
252
253 /**
254 * Applies a block on the format returned by queryUtf8Block.
255 *
256 * @returns IPRT status code.
257 * @param pszzBlock Pointer to the block.
258 * @param cbBlock The size of the block.
259 * @param fNoEqualMeansUnset Whether the lack of a '=' (equal) sign in a
260 * string means it should be unset (@c true), or if
261 * it means the variable should be defined with an
262 * empty value (@c false, the default).
263 * @todo move this to RTEnv!
264 */
265 int copyUtf8Block(const char *pszzBlock, size_t cbBlock, bool fNoEqualMeansUnset = false)
266 {
267 int rc = VINF_SUCCESS;
268 while (cbBlock > 0 && *pszzBlock != '\0')
269 {
270 const char *pszEnd = (const char *)memchr(pszzBlock, '\0', cbBlock);
271 if (!pszEnd)
272 return VERR_BUFFER_UNDERFLOW;
273 int rc2;
274 if (fNoEqualMeansUnset || strchr(pszzBlock, '='))
275 rc2 = RTEnvPutEx(m_hEnv, pszzBlock);
276 else
277 rc2 = RTEnvSetEx(m_hEnv, pszzBlock, "");
278 if (RT_FAILURE(rc2) && RT_SUCCESS(rc))
279 rc = rc2;
280
281 /* Advance. */
282 cbBlock -= pszEnd - pszzBlock;
283 if (cbBlock < 2)
284 return VERR_BUFFER_UNDERFLOW;
285 cbBlock--;
286 pszzBlock = pszEnd + 1;
287 }
288
289 /* The remainder must be zero padded. */
290 if (RT_SUCCESS(rc))
291 {
292 if (ASMMemIsZero(pszzBlock, cbBlock))
293 return VINF_SUCCESS;
294 return VERR_TOO_MUCH_DATA;
295 }
296 return rc;
297 }
298
299 /**
300 * Get an environment variable.
301 *
302 * @returns IPRT status code.
303 * @param rName The variable name.
304 * @param pValue Where to return the value.
305 * @sa RTEnvGetEx
306 */
307 int getVariable(const com::Utf8Str &rName, com::Utf8Str *pValue) const
308 {
309 size_t cchNeeded;
310 int rc = RTEnvGetEx(m_hEnv, rName.c_str(), NULL, 0, &cchNeeded);
311 if ( RT_SUCCESS(rc)
312 || rc == VERR_BUFFER_OVERFLOW)
313 {
314 try
315 {
316 pValue->reserve(cchNeeded + 1);
317 rc = RTEnvGetEx(m_hEnv, rName.c_str(), pValue->mutableRaw(), pValue->capacity(), NULL);
318 pValue->jolt();
319 }
320 catch (std::bad_alloc &)
321 {
322 rc = VERR_NO_STR_MEMORY;
323 }
324 }
325 return rc;
326 }
327
328 /**
329 * Checks if the given variable exists.
330 *
331 * @returns @c true if it exists, @c false if not or if it's an scheduled unset
332 * in a environment change record.
333 * @param rName The variable name.
334 * @sa RTEnvExistEx
335 */
336 bool doesVariableExist(const com::Utf8Str &rName) const
337 {
338 return RTEnvExistEx(m_hEnv, rName.c_str());
339 }
340
341 /**
342 * Set an environment variable.
343 *
344 * @returns IPRT status code.
345 * @param rName The variable name.
346 * @param rValue The value of the variable.
347 * @sa RTEnvSetEx
348 */
349 int setVariable(const com::Utf8Str &rName, const com::Utf8Str &rValue)
350 {
351 return RTEnvSetEx(m_hEnv, rName.c_str(), rValue.c_str());
352 }
353
354 /**
355 * Unset an environment variable.
356 *
357 * @returns IPRT status code.
358 * @param rName The variable name.
359 * @sa RTEnvUnsetEx
360 */
361 int unsetVariable(const com::Utf8Str &rName)
362 {
363 return RTEnvUnsetEx(m_hEnv, rName.c_str());
364 }
365
366protected:
367 /**
368 * Copy constructor.
369 * @throws HRESULT
370 */
371 GuestEnvironmentBase(const GuestEnvironmentBase &rThat, bool fChangeRecord, uint32_t fFlags = 0)
372 : m_hEnv(NIL_RTENV)
373 , m_cRefs(1)
374 , m_fFlags(fFlags)
375 {
376 int rc = cloneCommon(rThat, fChangeRecord);
377 if (RT_FAILURE(rc))
378 throw (Global::vboxStatusCodeToCOM(rc));
379 }
380
381 /**
382 * Common clone/copy method with type conversion abilities.
383 *
384 * @returns IPRT status code.
385 * @param rThat The object to clone.
386 * @param fChangeRecord Whether the this instance is a change record (true)
387 * or normal (false) environment.
388 */
389 int cloneCommon(const GuestEnvironmentBase &rThat, bool fChangeRecord)
390 {
391 int rc = VINF_SUCCESS;
392 RTENV hNewEnv = NIL_RTENV;
393 if (rThat.m_hEnv != NIL_RTENV)
394 {
395 /*
396 * Clone it.
397 */
398 if (RTEnvIsChangeRecord(rThat.m_hEnv) == fChangeRecord)
399 rc = RTEnvClone(&hNewEnv, rThat.m_hEnv);
400 else
401 {
402 /* Need to type convert it. */
403 if (fChangeRecord)
404 rc = RTEnvCreateChangeRecordEx(&hNewEnv, rThat.m_fFlags);
405 else
406 rc = RTEnvCreateEx(&hNewEnv, rThat.m_fFlags);
407 if (RT_SUCCESS(rc))
408 {
409 rc = RTEnvApplyChanges(hNewEnv, rThat.m_hEnv);
410 if (RT_FAILURE(rc))
411 RTEnvDestroy(hNewEnv);
412 }
413 }
414 }
415 else
416 {
417 /*
418 * Create an empty one so the object works smoothly.
419 * (Relevant for GuestProcessStartupInfo and internal commands.)
420 */
421 if (fChangeRecord)
422 rc = RTEnvCreateChangeRecordEx(&hNewEnv, rThat.m_fFlags);
423 else
424 rc = RTEnvCreateEx(&hNewEnv, rThat.m_fFlags);
425 }
426 if (RT_SUCCESS(rc))
427 {
428 RTEnvDestroy(m_hEnv);
429 m_hEnv = hNewEnv;
430 m_fFlags = rThat.m_fFlags;
431 }
432 return rc;
433 }
434
435
436 /** The environment change record. */
437 RTENV m_hEnv;
438 /** Reference counter. */
439 uint32_t volatile m_cRefs;
440 /** RTENV_CREATE_F_XXX. */
441 uint32_t m_fFlags;
442};
443
444class GuestEnvironmentChanges;
445
446
447/**
448 * Wrapper around the RTEnv API for a normal environment.
449 */
450class GuestEnvironment : public GuestEnvironmentBase
451{
452public:
453 /**
454 * Default constructor.
455 *
456 * The user must invoke one of the init methods before using the object.
457 */
458 GuestEnvironment(void)
459 : GuestEnvironmentBase()
460 { }
461
462 /**
463 * Copy operator.
464 * @param rThat The object to copy.
465 * @throws HRESULT
466 */
467 GuestEnvironment(const GuestEnvironment &rThat)
468 : GuestEnvironmentBase(rThat, false /*fChangeRecord*/)
469 { }
470
471 /**
472 * Copy operator.
473 * @param rThat The object to copy.
474 * @throws HRESULT
475 */
476 GuestEnvironment(const GuestEnvironmentBase &rThat)
477 : GuestEnvironmentBase(rThat, false /*fChangeRecord*/)
478 { }
479
480 /**
481 * Initialize this as a normal environment block.
482 * @returns IPRT status code.
483 * @param fFlags RTENV_CREATE_F_XXX
484 */
485 int initNormal(uint32_t fFlags)
486 {
487 AssertReturn(m_hEnv == NIL_RTENV, VERR_WRONG_ORDER);
488 m_fFlags = fFlags;
489 return RTEnvCreateEx(&m_hEnv, fFlags);
490 }
491
492 /**
493 * Replaces this environemnt with that in @a rThat.
494 *
495 * @returns IPRT status code
496 * @param rThat The environment to copy. If it's a different type
497 * we'll convert the data to a normal environment block.
498 */
499 int copy(const GuestEnvironmentBase &rThat)
500 {
501 return cloneCommon(rThat, false /*fChangeRecord*/);
502 }
503
504 /**
505 * @copydoc copy()
506 */
507 GuestEnvironment &operator=(const GuestEnvironmentBase &rThat)
508 {
509 int rc = copy(rThat);
510 if (RT_FAILURE(rc))
511 throw (Global::vboxStatusCodeToCOM(rc));
512 return *this;
513 }
514
515 /** @copydoc copy() */
516 GuestEnvironment &operator=(const GuestEnvironment &rThat)
517 { return operator=((const GuestEnvironmentBase &)rThat); }
518
519 /** @copydoc copy() */
520 GuestEnvironment &operator=(const GuestEnvironmentChanges &rThat)
521 { return operator=((const GuestEnvironmentBase &)rThat); }
522
523};
524
525
526/**
527 * Wrapper around the RTEnv API for a environment change record.
528 *
529 * This class is used as a record of changes to be applied to a different
530 * environment block (in VBoxService before launching a new process).
531 */
532class GuestEnvironmentChanges : public GuestEnvironmentBase
533{
534public:
535 /**
536 * Default constructor.
537 *
538 * The user must invoke one of the init methods before using the object.
539 */
540 GuestEnvironmentChanges(void)
541 : GuestEnvironmentBase()
542 { }
543
544 /**
545 * Copy operator.
546 * @param rThat The object to copy.
547 * @throws HRESULT
548 */
549 GuestEnvironmentChanges(const GuestEnvironmentChanges &rThat)
550 : GuestEnvironmentBase(rThat, true /*fChangeRecord*/)
551 { }
552
553 /**
554 * Copy operator.
555 * @param rThat The object to copy.
556 * @throws HRESULT
557 */
558 GuestEnvironmentChanges(const GuestEnvironmentBase &rThat)
559 : GuestEnvironmentBase(rThat, true /*fChangeRecord*/)
560 { }
561
562 /**
563 * Initialize this as a environment change record.
564 * @returns IPRT status code.
565 * @param fFlags RTENV_CREATE_F_XXX
566 */
567 int initChangeRecord(uint32_t fFlags)
568 {
569 AssertReturn(m_hEnv == NIL_RTENV, VERR_WRONG_ORDER);
570 m_fFlags = fFlags;
571 return RTEnvCreateChangeRecordEx(&m_hEnv, fFlags);
572 }
573
574 /**
575 * Replaces this environemnt with that in @a rThat.
576 *
577 * @returns IPRT status code
578 * @param rThat The environment to copy. If it's a different type
579 * we'll convert the data to a set of changes.
580 */
581 int copy(const GuestEnvironmentBase &rThat)
582 {
583 return cloneCommon(rThat, true /*fChangeRecord*/);
584 }
585
586 /**
587 * @copydoc copy()
588 */
589 GuestEnvironmentChanges &operator=(const GuestEnvironmentBase &rThat)
590 {
591 int rc = copy(rThat);
592 if (RT_FAILURE(rc))
593 throw (Global::vboxStatusCodeToCOM(rc));
594 return *this;
595 }
596
597 /** @copydoc copy() */
598 GuestEnvironmentChanges &operator=(const GuestEnvironmentChanges &rThat)
599 { return operator=((const GuestEnvironmentBase &)rThat); }
600
601 /** @copydoc copy() */
602 GuestEnvironmentChanges &operator=(const GuestEnvironment &rThat)
603 { return operator=((const GuestEnvironmentBase &)rThat); }
604};
605
606/**
607 * Class for keeping guest error information.
608 */
609class GuestErrorInfo
610{
611public:
612
613 /**
614 * Enumeration for specifying the guest error type.
615 */
616 enum Type
617 {
618 /** Guest error is anonymous. Avoid this. */
619 Type_Anonymous = 0,
620 /** Guest error is from a guest session. */
621 Type_Session,
622 /** Guest error is from a guest process. */
623 Type_Process,
624 /** Guest error is from a guest file object. */
625 Type_File,
626 /** Guest error is from a guest directory object. */
627 Type_Directory,
628 /** Guest error is from a the built-in toolbox "vbox_cat" command. */
629 Type_ToolCat,
630 /** Guest error is from a the built-in toolbox "vbox_ls" command. */
631 Type_ToolLs,
632 /** Guest error is from a the built-in toolbox "vbox_rm" command. */
633 Type_ToolRm,
634 /** Guest error is from a the built-in toolbox "vbox_mkdir" command. */
635 Type_ToolMkDir,
636 /** Guest error is from a the built-in toolbox "vbox_mktemp" command. */
637 Type_ToolMkTemp,
638 /** Guest error is from a the built-in toolbox "vbox_stat" command. */
639 Type_ToolStat,
640 /** The usual 32-bit hack. */
641 Type_32BIT_HACK = 0x7fffffff
642 };
643
644 /**
645 * Initialization constructor.
646 *
647 * @param eType Error type to use.
648 * @param rc IPRT-style rc to use.
649 * @param pcszWhat Subject to use.
650 */
651 GuestErrorInfo(GuestErrorInfo::Type eType, int rc, const char *pcszWhat)
652 {
653 int rc2 = setV(eType, rc, pcszWhat);
654 if (RT_FAILURE(rc2))
655 throw rc2;
656 }
657
658 /**
659 * Returns the (IPRT-style) rc of this error.
660 *
661 * @returns VBox status code.
662 */
663 int getRc(void) const { return mRc; }
664
665 /**
666 * Returns the type of this error.
667 *
668 * @returns Error type.
669 */
670 Type getType(void) const { return mType; }
671
672 /**
673 * Returns the subject of this error.
674 *
675 * @returns Subject as a string.
676 */
677 Utf8Str getWhat(void) const { return mWhat; }
678
679 /**
680 * Sets the error information using a variable arguments list (va_list).
681 *
682 * @returns VBox status code.
683 * @param eType Error type to use.
684 * @param rc IPRT-style rc to use.
685 * @param pcszWhat Subject to use.
686 */
687 int setV(GuestErrorInfo::Type eType, int rc, const char *pcszWhat)
688 {
689 mType = eType;
690 mRc = rc;
691 mWhat = pcszWhat;
692
693 return VINF_SUCCESS;
694 }
695
696protected:
697
698 /** Error type. */
699 Type mType;
700 /** IPRT-style error code. */
701 int mRc;
702 /** Subject string related to this error. */
703 Utf8Str mWhat;
704};
705
706/**
707 * Structure for keeping all the relevant guest directory
708 * information around.
709 */
710struct GuestDirectoryOpenInfo
711{
712 GuestDirectoryOpenInfo(void)
713 : mFlags(0) { }
714
715 /** The directory path. */
716 Utf8Str mPath;
717 /** Then open filter. */
718 Utf8Str mFilter;
719 /** Opening flags. */
720 uint32_t mFlags;
721};
722
723
724/**
725 * Structure for keeping all the relevant guest file
726 * information around.
727 */
728struct GuestFileOpenInfo
729{
730 GuestFileOpenInfo(void)
731 : mAccessMode((FileAccessMode_T)0)
732 , mOpenAction((FileOpenAction_T)0)
733 , mSharingMode((FileSharingMode_T)0)
734 , mCreationMode(0)
735 , mfOpenEx(0) { }
736
737 /**
738 * Validates a file open info.
739 *
740 * @returns \c true if valid, \c false if not.
741 */
742 bool IsValid(void) const
743 {
744 if (mfOpenEx) /** @todo Open flags not implemented yet. */
745 return false;
746
747 switch (mOpenAction)
748 {
749 case FileOpenAction_OpenExisting:
750 break;
751 case FileOpenAction_OpenOrCreate:
752 break;
753 case FileOpenAction_CreateNew:
754 break;
755 case FileOpenAction_CreateOrReplace:
756 break;
757 case FileOpenAction_OpenExistingTruncated:
758 {
759 if ( mAccessMode == FileAccessMode_ReadOnly
760 || mAccessMode == FileAccessMode_AppendOnly
761 || mAccessMode == FileAccessMode_AppendRead)
762 return false;
763 break;
764 }
765 case FileOpenAction_AppendOrCreate: /* Deprecated, do not use. */
766 break;
767 default:
768 AssertFailedReturn(false);
769 break;
770 }
771
772 return true; /** @todo Do we need more checks here? */
773 }
774
775 /** The filename. */
776 Utf8Str mFilename;
777 /** The file access mode. */
778 FileAccessMode_T mAccessMode;
779 /** The file open action. */
780 FileOpenAction_T mOpenAction;
781 /** The file sharing mode. */
782 FileSharingMode_T mSharingMode;
783 /** Octal creation mode. */
784 uint32_t mCreationMode;
785 /** Extended open flags (currently none defined). */
786 uint32_t mfOpenEx;
787};
788
789
790/**
791 * Structure representing information of a
792 * file system object.
793 */
794struct GuestFsObjData
795{
796 GuestFsObjData(void)
797 : mType(FsObjType_Unknown)
798 , mObjectSize(0)
799 , mAllocatedSize(0)
800 , mAccessTime(0)
801 , mBirthTime(0)
802 , mChangeTime(0)
803 , mModificationTime(0)
804 , mUID(0)
805 , mGID(0)
806 , mNodeID(0)
807 , mNodeIDDevice(0)
808 , mNumHardLinks(0)
809 , mDeviceNumber(0)
810 , mGenerationID(0)
811 , mUserFlags(0) { }
812
813 /** @name Helper functions to extract the data from a certin VBoxService tool's guest stream block.
814 * @{ */
815 int FromLs(const GuestProcessStreamBlock &strmBlk, bool fLong);
816 int FromStat(const GuestProcessStreamBlock &strmBlk);
817 int FromMkTemp(const GuestProcessStreamBlock &strmBlk);
818 /** @} */
819
820 /** @name Static helper functions to work with time from stream block keys.
821 * @{ */
822 static PRTTIMESPEC TimeSpecFromKey(const GuestProcessStreamBlock &strmBlk, const Utf8Str &strKey, PRTTIMESPEC pTimeSpec);
823 static int64_t UnixEpochNsFromKey(const GuestProcessStreamBlock &strmBlk, const Utf8Str &strKey);
824 /** @} */
825
826 /** @name helper functions to work with IPRT stuff.
827 * @{ */
828 RTFMODE GetFileMode(void) const;
829 /** @} */
830
831 Utf8Str mName;
832 FsObjType_T mType;
833 Utf8Str mFileAttrs;
834 int64_t mObjectSize;
835 int64_t mAllocatedSize;
836 int64_t mAccessTime;
837 int64_t mBirthTime;
838 int64_t mChangeTime;
839 int64_t mModificationTime;
840 Utf8Str mUserName;
841 int32_t mUID;
842 int32_t mGID;
843 Utf8Str mGroupName;
844 Utf8Str mACL;
845 int64_t mNodeID;
846 uint32_t mNodeIDDevice;
847 uint32_t mNumHardLinks;
848 uint32_t mDeviceNumber;
849 uint32_t mGenerationID;
850 uint32_t mUserFlags;
851};
852
853
854/**
855 * Structure for keeping all the relevant guest session
856 * startup parameters around.
857 */
858class GuestSessionStartupInfo
859{
860public:
861
862 GuestSessionStartupInfo(void)
863 : mID(UINT32_MAX)
864 , mIsInternal(false /* Non-internal session */)
865 , mOpenTimeoutMS(30 * 1000 /* 30s opening timeout */)
866 , mOpenFlags(0 /* No opening flags set */) { }
867
868 /** The session's friendly name. Optional. */
869 Utf8Str mName;
870 /** The session's unique ID. Used to encode a context ID.
871 * UINT32_MAX if not initialized. */
872 uint32_t mID;
873 /** Flag indicating if this is an internal session
874 * or not. Internal session are not accessible by
875 * public API clients. */
876 bool mIsInternal;
877 /** Timeout (in ms) used for opening the session. */
878 uint32_t mOpenTimeoutMS;
879 /** Session opening flags. */
880 uint32_t mOpenFlags;
881};
882
883
884/**
885 * Structure for keeping all the relevant guest process
886 * startup parameters around.
887 */
888class GuestProcessStartupInfo
889{
890public:
891
892 GuestProcessStartupInfo(void)
893 : mFlags(ProcessCreateFlag_None)
894 , mTimeoutMS(UINT32_MAX /* No timeout by default */)
895 , mPriority(ProcessPriority_Default)
896 , mAffinity(0) { }
897
898 /** The process' friendly name. */
899 Utf8Str mName;
900 /** The executable. */
901 Utf8Str mExecutable;
902 /** Arguments vector (starting with argument \#0). */
903 ProcessArguments mArguments;
904 /** The process environment change record. */
905 GuestEnvironmentChanges mEnvironmentChanges;
906 /** Process creation flags. */
907 uint32_t mFlags;
908 /** Timeout (in ms) the process is allowed to run.
909 * Specify UINT32_MAX if no timeout (unlimited run time) is given. */
910 ULONG mTimeoutMS;
911 /** Process priority. */
912 ProcessPriority_T mPriority;
913 /** Process affinity. At the moment we
914 * only support 64 VCPUs. API and
915 * guest can do more already! */
916 uint64_t mAffinity;
917};
918
919
920/**
921 * Class representing the "value" side of a "key=value" pair.
922 */
923class GuestProcessStreamValue
924{
925public:
926
927 GuestProcessStreamValue(void) { }
928 GuestProcessStreamValue(const char *pszValue)
929 : mValue(pszValue) {}
930
931 GuestProcessStreamValue(const GuestProcessStreamValue& aThat)
932 : mValue(aThat.mValue) { }
933
934 /** Copy assignment operator. */
935 GuestProcessStreamValue &operator=(GuestProcessStreamValue const &a_rThat) RT_NOEXCEPT
936 {
937 mValue = a_rThat.mValue;
938
939 return *this;
940 }
941
942 Utf8Str mValue;
943};
944
945/** Map containing "key=value" pairs of a guest process stream. */
946typedef std::pair< Utf8Str, GuestProcessStreamValue > GuestCtrlStreamPair;
947typedef std::map < Utf8Str, GuestProcessStreamValue > GuestCtrlStreamPairMap;
948typedef std::map < Utf8Str, GuestProcessStreamValue >::iterator GuestCtrlStreamPairMapIter;
949typedef std::map < Utf8Str, GuestProcessStreamValue >::const_iterator GuestCtrlStreamPairMapIterConst;
950
951/**
952 * Class representing a block of stream pairs (key=value). Each block in a raw guest
953 * output stream is separated by "\0\0", each pair is separated by "\0". The overall
954 * end of a guest stream is marked by "\0\0\0\0".
955 */
956class GuestProcessStreamBlock
957{
958public:
959
960 GuestProcessStreamBlock(void);
961
962 virtual ~GuestProcessStreamBlock(void);
963
964public:
965
966 void Clear(void);
967
968#ifdef DEBUG
969 void DumpToLog(void) const;
970#endif
971
972 const char *GetString(const char *pszKey) const;
973 size_t GetCount(void) const;
974 int GetRc(void) const;
975 int GetInt64Ex(const char *pszKey, int64_t *piVal) const;
976 int64_t GetInt64(const char *pszKey) const;
977 int GetUInt32Ex(const char *pszKey, uint32_t *puVal) const;
978 uint32_t GetUInt32(const char *pszKey, uint32_t uDefault = 0) const;
979 int32_t GetInt32(const char *pszKey, int32_t iDefault = 0) const;
980
981 bool IsEmpty(void) { return mPairs.empty(); }
982
983 int SetValue(const char *pszKey, const char *pszValue);
984
985protected:
986
987 GuestCtrlStreamPairMap mPairs;
988};
989
990/** Vector containing multiple allocated stream pair objects. */
991typedef std::vector< GuestProcessStreamBlock > GuestCtrlStreamObjects;
992typedef std::vector< GuestProcessStreamBlock >::iterator GuestCtrlStreamObjectsIter;
993typedef std::vector< GuestProcessStreamBlock >::const_iterator GuestCtrlStreamObjectsIterConst;
994
995/**
996 * Class for parsing machine-readable guest process output by VBoxService'
997 * toolbox commands ("vbox_ls", "vbox_stat" etc), aka "guest stream".
998 */
999class GuestProcessStream
1000{
1001
1002public:
1003
1004 GuestProcessStream();
1005
1006 virtual ~GuestProcessStream();
1007
1008public:
1009
1010 int AddData(const BYTE *pbData, size_t cbData);
1011
1012 void Destroy();
1013
1014#ifdef DEBUG
1015 void Dump(const char *pszFile);
1016#endif
1017
1018 size_t GetOffset() { return m_offBuffer; }
1019
1020 size_t GetSize() { return m_cbUsed; }
1021
1022 int ParseBlock(GuestProcessStreamBlock &streamBlock);
1023
1024protected:
1025
1026 /** Maximum allowed size the stream buffer can grow to.
1027 * Defaults to 32 MB. */
1028 size_t m_cbMax;
1029 /** Currently allocated size of internal stream buffer. */
1030 size_t m_cbAllocated;
1031 /** Currently used size at m_offBuffer. */
1032 size_t m_cbUsed;
1033 /** Current byte offset within the internal stream buffer. */
1034 size_t m_offBuffer;
1035 /** Internal stream buffer. */
1036 BYTE *m_pbBuffer;
1037};
1038
1039class Guest;
1040class Progress;
1041
1042class GuestWaitEventPayload
1043{
1044
1045public:
1046
1047 GuestWaitEventPayload(void)
1048 : uType(0),
1049 cbData(0),
1050 pvData(NULL) { }
1051
1052 /**
1053 * Initialization constructor. Will throw() VBox status code (rc).
1054 *
1055 * @param uTypePayload Payload type to set.
1056 * @param pvPayload Pointer to payload data to set (deep copy).
1057 * @param cbPayload Size (in bytes) of payload data to set.
1058 */
1059 GuestWaitEventPayload(uint32_t uTypePayload,
1060 const void *pvPayload, uint32_t cbPayload)
1061 : uType(0),
1062 cbData(0),
1063 pvData(NULL)
1064 {
1065 int rc = copyFrom(uTypePayload, pvPayload, cbPayload);
1066 if (RT_FAILURE(rc))
1067 throw rc;
1068 }
1069
1070 virtual ~GuestWaitEventPayload(void)
1071 {
1072 Clear();
1073 }
1074
1075 GuestWaitEventPayload& operator=(const GuestWaitEventPayload &that)
1076 {
1077 CopyFromDeep(that);
1078 return *this;
1079 }
1080
1081public:
1082
1083 void Clear(void)
1084 {
1085 if (pvData)
1086 {
1087 Assert(cbData);
1088 RTMemFree(pvData);
1089 cbData = 0;
1090 pvData = NULL;
1091 }
1092 uType = 0;
1093 }
1094
1095 int CopyFromDeep(const GuestWaitEventPayload &payload)
1096 {
1097 return copyFrom(payload.uType, payload.pvData, payload.cbData);
1098 }
1099
1100 const void* Raw(void) const { return pvData; }
1101
1102 size_t Size(void) const { return cbData; }
1103
1104 uint32_t Type(void) const { return uType; }
1105
1106 void* MutableRaw(void) { return pvData; }
1107
1108 Utf8Str ToString(void)
1109 {
1110 const char *pszStr = (const char *)pvData;
1111 size_t cbStr = cbData;
1112
1113 if (RT_FAILURE(RTStrValidateEncodingEx(pszStr, cbStr,
1114 RTSTR_VALIDATE_ENCODING_ZERO_TERMINATED | RTSTR_VALIDATE_ENCODING_EXACT_LENGTH)))
1115 {
1116 AssertFailed();
1117 return "";
1118 }
1119
1120 return Utf8Str(pszStr, cbStr);
1121 }
1122
1123protected:
1124
1125 int copyFrom(uint32_t uTypePayload, const void *pvPayload, uint32_t cbPayload)
1126 {
1127 if (cbPayload > _64K) /* Paranoia. */
1128 return VERR_TOO_MUCH_DATA;
1129
1130 Clear();
1131
1132 int rc = VINF_SUCCESS;
1133
1134 if (cbPayload)
1135 {
1136 pvData = RTMemAlloc(cbPayload);
1137 if (pvData)
1138 {
1139 uType = uTypePayload;
1140
1141 memcpy(pvData, pvPayload, cbPayload);
1142 cbData = cbPayload;
1143 }
1144 else
1145 rc = VERR_NO_MEMORY;
1146 }
1147 else
1148 {
1149 uType = uTypePayload;
1150
1151 pvData = NULL;
1152 cbData = 0;
1153 }
1154
1155 return rc;
1156 }
1157
1158protected:
1159
1160 /** Type of payload. */
1161 uint32_t uType;
1162 /** Size (in bytes) of payload. */
1163 uint32_t cbData;
1164 /** Pointer to actual payload data. */
1165 void *pvData;
1166};
1167
1168class GuestWaitEventBase
1169{
1170
1171protected:
1172
1173 GuestWaitEventBase(void);
1174 virtual ~GuestWaitEventBase(void);
1175
1176public:
1177
1178 uint32_t ContextID(void) { return mCID; };
1179 int GuestResult(void) { return mGuestRc; }
1180 int Result(void) { return mRc; }
1181 GuestWaitEventPayload & Payload(void) { return mPayload; }
1182 int SignalInternal(int rc, int guestRc, const GuestWaitEventPayload *pPayload);
1183 int Wait(RTMSINTERVAL uTimeoutMS);
1184
1185protected:
1186
1187 int Init(uint32_t uCID);
1188
1189protected:
1190
1191 /* Shutdown indicator. */
1192 bool mfAborted;
1193 /* Associated context ID (CID). */
1194 uint32_t mCID;
1195 /** The event semaphore for triggering
1196 * the actual event. */
1197 RTSEMEVENT mEventSem;
1198 /** The event's overall result. If
1199 * set to VERR_GSTCTL_GUEST_ERROR,
1200 * mGuestRc will contain the actual
1201 * error code from the guest side. */
1202 int mRc;
1203 /** The event'S overall result from the
1204 * guest side. If used, mRc must be
1205 * set to VERR_GSTCTL_GUEST_ERROR. */
1206 int mGuestRc;
1207 /** The event's payload data. Optional. */
1208 GuestWaitEventPayload mPayload;
1209};
1210
1211/** List of public guest event types. */
1212typedef std::list < VBoxEventType_T > GuestEventTypes;
1213
1214class GuestWaitEvent : public GuestWaitEventBase
1215{
1216
1217public:
1218
1219 GuestWaitEvent(void);
1220 virtual ~GuestWaitEvent(void);
1221
1222public:
1223
1224 int Init(uint32_t uCID);
1225 int Init(uint32_t uCID, const GuestEventTypes &lstEvents);
1226 int Cancel(void);
1227 const ComPtr<IEvent> Event(void) { return mEvent; }
1228 bool HasGuestError(void) const { return mRc == VERR_GSTCTL_GUEST_ERROR; }
1229 int GetGuestError(void) const { return mGuestRc; }
1230 int SignalExternal(IEvent *pEvent);
1231 const GuestEventTypes &Types(void) { return mEventTypes; }
1232 size_t TypeCount(void) { return mEventTypes.size(); }
1233
1234protected:
1235
1236 /** List of public event types this event should
1237 * be signalled on. Optional. */
1238 GuestEventTypes mEventTypes;
1239 /** Pointer to the actual public event, if any. */
1240 ComPtr<IEvent> mEvent;
1241};
1242/** Map of pointers to guest events. The primary key
1243 * contains the context ID. */
1244typedef std::map < uint32_t, GuestWaitEvent* > GuestWaitEvents;
1245/** Map of wait events per public guest event. Nice for
1246 * faster lookups when signalling a whole event group. */
1247typedef std::map < VBoxEventType_T, GuestWaitEvents > GuestEventGroup;
1248
1249class GuestBase
1250{
1251
1252public:
1253
1254 GuestBase(void);
1255 virtual ~GuestBase(void);
1256
1257public:
1258
1259 /** Signals a wait event using a public guest event; also used for
1260 * for external event listeners. */
1261 int signalWaitEvent(VBoxEventType_T aType, IEvent *aEvent);
1262 /** Signals a wait event using a guest rc. */
1263 int signalWaitEventInternal(PVBOXGUESTCTRLHOSTCBCTX pCbCtx, int guestRc, const GuestWaitEventPayload *pPayload);
1264 /** Signals a wait event without letting public guest events know,
1265 * extended director's cut version. */
1266 int signalWaitEventInternalEx(PVBOXGUESTCTRLHOSTCBCTX pCbCtx, int rc, int guestRc, const GuestWaitEventPayload *pPayload);
1267
1268public:
1269
1270 int baseInit(void);
1271 void baseUninit(void);
1272 int cancelWaitEvents(void);
1273 int dispatchGeneric(PVBOXGUESTCTRLHOSTCBCTX pCtxCb, PVBOXGUESTCTRLHOSTCALLBACK pSvcCb);
1274 int generateContextID(uint32_t uSessionID, uint32_t uObjectID, uint32_t *puContextID);
1275 int registerWaitEvent(uint32_t uSessionID, uint32_t uObjectID, GuestWaitEvent **ppEvent);
1276 int registerWaitEventEx(uint32_t uSessionID, uint32_t uObjectID, const GuestEventTypes &lstEvents, GuestWaitEvent **ppEvent);
1277 int unregisterWaitEvent(GuestWaitEvent *pEvent);
1278 int waitForEvent(GuestWaitEvent *pEvent, uint32_t uTimeoutMS, VBoxEventType_T *pType, IEvent **ppEvent);
1279
1280#ifndef VBOX_GUESTCTRL_TEST_CASE
1281 HRESULT setErrorExternal(VirtualBoxBase *pInterface, const Utf8Str &strAction, const GuestErrorInfo &guestErrorInfo);
1282#endif
1283
1284public:
1285
1286 static FsObjType_T fileModeToFsObjType(RTFMODE fMode);
1287 static Utf8Str getErrorAsString(const Utf8Str &strAction, const GuestErrorInfo& guestErrorInfo);
1288 static Utf8Str getErrorAsString(const GuestErrorInfo &guestErrorInfo);
1289
1290protected:
1291
1292 /** Pointer to the console object. Needed
1293 * for HGCM (VMMDev) communication. */
1294 Console *mConsole;
1295 /** The next context ID counter component for this object. */
1296 uint32_t mNextContextID;
1297 /** Local listener for handling the waiting events
1298 * internally. */
1299 ComPtr<IEventListener> mLocalListener;
1300 /** Critical section for wait events access. */
1301 RTCRITSECT mWaitEventCritSect;
1302 /** Map of registered wait events per event group. */
1303 GuestEventGroup mWaitEventGroups;
1304 /** Map of registered wait events. */
1305 GuestWaitEvents mWaitEvents;
1306};
1307
1308/**
1309 * Virtual class (interface) for guest objects (processes, files, ...) --
1310 * contains all per-object callback management.
1311 */
1312class GuestObject : public GuestBase
1313{
1314 friend class GuestSession;
1315
1316public:
1317
1318 GuestObject(void);
1319 virtual ~GuestObject(void);
1320
1321public:
1322
1323 ULONG getObjectID(void) { return mObjectID; }
1324
1325protected:
1326
1327 /**
1328 * Called by IGuestSession when the session status has been changed.
1329 *
1330 * @returns VBox status code.
1331 * @param enmSessionStatus New session status.
1332 */
1333 virtual int i_onSessionStatusChange(GuestSessionStatus_T enmSessionStatus) = 0;
1334
1335 /**
1336 * Called by IGuestSession right before this object gets
1337 * unregistered (removed) from the public object list.
1338 */
1339 virtual int i_onUnregister(void) = 0;
1340
1341 /** Callback dispatcher -- must be implemented by the actual object. */
1342 virtual int i_callbackDispatcher(PVBOXGUESTCTRLHOSTCBCTX pCbCtx, PVBOXGUESTCTRLHOSTCALLBACK pSvcCb) = 0;
1343
1344protected:
1345
1346 int bindToSession(Console *pConsole, GuestSession *pSession, uint32_t uObjectID);
1347 int registerWaitEvent(const GuestEventTypes &lstEvents, GuestWaitEvent **ppEvent);
1348 int sendMessage(uint32_t uFunction, uint32_t cParms, PVBOXHGCMSVCPARM paParms);
1349
1350protected:
1351
1352 /** @name Common parameters for all derived objects. They have their own
1353 * mData structure to keep their specific data around.
1354 * @{ */
1355 /** Pointer to parent session. Per definition
1356 * this objects *always* lives shorter than the
1357 * parent.
1358 * @todo r=bird: When wanting to use mSession in the
1359 * IGuestProcess::getEnvironment() implementation I wanted to access
1360 * GuestSession::mData::mpBaseEnvironment. Seeing the comment in
1361 * GuestProcess::terminate() saying:
1362 * "Now only API clients still can hold references to it."
1363 * and recalling seeing similar things in VirtualBox.xidl or some such place,
1364 * I'm wondering how this "per definition" behavior is enforced. Is there any
1365 * GuestProcess:uninit() call or similar magic that invalidates objects that
1366 * GuestSession loses track of in place like GuestProcess::terminate() that I've
1367 * failed to spot?
1368 *
1369 * Please enlighten me.
1370 */
1371 GuestSession *mSession;
1372 /** The object ID -- must be unique for each guest
1373 * object and is encoded into the context ID. Must
1374 * be set manually when initializing the object.
1375 *
1376 * For guest processes this is the internal PID,
1377 * for guest files this is the internal file ID. */
1378 uint32_t mObjectID;
1379 /** @} */
1380};
1381#endif /* !MAIN_INCLUDED_GuestCtrlImplPrivate_h */
1382
Note: See TracBrowser for help on using the repository browser.

© 2023 Oracle
Contact – Privacy policy – Terms of Use