VirtualBox

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

Last change on this file since 76900 was 76562, checked in by vboxsync, 6 years ago

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