VirtualBox

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

Last change on this file since 75267 was 73036, checked in by vboxsync, 6 years ago

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