VirtualBox

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

Last change on this file since 67954 was 66857, checked in by vboxsync, 7 years ago

Guest Control/Main: Event fixes (for bugref:8833):

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

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette