VirtualBox

source: vbox/trunk/src/VBox/Main/include/GuestProcessImpl.h@ 98694

Last change on this file since 98694 was 98614, checked in by vboxsync, 23 months ago

Main/GuestProcess: Simplified the GuestProcessToolbox::run stuff to sort out the issue VERR_IPE_UNINITIALIZED_STATUS introduced around r155802+. Also decoded the meaning of the GuestCtrlStreamObjects parameters and tried to make that easier to understand for the uninitiated. bugref:9783
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 11.5 KB
Line 
1/* $Id: GuestProcessImpl.h 98614 2023-02-17 01:09:38Z vboxsync $ */
2/** @file
3 * VirtualBox Main - Guest process handling implementation.
4 */
5
6/*
7 * Copyright (C) 2012-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_GuestProcessImpl_h
29#define MAIN_INCLUDED_GuestProcessImpl_h
30#ifndef RT_WITHOUT_PRAGMA_ONCE
31# pragma once
32#endif
33
34#include "GuestCtrlImplPrivate.h"
35#include "GuestProcessWrap.h"
36
37#include <iprt/cpp/utils.h>
38
39class Console;
40class GuestSession;
41class GuestProcessStartTask;
42
43/**
44 * Class for handling a guest process.
45 */
46class ATL_NO_VTABLE GuestProcess :
47 public GuestProcessWrap,
48 public GuestObject
49{
50public:
51 /** @name COM and internal init/term/mapping cruft.
52 * @{ */
53 DECLARE_COMMON_CLASS_METHODS(GuestProcess)
54
55 int init(Console *aConsole, GuestSession *aSession, ULONG aObjectID,
56 const GuestProcessStartupInfo &aProcInfo, const GuestEnvironment *pBaseEnv);
57 void uninit(void);
58 HRESULT FinalConstruct(void);
59 void FinalRelease(void);
60 /** @} */
61
62public:
63 /** @name Implemented virtual methods from GuestObject.
64 * @{ */
65 int i_callbackDispatcher(PVBOXGUESTCTRLHOSTCBCTX pCbCtx, PVBOXGUESTCTRLHOSTCALLBACK pSvcCb);
66 int i_onUnregister(void);
67 int i_onSessionStatusChange(GuestSessionStatus_T enmSessionStatus);
68 /** @} */
69
70public:
71 /** @name Public internal methods.
72 * @{ */
73 inline int i_checkPID(uint32_t uPID);
74 ProcessStatus_T i_getStatus(void);
75 int i_readData(uint32_t uHandle, uint32_t uSize, uint32_t uTimeoutMS, void *pvData, size_t cbData, uint32_t *pcbRead, int *pvrcGuest);
76 int i_startProcess(uint32_t cMsTimeout, int *pvrcGuest);
77 int i_startProcessInner(uint32_t cMsTimeout, AutoWriteLock &rLock, GuestWaitEvent *pEvent, int *pvrcGuest);
78 int i_startProcessAsync(void);
79 int i_terminateProcess(uint32_t uTimeoutMS, int *pvrcGuest);
80 ProcessWaitResult_T i_waitFlagsToResult(uint32_t fWaitFlags);
81 int i_waitFor(uint32_t fWaitFlags, ULONG uTimeoutMS, ProcessWaitResult_T &waitResult, int *pvrcGuest);
82 int i_waitForInputNotify(GuestWaitEvent *pEvent, uint32_t uHandle, uint32_t uTimeoutMS, ProcessInputStatus_T *pInputStatus, uint32_t *pcbProcessed);
83 int i_waitForOutput(GuestWaitEvent *pEvent, uint32_t uHandle, uint32_t uTimeoutMS, void* pvData, size_t cbData, uint32_t *pcbRead);
84 int i_waitForStatusChange(GuestWaitEvent *pEvent, uint32_t uTimeoutMS, ProcessStatus_T *pProcessStatus, int *pvrcGuest);
85 int i_writeData(uint32_t uHandle, uint32_t uFlags, void *pvData, size_t cbData, uint32_t uTimeoutMS, uint32_t *puWritten, int *pvrcGuest);
86 /** @} */
87
88 /** @name Static internal methods.
89 * @{ */
90 static Utf8Str i_guestErrorToString(int vrcGuest, const char *pcszWhat);
91 static Utf8Str i_statusToString(ProcessStatus_T enmStatus);
92 static bool i_isGuestError(int guestRc);
93 static ProcessWaitResult_T i_waitFlagsToResultEx(uint32_t fWaitFlags, ProcessStatus_T oldStatus, ProcessStatus_T newStatus, uint32_t uProcFlags, uint32_t uProtocol);
94#if 0 /* unused */
95 static bool i_waitResultImpliesEx(ProcessWaitResult_T waitResult, ProcessStatus_T procStatus, uint32_t uProtocol);
96#endif
97 /** @} */
98
99protected:
100 /** @name Protected internal methods.
101 * @{ */
102 inline bool i_isAlive(void);
103 inline bool i_hasEnded(void);
104 int i_onGuestDisconnected(PVBOXGUESTCTRLHOSTCBCTX pCbCtx, PVBOXGUESTCTRLHOSTCALLBACK pSvcCbData);
105 int i_onProcessInputStatus(PVBOXGUESTCTRLHOSTCBCTX pCbCtx, PVBOXGUESTCTRLHOSTCALLBACK pSvcCbData);
106 int i_onProcessNotifyIO(PVBOXGUESTCTRLHOSTCBCTX pCbCtx, PVBOXGUESTCTRLHOSTCALLBACK pSvcCbData);
107 int i_onProcessStatusChange(PVBOXGUESTCTRLHOSTCBCTX pCbCtx, PVBOXGUESTCTRLHOSTCALLBACK pSvcCbData);
108 int i_onProcessOutput(PVBOXGUESTCTRLHOSTCBCTX pCbCtx, PVBOXGUESTCTRLHOSTCALLBACK pSvcCbData);
109 int i_prepareExecuteEnv(const char *pszEnv, void **ppvList, ULONG *pcbList, ULONG *pcEnvVars);
110 int i_setProcessStatus(ProcessStatus_T procStatus, int vrcProc);
111 static int i_startProcessThreadTask(GuestProcessStartTask *pTask);
112 /** @} */
113
114private:
115 /** Wrapped @name IProcess properties.
116 * @{ */
117 HRESULT getArguments(std::vector<com::Utf8Str> &aArguments);
118 HRESULT getEnvironment(std::vector<com::Utf8Str> &aEnvironment);
119 HRESULT getEventSource(ComPtr<IEventSource> &aEventSource);
120 HRESULT getExecutablePath(com::Utf8Str &aExecutablePath);
121 HRESULT getExitCode(LONG *aExitCode);
122 HRESULT getName(com::Utf8Str &aName);
123 HRESULT getPID(ULONG *aPID);
124 HRESULT getStatus(ProcessStatus_T *aStatus);
125 /** @} */
126
127 /** Wrapped @name IProcess methods.
128 * @{ */
129 HRESULT waitFor(ULONG aWaitFor,
130 ULONG aTimeoutMS,
131 ProcessWaitResult_T *aReason);
132 HRESULT waitForArray(const std::vector<ProcessWaitForFlag_T> &aWaitFor,
133 ULONG aTimeoutMS,
134 ProcessWaitResult_T *aReason);
135 HRESULT read(ULONG aHandle,
136 ULONG aToRead,
137 ULONG aTimeoutMS,
138 std::vector<BYTE> &aData);
139 HRESULT write(ULONG aHandle,
140 ULONG aFlags,
141 const std::vector<BYTE> &aData,
142 ULONG aTimeoutMS,
143 ULONG *aWritten);
144 HRESULT writeArray(ULONG aHandle,
145 const std::vector<ProcessInputFlag_T> &aFlags,
146 const std::vector<BYTE> &aData,
147 ULONG aTimeoutMS,
148 ULONG *aWritten);
149 HRESULT terminate(void);
150 /** @} */
151
152 /**
153 * This can safely be used without holding any locks.
154 * An AutoCaller suffices to prevent it being destroy while in use and
155 * internally there is a lock providing the necessary serialization.
156 */
157 const ComObjPtr<EventSource> mEventSource;
158
159 struct Data
160 {
161 /** The process startup information. */
162 GuestProcessStartupInfo mProcess;
163 /** Reference to the immutable session base environment. NULL if the
164 * environment feature isn't supported.
165 * @remarks If there is proof that the uninit order of GuestSession and
166 * this class is what GuestObjectBase claims, then this isn't
167 * strictly necessary. */
168 GuestEnvironment const *mpSessionBaseEnv;
169 /** Exit code if process has been terminated. */
170 LONG mExitCode;
171 /** PID reported from the guest.
172 * Note: This is *not* the internal object ID! */
173 ULONG mPID;
174 /** The current process status. */
175 ProcessStatus_T mStatus;
176 /** The last returned process status
177 * returned from the guest side. */
178 int mLastError;
179
180 Data(void) : mpSessionBaseEnv(NULL)
181 { }
182 ~Data(void)
183 {
184 if (mpSessionBaseEnv)
185 {
186 mpSessionBaseEnv->releaseConst();
187 mpSessionBaseEnv = NULL;
188 }
189 }
190 } mData;
191
192 friend class GuestProcessStartTask;
193};
194
195/**
196 * Guest process tool wait flags.
197 */
198/** No wait flags specified; wait until process terminates.
199 * The maximum waiting time is set in the process' startup
200 * info. */
201#define GUESTPROCESSTOOL_WAIT_FLAG_NONE 0
202/** Wait until next stream block from stdout has been
203 * read in completely, then return.
204 */
205#define GUESTPROCESSTOOL_WAIT_FLAG_STDOUT_BLOCK RT_BIT(0)
206
207/**
208 * Structure for keeping a VBoxService toolbox tool's error info around.
209 */
210struct GuestProcessToolErrorInfo
211{
212 /** Return (VBox status) code from the guest side for executing the process tool. */
213 int vrcGuest;
214 /** The process tool's returned exit code. */
215 int32_t iExitCode;
216};
217
218/**
219 * Internal class for handling the BusyBox-like tools built into VBoxService
220 * on the guest side. It's also called the VBoxService Toolbox (tm).
221 *
222 * Those initially were necessary to guarantee execution of commands (like "ls", "cat")
223 * under the behalf of a certain guest user.
224 *
225 * This class essentially helps to wrap all the gory details like process creation,
226 * information extraction and maintaining the overall status.
227 *
228 * Note! When implementing new functionality / commands, do *not* use this approach anymore!
229 * This class has to be kept to guarantee backwards-compatibility.
230 */
231class GuestProcessToolbox
232{
233public:
234 DECLARE_TRANSLATE_METHODS(GuestProcessTool)
235
236 GuestProcessToolbox(void);
237
238 virtual ~GuestProcessToolbox(void);
239
240public:
241
242 int init(GuestSession *pGuestSession, const GuestProcessStartupInfo &startupInfo, bool fAsync, int *pvrcGuest);
243
244 void uninit(void);
245
246 int getCurrentBlock(uint32_t uHandle, GuestToolboxStreamBlock &strmBlock);
247
248 int getRc(void) const;
249
250 /** Returns the stdout output from the guest process tool. */
251 GuestToolboxStream &getStdOut(void) { return mStdOut; }
252
253 /** Returns the stderr output from the guest process tool. */
254 GuestToolboxStream &getStdErr(void) { return mStdErr; }
255
256 int wait(uint32_t fToolWaitFlags, int *pvrcGuest);
257
258 int waitEx(uint32_t fToolWaitFlags, GuestToolboxStreamBlock *pStreamBlock, int *pvrcGuest);
259
260 bool isRunning(void);
261
262 bool isTerminatedOk(void);
263
264 int getTerminationStatus(int32_t *piExitCode = NULL);
265
266 int terminate(uint32_t uTimeoutMS, int *pvrcGuest);
267
268public:
269
270 /** Wrapped @name Static run methods.
271 * @note Do not call anything 'run' here, it's way too common.
272 * @{ */
273 static int runTool(GuestSession *pGuestSession, const GuestProcessStartupInfo &startupInfo, int *pvrcGuest,
274 GuestCtrlStreamObjects *pLstStdOutObjPairs = NULL, uint32_t cStdOutObjectsToRead = 1);
275
276 static int runToolWithErrorInfo(GuestSession *pGuestSession, const GuestProcessStartupInfo &startupInfo,
277 GuestProcessToolErrorInfo &errorInfo,
278 GuestCtrlStreamObjects *pLstStdOutObjPairs = NULL, uint32_t cStdOutObjectsToRead = 1);
279 /** @} */
280
281 /** Wrapped @name Static exit code conversion methods.
282 * @{ */
283 static int exitCodeToRc(const GuestProcessStartupInfo &startupInfo, int32_t iExitCode);
284
285 static int exitCodeToRc(const char *pszTool, int32_t iExitCode);
286 /** @} */
287
288 /** Wrapped @name Static guest error conversion methods.
289 * @{ */
290 static Utf8Str guestErrorToString(const char *pszTool, const GuestErrorInfo& guestErrorInfo);
291 /** @} */
292
293protected:
294
295 /** Pointer to session this toolbox object is bound to. */
296 ComObjPtr<GuestSession> pSession;
297 /** Pointer to process object this toolbox object is bound to. */
298 ComObjPtr<GuestProcess> pProcess;
299 /** The toolbox' startup info. */
300 GuestProcessStartupInfo mStartupInfo;
301 /** Stream object for handling the toolbox' stdout data. */
302 GuestToolboxStream mStdOut;
303 /** Stream object for handling the toolbox' stderr data. */
304 GuestToolboxStream mStdErr;
305};
306
307#endif /* !MAIN_INCLUDED_GuestProcessImpl_h */
308
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