VirtualBox

source: vbox/trunk/src/VBox/Main/include/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
51using namespace com;
52
53#ifdef VBOX_WITH_GUEST_CONTROL
54# include <VBox/GuestHost/GuestControl.h>
55# include <VBox/HostServices/GuestControlSvc.h>
56using namespace guestControl;
57#endif
58
59/** Vector holding a process' CPU affinity. */
60typedef std::vector<LONG> ProcessAffinity;
61/** Vector holding process startup arguments. */
62typedef std::vector<Utf8Str> ProcessArguments;
63
64class GuestToolboxStreamBlock;
65class GuestSession;
66
67
68/**
69 * Simple structure mantaining guest credentials.
70 */
71struct 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 */
84class GuestEnvironmentBase
85{
86public:
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
376protected:
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
454class GuestEnvironmentChanges;
455
456
457/**
458 * Wrapper around the RTEnv API for a normal environment.
459 */
460class GuestEnvironment : public GuestEnvironmentBase
461{
462public:
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 */
542class GuestEnvironmentChanges : public GuestEnvironmentBase
543{
544public:
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 */
619class GuestErrorInfo
620{
621public:
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
708protected:
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 */
722struct 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 */
743struct 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 */
808class GuestFs
809{
810 DECLARE_TRANSLATE_METHODS(GuestFs)
811
812private:
813
814 /* Not directly instantiable. */
815 GuestFs(void) { }
816
817public:
818
819 static Utf8Str guestErrorToString(const GuestErrorInfo &guestErrorInfo);
820};
821
822
823/**
824 * Structure representing information of a
825 * file system object.
826 */
827struct 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 */
903class GuestSessionStartupInfo
904{
905public:
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 */
933class GuestProcessStartupInfo
934{
935public:
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 */
970class GuestToolboxStreamValue
971{
972public:
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. */
993typedef std::pair< Utf8Str, GuestToolboxStreamValue > GuestCtrlStreamPair;
994typedef std::map < Utf8Str, GuestToolboxStreamValue > GuestCtrlStreamPairMap;
995typedef std::map < Utf8Str, GuestToolboxStreamValue >::iterator GuestCtrlStreamPairMapIter;
996typedef 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 */
1006class GuestToolboxStreamBlock
1007{
1008public:
1009
1010 GuestToolboxStreamBlock(void);
1011
1012 virtual ~GuestToolboxStreamBlock(void);
1013
1014public:
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
1035protected:
1036
1037 GuestCtrlStreamPairMap mPairs;
1038};
1039
1040/** Vector containing multiple allocated stream pair objects. */
1041typedef std::vector< GuestToolboxStreamBlock > GuestCtrlStreamObjects;
1042typedef std::vector< GuestToolboxStreamBlock >::iterator GuestCtrlStreamObjectsIter;
1043typedef 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 */
1051class GuestToolboxStream
1052{
1053
1054public:
1055
1056 GuestToolboxStream();
1057
1058 virtual ~GuestToolboxStream();
1059
1060public:
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
1076protected:
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
1091class Guest;
1092class Progress;
1093
1094class GuestWaitEventPayload
1095{
1096
1097public:
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
1135public:
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
1177protected:
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
1211protected:
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
1221class GuestWaitEventBase
1222{
1223
1224protected:
1225
1226 GuestWaitEventBase(void);
1227 virtual ~GuestWaitEventBase(void);
1228
1229public:
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
1239protected:
1240
1241 int Init(uint32_t uCID);
1242
1243protected:
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. */
1263typedef std::list < VBoxEventType_T > GuestEventTypes;
1264
1265class GuestWaitEvent : public GuestWaitEventBase
1266{
1267
1268public:
1269
1270 GuestWaitEvent(void);
1271 virtual ~GuestWaitEvent(void);
1272
1273public:
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
1283protected:
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. */
1293typedef 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. */
1296typedef std::map < VBoxEventType_T, GuestWaitEvents > GuestEventGroup;
1297
1298class GuestBase
1299{
1300
1301public:
1302
1303 GuestBase(void);
1304 virtual ~GuestBase(void);
1305
1306public:
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
1317public:
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
1329public:
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
1337protected:
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 */
1359class GuestObject : public GuestBase
1360{
1361 friend class GuestSession;
1362
1363public:
1364
1365 GuestObject(void);
1366 virtual ~GuestObject(void);
1367
1368public:
1369
1370 ULONG getObjectID(void) { return mObjectID; }
1371
1372protected:
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
1391protected:
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
1397protected:
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 */
1440class GuestPath
1441{
1442private:
1443
1444 /**
1445 * Default constructor.
1446 *
1447 * Not directly instantiable (yet).
1448 */
1449 GuestPath(void) { }
1450
1451public:
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 */
1472typedef 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. */
1480typedef CALLBACKDATA_HEADER *PCALLBACKDATA_HEADER;
1481
1482/**
1483 * Host service callback data when a HGCM client disconnected.
1484 */
1485typedef 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. */
1491typedef CALLBACKDATA_CLIENT_DISCONNECTED *PCALLBACKDATA_CLIENT_DISCONNECTED;
1492
1493/**
1494 * Host service callback data for a generic guest reply.
1495 */
1496typedef 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. */
1510typedef CALLBACKDATA_MSG_REPLY *PCALLBACKDATA_MSG_REPLY;
1511
1512/**
1513 * Host service callback data for guest session notifications.
1514 */
1515typedef 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. */
1525typedef CALLBACKDATA_SESSION_NOTIFY *PCALLBACKDATA_SESSION_NOTIFY;
1526
1527/**
1528 * Host service callback data for guest process status notifications.
1529 */
1530typedef 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. */
1546typedef CALLBACKDATA_PROC_STATUS* PCALLBACKDATA_PROC_STATUS;
1547
1548/**
1549 * Host service callback data for guest process output notifications.
1550 */
1551typedef 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. */
1567typedef CALLBACKDATA_PROC_OUTPUT *PCALLBACKDATA_PROC_OUTPUT;
1568
1569/**
1570 * Host service callback data guest process input notifications.
1571 */
1572typedef 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. */
1586typedef CALLBACKDATA_PROC_INPUT *PCALLBACKDATA_PROC_INPUT;
1587
1588/**
1589 * General guest file notification callback.
1590 */
1591typedef 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. */
1637typedef CALLBACKDATA_FILE_NOTIFY *PCALLBACKDATA_FILE_NOTIFY;
1638
1639/**
1640 * Callback data for a single GSTCTLDIRENTRYEX entry.
1641 */
1642typedef 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. */
1659typedef CALLBACKDATA_DIR_ENTRY *PCALLBACKDATA_DIR_ENTRY;
1660
1661/**
1662 * Callback data for guest directory operations.
1663 */
1664typedef 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. */
1700typedef CALLBACKDATA_DIR_NOTIFY *PCALLBACKDATA_DIR_NOTIFY;
1701
1702/**
1703 * Callback data for guest file system operations.
1704 */
1705typedef 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. */
1745typedef CALLBACKDATA_FS_NOTIFY *PCALLBACKDATA_FS_NOTIFY;
1746#endif /* !MAIN_INCLUDED_GuestCtrlImplPrivate_h */
1747
Note: See TracBrowser for help on using the repository browser.

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