VirtualBox

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

Last change on this file since 94173 was 93720, checked in by vboxsync, 3 years ago

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