Changeset 92897 in vbox for trunk/src/VBox/Main/src-client/GuestSessionImplTasks.cpp

Timestamp:

Dec 14, 2021 1:53:27 PM (3 years ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

148852

Message:

Guest Control/Main: Added lots of missing docs.

File:

• trunk/src/VBox/Main/src-client/GuestSessionImplTasks.cpp (modified) (14 diffs)

trunk/src/VBox/Main/src-client/GuestSessionImplTasks.cpp

@@ -5 +5 @@
 
 /*
- * Copyright (C) 2012-2020 Oracle Corporation
+ * Copyright (C) 2012-2021 Oracle Corporation
  *
  * This file is part of VirtualBox Open Source Edition (OSE), as
@@ -91 +91 @@
 }
 
+/**
+ * Creates (and initializes / sets) the progress objects of a guest session task.
+ *
+ * @returns VBox status code.
+ * @param   cOperations         Number of operation the task wants to perform.
+ */
 int GuestSessionTask::createAndSetProgressObject(ULONG cOperations /* = 1 */)
 {
@@ -128 +134 @@
 #endif
 
+/**
+ * Gets a guest property from the VM.
+ *
+ * @returns VBox status code.
+ * @param   pGuest              Guest object of VM to get guest property from.
+ * @param   strPath             Guest property to path to get.
+ * @param   strValue            Where to store the guest property value on success.
+ */
 int GuestSessionTask::getGuestProperty(const ComObjPtr<Guest> &pGuest,
                                        const Utf8Str &strPath, Utf8Str &strValue)
@@ -148 +162 @@
 }
 
+/**
+ * Sets the percentage of a guest session task progress.
+ *
+ * @returns VBox status code.
+ * @param   uPercent            Percentage (0-100) to set.
+ */
 int GuestSessionTask::setProgress(ULONG uPercent)
 {
@@ -171 +191 @@
 }
 
+/**
+ * Sets the task's progress object to succeeded.
+ *
+ * @returns VBox status code.
+ */
 int GuestSessionTask::setProgressSuccess(void)
 {
@@ -1334 +1359 @@
 }
 
+/** @copydoc GuestSessionTask::Run */
 int GuestSessionTaskOpen::Run(void)
 {
@@ -1382 +1408 @@
 }
 
+/**
+ * Initializes a copy-from-guest task.
+ *
+ * @returns HRESULT
+ * @param   strTaskDesc         Friendly task description.
+ */
 HRESULT GuestSessionTaskCopyFrom::Init(const Utf8Str &strTaskDesc)
 {
@@ -1544 +1576 @@
 }
 
+/** @copydoc GuestSessionTask::Run */
 int GuestSessionTaskCopyFrom::Run(void)
 {
@@ -1676 +1709 @@
 }
 
+/**
+ * Initializes a copy-to-guest task.
+ *
+ * @returns HRESULT
+ * @param   strTaskDesc         Friendly task description.
+ */
 HRESULT GuestSessionTaskCopyTo::Init(const Utf8Str &strTaskDesc)
 {
@@ -1813 +1852 @@
 }
 
+/** @copydoc GuestSessionTask::Run */
 int GuestSessionTaskCopyTo::Run(void)
 {
@@ -2064 +2104 @@
 }
 
+/**
+ * Adds arguments to existing process arguments.
+ * Identical / already existing arguments will be filtered out.
+ *
+ * @returns VBox status code.
+ * @param   aArgumentsDest      Destination to add arguments to.
+ * @param   aArgumentsSource    Arguments to add.
+ */
 int GuestSessionTaskUpdateAdditions::addProcessArguments(ProcessArguments &aArgumentsDest, const ProcessArguments &aArgumentsSource)
 {
@@ -2102 +2150 @@
 }
 
+/**
+ * Helper function to copy a file from a VISO to the guest.
+ *
+ * @returns VBox status code.
+ * @param   pSession            Guest session to use.
+ * @param   hVfsIso             VISO handle to use.
+ * @param   strFileSrc          Source file path on VISO to copy.
+ * @param   strFileDst          Destination file path on guest.
+ * @param   fOptional           When set to \c true, the file is optional, i.e. can be skipped
+ *                              when not found, \c false if not.
+ */
 int GuestSessionTaskUpdateAdditions::copyFileToGuest(GuestSession *pSession, RTVFS hVfsIso,
                                                      Utf8Str const &strFileSrc, const Utf8Str &strFileDst, bool fOptional)
@@ -2160 +2219 @@
 }
 
+/**
+ * Helper function to run (start) a file on the guest.
+ *
+ * @returns VBox status code.
+ * @param   pSession            Guest session to use.
+ * @param   procInfo            Guest process startup info to use.
+ */
 int GuestSessionTaskUpdateAdditions::runFileOnGuest(GuestSession *pSession, GuestProcessStartupInfo &procInfo)
 {
@@ -2209 +2275 @@
 }
 
+/** @copydoc GuestSessionTask::Run */
 int GuestSessionTaskUpdateAdditions::Run(void)
 {