VirtualBox

source: vbox/trunk/src/VBox/Main/include/GuestSessionImplTasks.h@ 94521

Last change on this file since 94521 was 93115, checked in by vboxsync, 2 years ago

scm --update-copyright-year
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 12.4 KB
Line 
1/* $Id: GuestSessionImplTasks.h 93115 2022-01-01 11:31:46Z vboxsync $ */
2/** @file
3 * VirtualBox Main - Guest session tasks header.
4 */
5
6/*
7 * Copyright (C) 2018-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_GuestSessionImplTasks_h
19#define MAIN_INCLUDED_GuestSessionImplTasks_h
20#ifndef RT_WITHOUT_PRAGMA_ONCE
21# pragma once
22#endif
23
24#include "GuestSessionWrap.h"
25#include "EventImpl.h"
26
27#include "GuestCtrlImplPrivate.h"
28#include "GuestSessionImpl.h"
29#include "ThreadTask.h"
30
31#include <iprt/vfs.h>
32
33#include <vector>
34
35class Guest;
36class GuestSessionTask;
37class GuestSessionTaskInternalStart;
38
39
40/**
41 * Structure for keeping a file system source specification,
42 * along with options.
43 */
44struct GuestSessionFsSourceSpec
45{
46 GuestSessionFsSourceSpec()
47 : enmType(FsObjType_Unknown)
48 , enmPathStyle(PathStyle_Unknown)
49 , fDryRun(false) { RT_ZERO(Type); }
50
51 /** The (absolute) path to the source to use. */
52 Utf8Str strSource;
53 /** Filter to use. Currently not implemented and thus ignored. */
54 Utf8Str strFilter;
55 /** The object type of this source. */
56 FsObjType_T enmType;
57 /** The path style to use. */
58 PathStyle_T enmPathStyle;
59 /** Whether to do a dry run (e.g. not really touching anything) or not. */
60 bool fDryRun;
61 /** Union to keep type-specific data. Must be a POD type (zero'ing). */
62 union
63 {
64 /** Directory-specific data. */
65 struct
66 {
67 /** Directory copy flags. */
68 DirectoryCopyFlag_T fCopyFlags;
69 } Dir;
70 /** File-specific data. */
71 struct
72 {
73 /** File copy flags. */
74 FileCopyFlag_T fCopyFlags;
75 /** Source file offset to start copying from. */
76 size_t offStart;
77 /** Host file handle to use for reading from / writing to.
78 * Optional and can be NULL if not used. */
79 PRTFILE phFile;
80 /** Source size (in bytes) to copy. */
81 uint64_t cbSize;
82 } File;
83 } Type;
84};
85
86/** A set of GuestSessionFsSourceSpec sources. */
87typedef std::vector<GuestSessionFsSourceSpec> GuestSessionFsSourceSet;
88
89/**
90 * Structure for keeping a file system entry.
91 */
92struct FsEntry
93{
94 /** The entrie's file mode. */
95 RTFMODE fMode;
96 /** The entrie's path, relative to the list's root path. */
97 Utf8Str strPath;
98};
99
100/** A vector of FsEntry entries. */
101typedef std::vector<FsEntry *> FsEntries;
102
103/**
104 * Class for storing and handling file system entries, neeed for doing
105 * internal file / directory operations to / from the guest.
106 */
107class FsList
108{
109public:
110
111 FsList(const GuestSessionTask &Task);
112 virtual ~FsList();
113
114public:
115
116 int Init(const Utf8Str &strSrcRootAbs, const Utf8Str &strDstRootAbs, const GuestSessionFsSourceSpec &SourceSpec);
117 void Destroy(void);
118
119 int AddEntryFromGuest(const Utf8Str &strFile, const GuestFsObjData &fsObjData);
120 int AddDirFromGuest(const Utf8Str &strPath, const Utf8Str &strSubDir = "");
121
122 int AddEntryFromHost(const Utf8Str &strFile, PCRTFSOBJINFO pcObjInfo);
123 int AddDirFromHost(const Utf8Str &strPath, const Utf8Str &strSubDir = "");
124
125public:
126
127 /** The guest session task object this list is working on. */
128 const GuestSessionTask &mTask;
129 /** File system filter / options to use for this task. */
130 GuestSessionFsSourceSpec mSourceSpec;
131 /** The source' root path.
132 * For a single file list this is the full (absolute) path to a file,
133 * for a directory list this is the source root directory. */
134 Utf8Str mSrcRootAbs;
135 /** The destinations's root path.
136 * For a single file list this is the full (absolute) path to a file,
137 * for a directory list this is the destination root directory. */
138 Utf8Str mDstRootAbs;
139 /** Total size (in bytes) of all list entries together. */
140 uint64_t mcbTotalSize;
141 /** List of file system entries this list contains. */
142 FsEntries mVecEntries;
143};
144
145/** A set of FsList lists. */
146typedef std::vector<FsList *> FsLists;
147
148/**
149 * Abstract base class for a lenghtly per-session operation which
150 * runs in a Main worker thread.
151 */
152class GuestSessionTask
153 : public ThreadTask
154{
155public:
156 DECLARE_TRANSLATE_METHODS(GuestSessionTask)
157
158 GuestSessionTask(GuestSession *pSession);
159
160 virtual ~GuestSessionTask(void);
161
162public:
163
164 /**
165 * Function which implements the actual task to perform.
166 *
167 * @returns VBox status code.
168 */
169 virtual int Run(void) = 0;
170
171 void handler()
172 {
173 int vrc = Run();
174 NOREF(vrc);
175 /** @todo
176 *
177 * r=bird: what was your idea WRT to Run status code and async tasks?
178 *
179 */
180 }
181
182 // unused: int RunAsync(const Utf8Str &strDesc, ComObjPtr<Progress> &pProgress);
183
184 virtual HRESULT Init(const Utf8Str &strTaskDesc)
185 {
186 setTaskDesc(strTaskDesc);
187 int rc = createAndSetProgressObject(); /* Single operation by default. */
188 if (RT_FAILURE(rc))
189 return E_FAIL;
190
191 return S_OK;
192 }
193
194 /** Returns the task's progress object. */
195 const ComObjPtr<Progress>& GetProgressObject(void) const { return mProgress; }
196
197 /** Returns the task's guest session object. */
198 const ComObjPtr<GuestSession>& GetSession(void) const { return mSession; }
199
200protected:
201
202 /** @name Directory handling primitives.
203 * @{ */
204 int directoryCreateOnGuest(const com::Utf8Str &strPath,
205 DirectoryCreateFlag_T enmDirectoryCreateFlags, uint32_t fMode,
206 bool fFollowSymlinks, bool fCanExist);
207 int directoryCreateOnHost(const com::Utf8Str &strPath, uint32_t fCreate, uint32_t fMode, bool fCanExist);
208 /** @} */
209
210 /** @name File handling primitives.
211 * @{ */
212 int fileCopyFromGuestInner(const Utf8Str &strSrcFile, ComObjPtr<GuestFile> &srcFile,
213 const Utf8Str &strDstFile, PRTFILE phDstFile,
214 FileCopyFlag_T fFileCopyFlags, uint64_t offCopy, uint64_t cbSize);
215 int fileCopyFromGuest(const Utf8Str &strSource, const Utf8Str &strDest, FileCopyFlag_T fFileCopyFlags);
216 int fileCopyToGuestInner(const Utf8Str &strSrcFile, RTVFSFILE hSrcFile,
217 const Utf8Str &strDstFile, ComObjPtr<GuestFile> &dstFile,
218 FileCopyFlag_T fFileCopyFlags, uint64_t offCopy, uint64_t cbSize);
219
220 int fileCopyToGuest(const Utf8Str &strSource, const Utf8Str &strDest, FileCopyFlag_T fFileCopyFlags);
221 /** @} */
222
223 /** @name Guest property handling primitives.
224 * @{ */
225 int getGuestProperty(const ComObjPtr<Guest> &pGuest, const Utf8Str &strPath, Utf8Str &strValue);
226 /** @} */
227
228 int setProgress(ULONG uPercent);
229 int setProgressSuccess(void);
230 HRESULT setProgressErrorMsg(HRESULT hr, const Utf8Str &strMsg);
231 HRESULT setProgressErrorMsg(HRESULT hr, const Utf8Str &strMsg, const GuestErrorInfo &guestErrorInfo);
232
233 inline void setTaskDesc(const Utf8Str &strTaskDesc) throw()
234 {
235 mDesc = strTaskDesc;
236 }
237
238 int createAndSetProgressObject(ULONG cOperations = 1);
239
240protected:
241
242 Utf8Str mDesc;
243 /** The guest session object this task is working on. */
244 ComObjPtr<GuestSession> mSession;
245 /** Progress object for getting updated when running
246 * asynchronously. Optional. */
247 ComObjPtr<Progress> mProgress;
248 /** The guest's path style (depending on the guest OS type set). */
249 uint32_t mfPathStyle;
250 /** The guest's path style as string representation (depending on the guest OS type set). */
251 Utf8Str mPathStyle;
252};
253
254/**
255 * Task for opening a guest session.
256 */
257class GuestSessionTaskOpen : public GuestSessionTask
258{
259public:
260
261 GuestSessionTaskOpen(GuestSession *pSession,
262 uint32_t uFlags,
263 uint32_t uTimeoutMS);
264 virtual ~GuestSessionTaskOpen(void);
265 int Run(void);
266
267protected:
268
269 /** Session creation flags. */
270 uint32_t mFlags;
271 /** Session creation timeout (in ms). */
272 uint32_t mTimeoutMS;
273};
274
275class GuestSessionCopyTask : public GuestSessionTask
276{
277public:
278 DECLARE_TRANSLATE_METHODS(GuestSessionCopyTask)
279
280 GuestSessionCopyTask(GuestSession *pSession);
281 virtual ~GuestSessionCopyTask();
282
283protected:
284
285 /** Source set. */
286 GuestSessionFsSourceSet mSources;
287 /** Destination to copy to. */
288 Utf8Str mDest;
289 /** Vector of file system lists to handle.
290 * This either can be from the guest or the host side. */
291 FsLists mVecLists;
292};
293
294/**
295 * Guest session task for copying files / directories from guest to the host.
296 */
297class GuestSessionTaskCopyFrom : public GuestSessionCopyTask
298{
299public:
300 DECLARE_TRANSLATE_METHODS(GuestSessionTaskCopyFrom)
301
302 GuestSessionTaskCopyFrom(GuestSession *pSession, GuestSessionFsSourceSet const &vecSrc, const Utf8Str &strDest);
303 virtual ~GuestSessionTaskCopyFrom(void);
304
305 HRESULT Init(const Utf8Str &strTaskDesc);
306 int Run(void);
307};
308
309/**
310 * Task for copying directories from host to the guest.
311 */
312class GuestSessionTaskCopyTo : public GuestSessionCopyTask
313{
314public:
315 DECLARE_TRANSLATE_METHODS(GuestSessionTaskCopyTo)
316
317 GuestSessionTaskCopyTo(GuestSession *pSession, GuestSessionFsSourceSet const &vecSrc, const Utf8Str &strDest);
318 virtual ~GuestSessionTaskCopyTo(void);
319
320 HRESULT Init(const Utf8Str &strTaskDesc);
321 int Run(void);
322};
323
324/**
325 * Guest session task for automatically updating the Guest Additions on the guest.
326 */
327class GuestSessionTaskUpdateAdditions : public GuestSessionTask
328{
329public:
330 DECLARE_TRANSLATE_METHODS(GuestSessionTaskUpdateAdditions)
331
332 GuestSessionTaskUpdateAdditions(GuestSession *pSession, const Utf8Str &strSource,
333 const ProcessArguments &aArguments, uint32_t fFlags);
334 virtual ~GuestSessionTaskUpdateAdditions(void);
335 int Run(void);
336
337protected:
338
339 /**
340 * Suported OS types for automatic updating.
341 */
342 enum eOSType
343 {
344 eOSType_Unknown = 0,
345 eOSType_Windows = 1,
346 eOSType_Linux = 2,
347 eOSType_Solaris = 3
348 };
349
350 /**
351 * Structure representing a file to
352 * get off the .ISO, copied to the guest.
353 */
354 struct ISOFile
355 {
356 ISOFile(const Utf8Str &aSource,
357 const Utf8Str &aDest,
358 uint32_t aFlags = 0)
359 : strSource(aSource),
360 strDest(aDest),
361 fFlags(aFlags) { }
362
363 ISOFile(const Utf8Str &aSource,
364 const Utf8Str &aDest,
365 uint32_t aFlags,
366 const GuestProcessStartupInfo &aStartupInfo)
367 : strSource(aSource),
368 strDest(aDest),
369 fFlags(aFlags),
370 mProcInfo(aStartupInfo)
371 {
372 mProcInfo.mExecutable = strDest;
373 if (mProcInfo.mName.isEmpty())
374 mProcInfo.mName = strDest;
375 }
376
377 /** Source file on .ISO. */
378 Utf8Str strSource;
379 /** Destination file on the guest. */
380 Utf8Str strDest;
381 /** ISO file flags (see ISOFILE_FLAG_ defines). */
382 uint32_t fFlags;
383 /** Optional arguments if this file needs to be
384 * executed. */
385 GuestProcessStartupInfo mProcInfo;
386 };
387
388 int addProcessArguments(ProcessArguments &aArgumentsDest, const ProcessArguments &aArgumentsSource);
389 int copyFileToGuest(GuestSession *pSession, RTVFS hVfsIso, Utf8Str const &strFileSource, const Utf8Str &strFileDest, bool fOptional);
390 int runFileOnGuest(GuestSession *pSession, GuestProcessStartupInfo &procInfo);
391
392 /** Files to handle. */
393 std::vector<ISOFile> mFiles;
394 /** The (optionally) specified Guest Additions .ISO on the host
395 * which will be used for the updating process. */
396 Utf8Str mSource;
397 /** (Optional) installer command line arguments. */
398 ProcessArguments mArguments;
399 /** Update flags. */
400 uint32_t mFlags;
401};
402#endif /* !MAIN_INCLUDED_GuestSessionImplTasks_h */
Note: See TracBrowser for help on using the repository browser.

© 2023 Oracle
Contact – Privacy policy – Terms of Use