VirtualBox

Changeset 92897 in vbox


Ignore:
Timestamp:
Dec 14, 2021 1:53:27 PM (3 years ago)
Author:
vboxsync
Message:

Guest Control/Main: Added lots of missing docs.

Location:
trunk/src/VBox/Main
Files:
8 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/VBox/Main/include/GuestProcessImpl.h

    r91312 r92897  
    55
    66/*
    7  * Copyright (C) 2012-2020 Oracle Corporation
     7 * Copyright (C) 2012-2021 Oracle Corporation
    88 *
    99 * This file is part of VirtualBox Open Source Edition (OSE), as
    … …  
    213213 * This class essentially helps to wrap all the gory details like process creation,
    214214 * information extraction and maintaining the overall status.
     215 *
     216 * Note! When implementing new functionality / commands, do *not* use this approach anymore!
     217 *       This class has to be kept to guarantee backwards-compatibility.
    215218 */
    216219class GuestProcessTool
    … …  
    233236    int getRc(void) const;
    234237
     238    /** Returns the stdout output from the guest process tool. */
    235239    GuestProcessStream &getStdOut(void) { return mStdOut; }
    236240
     241    /** Returns the stderr output from the guest process tool. */
    237242    GuestProcessStream &getStdErr(void) { return mStdErr; }
    238243

  • trunk/src/VBox/Main/include/GuestSessionImplTasks.h

    r92822 r92897  
    55
    66/*
    7  * Copyright (C) 2018-2020 Oracle Corporation
     7 * Copyright (C) 2018-2021 Oracle Corporation
    88 *
    99 * This file is part of VirtualBox Open Source Edition (OSE), as
    … …  
    162162public:
    163163
     164    /**
     165     * Function which implements the actual task to perform.
     166     *
     167     * @returns VBox status code.
     168     */
    164169    virtual int Run(void) = 0;
     170
    165171    void handler()
    166172    {
    … …  
    186192    }
    187193
     194    /** Returns the task's progress object. */
    188195    const ComObjPtr<Progress>& GetProgressObject(void) const { return mProgress; }
    189196
     197    /** Returns the task's guest session object. */
    190198    const ComObjPtr<GuestSession>& GetSession(void) const { return mSession; }
    191199

  • trunk/src/VBox/Main/src-client/GuestDirectoryImpl.cpp

    r91518 r92897  
    55
    66/*
    7  * Copyright (C) 2012-2020 Oracle Corporation
     7 * Copyright (C) 2012-2021 Oracle Corporation
    88 *
    99 * This file is part of VirtualBox Open Source Edition (OSE), as
    … …  
    181181/////////////////////////////////////////////////////////////////////////////
    182182
     183/**
     184 * Entry point for guest side directory callbacks.
     185 *
     186 * @returns VBox status code.
     187 * @param   pCbCtx              Host callback context.
     188 * @param   pSvcCb              Host callback data.
     189 */
    183190int GuestDirectory::i_callbackDispatcher(PVBOXGUESTCTRLHOSTCBCTX pCbCtx, PVBOXGUESTCTRLHOSTCALLBACK pSvcCb)
    184191{

  • trunk/src/VBox/Main/src-client/GuestFileImpl.cpp

    r91718 r92897  
    55
    66/*
    7  * Copyright (C) 2012-2020 Oracle Corporation
     7 * Copyright (C) 2012-2021 Oracle Corporation
    88 *
    99 * This file is part of VirtualBox Open Source Edition (OSE), as
    … …  
    101101private:
    102102
     103    /** Weak pointer to the guest file object to listen for. */
    103104    GuestFile *mFile;
    104105};
    … …  
    334335/////////////////////////////////////////////////////////////////////////////
    335336
     337/**
     338 * Entry point for guest side file callbacks.
     339 *
     340 * @returns VBox status code.
     341 * @param   pCbCtx              Host callback context.
     342 * @param   pSvcCbData          Host callback data.
     343 */
    336344int GuestFile::i_callbackDispatcher(PVBOXGUESTCTRLHOSTCBCTX pCbCtx, PVBOXGUESTCTRLHOSTCALLBACK pSvcCb)
    337345{
    … …  
    365373}
    366374
     375/**
     376 * Closes the file on the guest side.
     377 *
     378 * @returns VBox status code.
     379 * @retval  VERR_GSTCTL_GUEST_ERROR when an error from the guest side has been received.
     380 * @param   prcGuest            Where to return the guest error when VERR_GSTCTL_GUEST_ERROR
     381 *                              was returned.
     382 */
    367383int GuestFile::i_closeFile(int *prcGuest)
    368384{
    … …  
    434450}
    435451
     452/**
     453 * Called when the guest side notifies the host of a file event.
     454 *
     455 * @returns VBox status code.
     456 * @param   pCbCtx              Host callback context.
     457 * @param   pSvcCbData          Host callback data.
     458 */
    436459int GuestFile::i_onFileNotify(PVBOXGUESTCTRLHOSTCBCTX pCbCtx, PVBOXGUESTCTRLHOSTCALLBACK pSvcCbData)
    437460{
    … …  
    671694}
    672695
     696/**
     697 * Called when the guest side of the file has been disconnected (closed, terminated, +++).
     698 *
     699 * @returns VBox status code.
     700 * @param   pCbCtx              Host callback context.
     701 * @param   pSvcCbData          Host callback data.
     702 */
    673703int GuestFile::i_onGuestDisconnected(PVBOXGUESTCTRLHOSTCBCTX pCbCtx, PVBOXGUESTCTRLHOSTCALLBACK pSvcCbData)
    674704{
    … …  
    727757}
    728758
     759/**
     760 * Opens the file on the guest.
     761 *
     762 * @returns VBox status code.
     763 * @retval  VERR_GSTCTL_GUEST_ERROR when an error from the guest side has been received.
     764 * @param   uTimeoutMS          Timeout (in ms) to wait.
     765 * @param   prcGuest            Where to return the guest error when VERR_GSTCTL_GUEST_ERROR
     766 *                              was returned. Optional.
     767 */
    729768int GuestFile::i_openFile(uint32_t uTimeoutMS, int *prcGuest)
    730769{
    … …  
    824863}
    825864
     865/**
     866 * Queries file system information from a guest file.
     867 *
     868 * @returns VBox status code.
     869 * @retval  VERR_GSTCTL_GUEST_ERROR when an error from the guest side has been received.
     870 * @param   objData             Where to store the file system object data on success.
     871 * @param   prcGuest            Where to return the guest error when VERR_GSTCTL_GUEST_ERROR
     872 *                              was returned. Optional.
     873 */
    826874int GuestFile::i_queryInfo(GuestFsObjData &objData, int *prcGuest)
    827875{
    … …  
    830878}
    831879
     880/**
     881 * Reads data from a guest file.
     882 *
     883 * @returns VBox status code.
     884 * @retval  VERR_GSTCTL_GUEST_ERROR when an error from the guest side has been received.
     885 * @param   uOffset             Offset (in bytes) to start reading from.
     886 * @param   uSize               Size (in bytes) to read.
     887 * @param   uTimeoutMS          Timeout (in ms) to wait.
     888 * @param   pvData              Where to store the read data on success.
     889 * @param   cbData              Size (in bytes) of \a pvData on input.
     890 * @param   pcbRead             Where to return to size (in bytes) read on success.
     891 *                              Optional.
     892 */
    832893int GuestFile::i_readData(uint32_t uSize, uint32_t uTimeoutMS,
    833894                          void* pvData, uint32_t cbData, uint32_t* pcbRead)
    … …  
    892953}
    893954
     955/**
     956 * Reads data from a specific position from a guest file.
     957 *
     958 * @returns VBox status code.
     959 * @retval  VERR_GSTCTL_GUEST_ERROR when an error from the guest side has been received.
     960 * @param   uOffset             Offset (in bytes) to start reading from.
     961 * @param   uSize               Size (in bytes) to read.
     962 * @param   uTimeoutMS          Timeout (in ms) to wait.
     963 * @param   pvData              Where to store the read data on success.
     964 * @param   cbData              Size (in bytes) of \a pvData on input.
     965 * @param   pcbRead             Where to return to size (in bytes) read on success.
     966 *                              Optional.
     967 */
    894968int GuestFile::i_readDataAt(uint64_t uOffset, uint32_t uSize, uint32_t uTimeoutMS,
    895969                            void* pvData, size_t cbData, size_t* pcbRead)
    … …  
    9531027}
    9541028
     1029/**
     1030 * Seeks a guest file to a specific position.
     1031 *
     1032 * @returns VBox status code.
     1033 * @retval  VERR_GSTCTL_GUEST_ERROR when an error from the guest side has been received.
     1034 * @param   iOffset             Offset (in bytes) to seek.
     1035 * @param   eSeekType           Seek type to use.
     1036 * @param   uTimeoutMS          Timeout (in ms) to wait.
     1037 * @param   puOffset            Where to return the new current file position (in bytes) on success.
     1038 */
    9551039int GuestFile::i_seekAt(int64_t iOffset, GUEST_FILE_SEEKTYPE eSeekType,
    9561040                        uint32_t uTimeoutMS, uint64_t *puOffset)
    … …  
    10151099}
    10161100
     1101/**
     1102 * Sets the current internal file object status.
     1103 *
     1104 * @returns VBox status code.
     1105 * @param   fileStatus          New file status to set.
     1106 * @param   fileRc              New result code to set.
     1107 *
     1108 * @note    Takes the write lock.
     1109 */
    10171110int GuestFile::i_setFileStatus(FileStatus_T fileStatus, int fileRc)
    10181111{
    … …  
    10571150}
    10581151
     1152/**
     1153 * Waits for a guest file offset change.
     1154 *
     1155 * @returns VBox status code.
     1156 * @retval  VERR_GSTCTL_GUEST_ERROR when an error from the guest side has been received.
     1157 * @param   pEvent              Guest wait event to wait for.
     1158 * @param   uTimeoutMS          Timeout (in ms) to wait.
     1159 * @param   puOffset            Where to return the new offset (in bytes) on success.
     1160 *                              Optional and can be NULL.
     1161 */
    10591162int GuestFile::i_waitForOffsetChange(GuestWaitEvent *pEvent,
    10601163                                     uint32_t uTimeoutMS, uint64_t *puOffset)
    … …  
    10861189}
    10871190
     1191/**
     1192 * Waits for reading from a guest file.
     1193 *
     1194 * @returns VBox status code.
     1195 * @retval  VERR_GSTCTL_GUEST_ERROR when an error from the guest side has been received.
     1196 * @param   pEvent              Guest wait event to wait for.
     1197 * @param   uTimeoutMS          Timeout (in ms) to wait.
     1198 * @param   pvData              Where to store read file data on success.
     1199 * @param   cbData              Size (in bytes) of \a pvData.
     1200 * @param   pcbRead             Where to return the actual bytes read on success.
     1201 *                              Optional and can be NULL.
     1202 */
    10881203int GuestFile::i_waitForRead(GuestWaitEvent *pEvent, uint32_t uTimeoutMS,
    10891204                             void *pvData, size_t cbData, uint32_t *pcbRead)
    … …  
    11401255
    11411256/**
    1142  * Undocumented, use with great care.
     1257 * Waits for a guest file status change.
    11431258 *
    11441259 * @note Similar code in GuestProcess::i_waitForStatusChange() and
    11451260 *       GuestSession::i_waitForStatusChange().
     1261 *
     1262 * @returns VBox status code.
     1263 * @retval  VERR_GSTCTL_GUEST_ERROR when an error from the guest side has been received.
     1264 * @param   pEvent              Guest wait event to wait for.
     1265 * @param   uTimeoutMS          Timeout (in ms) to wait.
     1266 * @param   pFileStatus         Where to return the file status on success.
     1267 * @param   prcGuest            Where to return the guest error when VERR_GSTCTL_GUEST_ERROR
     1268 *                              was returned.
    11461269 */
    11471270int GuestFile::i_waitForStatusChange(GuestWaitEvent *pEvent, uint32_t uTimeoutMS,
    … …  
    12301353}
    12311354
     1355/**
     1356 * Writes data to a guest file.
     1357 *
     1358 * @returns VBox status code.
     1359 * @retval  VERR_GSTCTL_GUEST_ERROR when an error from the guest side has been received.
     1360 * @param   uTimeoutMS          Timeout (in ms) to wait.
     1361 * @param   pvData              Data to write.
     1362 * @param   cbData              Size (in bytes) of \a pvData to write.
     1363 * @param   pcbWritten          Where to return to size (in bytes) written on success.
     1364 *                              Optional.
     1365 */
    12321366int GuestFile::i_writeData(uint32_t uTimeoutMS, const void *pvData, uint32_t cbData,
    12331367                           uint32_t *pcbWritten)
    … …  
    12931427}
    12941428
     1429
     1430/**
     1431 * Writes data to a specific position to a guest file.
     1432 *
     1433 * @returns VBox status code.
     1434 * @retval  VERR_GSTCTL_GUEST_ERROR when an error from the guest side has been received.
     1435 * @param   uOffset             Offset (in bytes) to start writing at.
     1436 * @param   uTimeoutMS          Timeout (in ms) to wait.
     1437 * @param   pvData              Data to write.
     1438 * @param   cbData              Size (in bytes) of \a pvData to write.
     1439 * @param   pcbWritten          Where to return to size (in bytes) written on success.
     1440 *                              Optional.
     1441 */
    12951442int GuestFile::i_writeDataAt(uint64_t uOffset, uint32_t uTimeoutMS,
    12961443                             const void *pvData, uint32_t cbData, uint32_t *pcbWritten)

  • trunk/src/VBox/Main/src-client/GuestFsObjInfoImpl.cpp

    r82968 r92897  
    55
    66/*
    7  * Copyright (C) 2012-2020 Oracle Corporation
     7 * Copyright (C) 2012-2021 Oracle Corporation
    88 *
    99 * This file is part of VirtualBox Open Source Edition (OSE), as

  • trunk/src/VBox/Main/src-client/GuestProcessImpl.cpp

    r92707 r92897  
    55
    66/*
    7  * Copyright (C) 2012-2020 Oracle Corporation
     7 * Copyright (C) 2012-2021 Oracle Corporation
    88 *
    99 * This file is part of VirtualBox Open Source Edition (OSE), as
    … …  
    5858
    5959
     60/**
     61 * Base class for all guest process tasks.
     62 */
    6063class GuestProcessTask : public ThreadTask
    6164{
    … …  
    6972    virtual ~GuestProcessTask(void) { }
    7073
     74    /** Returns the last set result code. */
    7175    int i_rc(void) const { return mRC; }
     76    /** Returns whether the last set result is okay (successful) or not. */
    7277    bool i_isOk(void) const { return RT_SUCCESS(mRC); }
     78    /** Returns the reference of the belonging progress object. */
    7379    const ComObjPtr<GuestProcess> &i_process(void) const { return mProcess; }
    7480
    7581protected:
    7682
     83    /** Progress object this process belongs to. */
    7784    const ComObjPtr<GuestProcess>    mProcess;
     85    /** Last set result code. */
    7886    int                              mRC;
    7987};
    8088
     89/**
     90 * Task to start a process on the guest.
     91 */
    8192class GuestProcessStartTask : public GuestProcessTask
    8293{
    … …  
    179190/////////////////////////////////////////////////////////////////////////////
    180191
     192/**
     193 * Initialies a guest process object.
     194 *
     195 * @returns VBox status code.
     196 * @param   aConsole            Console this process is bound to.
     197 * @param   aSession            Guest session this process is bound to.
     198 * @param   aObjectID           Object ID to use for this process object.
     199 * @param   aProcInfo           Process startup information to use.
     200 * @param   pBaseEnv            Guest environment to apply when starting the process on the guest.
     201 */
    181202int GuestProcess::init(Console *aConsole, GuestSession *aSession, ULONG aObjectID,
    182203                       const GuestProcessStartupInfo &aProcInfo, const GuestEnvironment *pBaseEnv)
    … …  
    405426/////////////////////////////////////////////////////////////////////////////
    406427
     428/**
     429 * Entry point for guest side process callbacks.
     430 *
     431 * @returns VBox status code.
     432 * @param   pCbCtx              Host callback context.
     433 * @param   pSvcCb              Host callback data.
     434 */
    407435int GuestProcess::i_callbackDispatcher(PVBOXGUESTCTRLHOSTCBCTX pCbCtx, PVBOXGUESTCTRLHOSTCALLBACK pSvcCb)
    408436{
    … …  
    540568}
    541569
     570/**
     571 * Returns whether the guest process is alive (i.e. running) or not.
     572 *
     573 * @returns \c true if alive and running, or \c false if not.
     574 */
    542575inline bool GuestProcess::i_isAlive(void)
    543576{
    … …  
    547580}
    548581
     582/**
     583 * Returns whether the guest process has ended (i.e. terminated) or not.
     584 *
     585 * @returns \c true if ended, or \c false if not.
     586 */
    549587inline bool GuestProcess::i_hasEnded(void)
    550588{
    … …  
    558596}
    559597
     598/**
     599 * Called when the guest side of the process has been disconnected (closed, terminated, +++).
     600 *
     601 * @returns VBox status code.
     602 * @param   pCbCtx              Host callback context.
     603 * @param   pSvcCbData          Host callback data.
     604 */
    560605int GuestProcess::i_onGuestDisconnected(PVBOXGUESTCTRLHOSTCBCTX pCbCtx, PVBOXGUESTCTRLHOSTCALLBACK pSvcCbData)
    561606{
    … …  
    569614}
    570615
     616/**
     617 * Sets (reports) the current input status of the guest process.
     618 *
     619 * @returns VBox status code.
     620 * @param   pCbCtx              Host callback context.
     621 * @param   pSvcCbData          Host callback data.
     622 *
     623 * @note    Takes the write lock.
     624 */
    571625int GuestProcess::i_onProcessInputStatus(PVBOXGUESTCTRLHOSTCBCTX pCbCtx, PVBOXGUESTCTRLHOSTCALLBACK pSvcCbData)
    572626{
    … …  
    635689}
    636690
     691/**
     692 * Notifies of an I/O operation of the guest process.
     693 *
     694 * @returns VERR_NOT_IMPLEMENTED -- not implemented yet.
     695 * @param   pCbCtx              Host callback context.
     696 * @param   pSvcCbData          Host callback data.
     697 */
    637698int GuestProcess::i_onProcessNotifyIO(PVBOXGUESTCTRLHOSTCBCTX pCbCtx, PVBOXGUESTCTRLHOSTCALLBACK pSvcCbData)
    638699{
    … …  
    643704}
    644705
     706/**
     707 * Sets (reports) the current running status of the guest process.
     708 *
     709 * @returns VBox status code.
     710 * @param   pCbCtx              Host callback context.
     711 * @param   pSvcCbData          Host callback data.
     712 *
     713 * @note    Takes the write lock.
     714 */
    645715int GuestProcess::i_onProcessStatusChange(PVBOXGUESTCTRLHOSTCBCTX pCbCtx, PVBOXGUESTCTRLHOSTCALLBACK pSvcCbData)
    646716{
    … …  
    753823}
    754824
     825/**
     826 * Sets (reports) the current output status of the guest process.
     827 *
     828 * @returns VBox status code.
     829 * @param   pCbCtx              Host callback context.
     830 * @param   pSvcCbData          Host callback data.
     831 */
    755832int GuestProcess::i_onProcessOutput(PVBOXGUESTCTRLHOSTCBCTX pCbCtx, PVBOXGUESTCTRLHOSTCALLBACK pSvcCbData)
    756833{
    … …  
    839916}
    840917
     918/**
     919 * Reads data from a guest file.
     920 *
     921 * @returns VBox status code.
     922 * @retval  VERR_GSTCTL_GUEST_ERROR when an error from the guest side has been received.
     923 * @param   uHandle             Internal file handle to use for reading.
     924 * @param   uSize               Size (in bytes) to read.
     925 * @param   uTimeoutMS          Timeout (in ms) to wait.
     926 * @param   pvData              Where to store the read data on success.
     927 * @param   cbData              Size (in bytes) of \a pvData on input.
     928 * @param   pcbRead             Where to return to size (in bytes) read on success.
     929 *                              Optional.
     930 * @param   prcGuest            Where to return the guest error when VERR_GSTCTL_GUEST_ERROR
     931 *                              was returned. Optional.
     932 *
     933 * @note    Takes the write lock.
     934 */
    841935int GuestProcess::i_readData(uint32_t uHandle, uint32_t uSize, uint32_t uTimeoutMS,
    842936                             void *pvData, size_t cbData, uint32_t *pcbRead, int *prcGuest)
    … …  
    9191013}
    9201014
    921 /* Does not do locking; caller is responsible for that! */
     1015/**
     1016 * Sets (reports) the current (overall) status of the guest process.
     1017 *
     1018 * @returns VBox status code.
     1019 * @param   procStatus          Guest process status to set.
     1020 * @param   pSvcCbData          Guest process result code to set.
     1021 *
     1022 * @note    Takes the write lock.
     1023 */
    9221024int GuestProcess::i_setProcessStatus(ProcessStatus_T procStatus, int procRc)
    9231025{
    … …  
    9831085}
    9841086
     1087/**
     1088 * Starts the process on the guest.
     1089 *
     1090 * @returns VBox status code.
     1091 * @param   cMsTimeout          Timeout (in ms) to wait for starting the process.
     1092 * @param   prcGuest            Where to return the guest error when VERR_GSTCTL_GUEST_ERROR
     1093 *                              was returned. Optional.
     1094 *
     1095 * @note    Takes the write lock.
     1096 */
    9851097int GuestProcess::i_startProcess(uint32_t cMsTimeout, int *prcGuest)
    9861098{
    … …  
    10191131}
    10201132
     1133/**
     1134 * Helper function to start a process on the guest. Do not call directly!
     1135 *
     1136 * @returns VBox status code.
     1137 * @param   cMsTimeout          Timeout (in ms) to wait for starting the process.
     1138 * @param   rLock               Write lock to use for serialization.
     1139 * @param   pEvent              Event to use for notifying waiters.
     1140 * @param   prcGuest            Where to return the guest error when VERR_GSTCTL_GUEST_ERROR
     1141 *                              was returned. Optional.
     1142 */
    10211143int GuestProcess::i_startProcessInner(uint32_t cMsTimeout, AutoWriteLock &rLock, GuestWaitEvent *pEvent, int *prcGuest)
    10221144{
    … …  
    11381260}
    11391261
     1262/**
     1263 * Starts the process asynchronously (via worker thread) on the guest.
     1264 *
     1265 * @returns VBox status code.
     1266 */
    11401267int GuestProcess::i_startProcessAsync(void)
    11411268{
    … …  
    11651292}
    11661293
     1294/**
     1295 * Thread task which does the asynchronous starting of a guest process.
     1296 *
     1297 * @returns VBox status code.
     1298 * @param   pTask               Process start task (context) to process.
     1299 */
    11671300/* static */
    11681301int GuestProcess::i_startProcessThreadTask(GuestProcessStartTask *pTask)
    … …  
    11841317}
    11851318
     1319/**
     1320 * Terminates a guest process.
     1321 *
     1322 * @returns VBox status code.
     1323 * @param   uTimeoutMS          Timeout (in ms) to wait for process termination.
     1324 * @param   prcGuest            Where to return the guest error when VERR_GSTCTL_GUEST_ERROR
     1325 *                              was returned. Optional.
     1326 *
     1327 * @note    Takes the write lock.
     1328 */
    11861329int GuestProcess::i_terminateProcess(uint32_t uTimeoutMS, int *prcGuest)
    11871330{
    … …  
    12431386}
    12441387
     1388/**
     1389 * Converts given process status / flags and wait flag combination
     1390 * to an overall process wait result.
     1391 *
     1392 * @returns  Overall process wait result.
     1393 * @param   fWaitFlags          Process wait flags to use for conversion.
     1394 * @param   oldStatus           Old process status to use for conversion.
     1395 * @param   newStatus           New process status to use for conversion.
     1396 * @param   uProcFlags          Process flags to use for conversion.
     1397 * @param   uProtocol           Guest Control protocol version to use for conversion.
     1398 */
    12451399/* static */
    12461400ProcessWaitResult_T GuestProcess::i_waitFlagsToResultEx(uint32_t fWaitFlags,
    … …  
    13501504}
    13511505
     1506/**
     1507 * Converts given wait flags to an overall process wait result.
     1508 *
     1509 * @returns Overall process wait result.
     1510 * @param   fWaitFlags          Process wait flags to use for conversion.
     1511 */
    13521512ProcessWaitResult_T GuestProcess::i_waitFlagsToResult(uint32_t fWaitFlags)
    13531513{
    … …  
    13581518}
    13591519
     1520/**
     1521 * Waits for certain events of the guest process.
     1522 *
     1523 * @returns VBox status code.
     1524 * @param   fWaitFlags          Process wait flags to wait for.
     1525 * @param   uTimeoutMS          Timeout (in ms) to wait.
     1526 * @param   waitResult          Where to return the process wait result on success.
     1527 * @param   prcGuest            Where to return the guest error when VERR_GSTCTL_GUEST_ERROR
     1528 *                              was returned. Optional.
     1529 * @note    Takes the read lock.
     1530 */
    13601531int GuestProcess::i_waitFor(uint32_t fWaitFlags, ULONG uTimeoutMS,
    13611532                            ProcessWaitResult_T &waitResult, int *prcGuest)
    … …  
    14611632}
    14621633
     1634/**
     1635 * Waits for a guest process input notification.
     1636 *
     1637 * @param   pEvent              Wait event to use for waiting.
     1638 * @param   uHandle             Guest process file handle to wait for.
     1639 * @param   uTimeoutMS          Timeout (in ms) to wait.
     1640 * @param   pInputStatus        Where to return the process input status on success.
     1641 * @param   pcbProcessed        Where to return the processed input (in bytes) on success.
     1642 */
    14631643int GuestProcess::i_waitForInputNotify(GuestWaitEvent *pEvent, uint32_t uHandle, uint32_t uTimeoutMS,
    14641644                                       ProcessInputStatus_T *pInputStatus, uint32_t *pcbProcessed)
    … …  
    14981678}
    14991679
     1680/**
     1681 * Waits for a guest process input notification.
     1682 *
     1683 * @returns VBox status code.
     1684 * @param   pEvent              Wait event to use for waiting.
     1685 * @param   uHandle             Guest process file handle to wait for.
     1686 * @param   uTimeoutMS          Timeout (in ms) to wait.
     1687 * @param   pvData              Where to store the guest process output on success.
     1688 * @param   cbData              Size (in bytes) of \a pvData.
     1689 * @param   pcbRead             Where to return the size (in bytes) read.
     1690 */
    15001691int GuestProcess::i_waitForOutput(GuestWaitEvent *pEvent, uint32_t uHandle, uint32_t uTimeoutMS,
    15011692                                  void *pvData, size_t cbData, uint32_t *pcbRead)
    … …  
    15811772
    15821773/**
    1583  * Undocumented, you guess what it does.
    1584  *
    1585  * @note Similar code in GuestFile::i_waitForStatusChange() and
    1586  *       GuestSession::i_waitForStatusChange().
     1774 * Waits for a guest process status change.
     1775 *
     1776 * @returns VBox status code.
     1777 * @retval  VERR_GSTCTL_GUEST_ERROR when an error from the guest side has been received.
     1778 * @param   pEvent              Guest wait event to wait for.
     1779 * @param   uTimeoutMS          Timeout (in ms) to wait.
     1780 * @param   pProcessStatus      Where to return the process status on success.
     1781 * @param   prcGuest            Where to return the guest error when VERR_GSTCTL_GUEST_ERROR
     1782 *                              was returned.
    15871783 */
    15881784int GuestProcess::i_waitForStatusChange(GuestWaitEvent *pEvent, uint32_t uTimeoutMS,
    … …  
    16681864#endif /* unused */
    16691865
     1866/**
     1867 * Writes input data to a guest process.
     1868 *
     1869 * @returns VBox status code.
     1870 * @retval  VERR_GSTCTL_GUEST_ERROR when an error from the guest side has been received.
     1871 * @param   uHandle             Guest process file handle to write to.
     1872 * @param   uFlags              Input flags of type PRocessInputFlag_XXX.
     1873 * @param   pvData              Data to write to the guest process.
     1874 * @param   cbData              Size (in bytes) of \a pvData to write.
     1875 * @param   uTimeoutMS          Timeout (in ms) to wait.
     1876 * @param   puWritten           Where to return the size (in bytes) written. Optional.
     1877 * @param   prcGuest            Where to return the guest error when VERR_GSTCTL_GUEST_ERROR
     1878 *                              was returned. Optional.
     1879 *
     1880 * @note    Takes the write lock.
     1881 */
    16701882int GuestProcess::i_writeData(uint32_t uHandle, uint32_t uFlags,
    16711883                              void *pvData, size_t cbData, uint32_t uTimeoutMS, uint32_t *puWritten, int *prcGuest)
    … …  
    19782190}
    19792191
     2192/**
     2193 * Initializes and starts a process tool on the guest.
     2194 *
     2195 * @returns VBox status code.
     2196 * @param   pGuestSession       Guest session the process tools should be started in.
     2197 * @param   startupInfo         Guest process startup info to use for starting.
     2198 * @param   fAsync              Whether to start asynchronously or not.
     2199 * @param   prcGuest            Where to return the guest error when VERR_GSTCTL_GUEST_ERROR
     2200 *                              was returned. Optional.
     2201 */
    19802202int GuestProcessTool::init(GuestSession *pGuestSession, const GuestProcessStartupInfo &startupInfo,
    19812203                           bool fAsync, int *prcGuest)
    … …  
    20172239}
    20182240
     2241/**
     2242 * Unitializes a guest process tool by terminating it on the guest.
     2243 */
    20192244void GuestProcessTool::uninit(void)
    20202245{
    … …  
    20332258}
    20342259
     2260/**
     2261 * Gets the current guest process stream block.
     2262 *
     2263 * @returns VBox status code.
     2264 * @param   uHandle             Guest process file handle to get current block for.
     2265 * @param   strmBlock           Where to return the stream block on success.
     2266 */
    20352267int GuestProcessTool::getCurrentBlock(uint32_t uHandle, GuestProcessStreamBlock &strmBlock)
    20362268{
    … …  
    20442276        return VERR_INVALID_PARAMETER;
    20452277
     2278    /** @todo Why not using pStream down below and hardcode to mStdOut? */
     2279
    20462280    int vrc;
    20472281    do
    … …  
    20582292}
    20592293
     2294/**
     2295 * Returns the result code from an ended guest process tool.
     2296 *
     2297 * @returns Result code from guest process tool.
     2298 */
    20602299int GuestProcessTool::getRc(void) const
    20612300{
    … …  
    20672306}
    20682307
     2308/**
     2309 * Returns whether a guest process tool is still running or not.
     2310 *
     2311 * @returns \c true if running, or \c false if not.
     2312 */
    20692313bool GuestProcessTool::isRunning(void)
    20702314{
    … …  
    22982542}
    22992543
     2544/**
     2545 * Waits for a guest process tool.
     2546 *
     2547 * @returns VBox status code.
     2548 * @param   fToolWaitFlags      Guest process tool wait flags to use for waiting.
     2549 * @param   prcGuest            Where to return the guest error when VERR_GSTCTL_GUEST_ERROR
     2550 *                              was returned. Optional.
     2551 */
    23002552int GuestProcessTool::wait(uint32_t fToolWaitFlags, int *prcGuest)
    23012553{
    … …  
    23032555}
    23042556
     2557/**
     2558 * Waits for a guest process tool, also returning process output.
     2559 *
     2560 * @returns VBox status code.
     2561 * @param   fToolWaitFlags      Guest process tool wait flags to use for waiting.
     2562 * @param   pStrmBlkOut         Where to store the guest process output.
     2563 * @param   prcGuest            Where to return the guest error when VERR_GSTCTL_GUEST_ERROR
     2564 *                              was returned. Optional.
     2565 */
    23052566int GuestProcessTool::waitEx(uint32_t fToolWaitFlags, GuestProcessStreamBlock *pStrmBlkOut, int *prcGuest)
    23062567{
    … …  
    24902751}
    24912752
     2753/**
     2754 * Terminates a guest process tool.
     2755 *
     2756 * @returns VBox status code.
     2757 * @param   uTimeoutMS          Timeout (in ms) to wait.
     2758 * @param   prcGuest            Where to return the guest error when VERR_GSTCTL_GUEST_ERROR
     2759 *                              was returned. Optional.
     2760 */
    24922761int GuestProcessTool::terminate(uint32_t uTimeoutMS, int *prcGuest)
    24932762{
    … …  
    25072776 * Converts a toolbox tool's exit code to an IPRT error code.
    25082777 *
    2509  * @return  int         Returned IPRT error for the particular tool.
    2510  * @param   startupInfo Startup info of the toolbox tool to lookup error code for.
    2511  * @param   iExitCode   The toolbox tool's exit code to lookup IPRT error for.
     2778 * @returns VBox status code.
     2779 * @param   startupInfo         Startup info of the toolbox tool to lookup error code for.
     2780 * @param   iExitCode           The toolbox tool's exit code to lookup IPRT error for.
    25122781 */
    25132782/* static */
    … …  
    25262795 * Converts a toolbox tool's exit code to an IPRT error code.
    25272796 *
    2528  * @return  Returned IPRT error for the particular tool.
    2529  * @param   pszTool     Name of toolbox tool to lookup error code for.
    2530  * @param   iExitCode   The toolbox tool's exit code to lookup IPRT error for.
     2797 * @returns VBox status code.
     2798 * @param   pszTool             Name of toolbox tool to lookup error code for.
     2799 * @param   iExitCode           The toolbox tool's exit code to lookup IPRT error for.
    25312800 */
    25322801/* static */
    … …  
    26052874}
    26062875
     2876/**
     2877 * Returns a stringyfied error of a guest process tool error.
     2878 *
     2879 * @returns Stringyfied error.
     2880 * @param   pszTool             Toolbox tool name to get stringyfied error for.
     2881 * @param   guestErrorInfo      Guest error info to get stringyfied error for.
     2882 */
    26072883/* static */
    26082884Utf8Str GuestProcessTool::guestErrorToString(const char *pszTool, const GuestErrorInfo &guestErrorInfo)

  • trunk/src/VBox/Main/src-client/GuestSessionImpl.cpp

    r92880 r92897  
    55
    66/*
    7  * Copyright (C) 2012-2020 Oracle Corporation
     7 * Copyright (C) 2012-2021 Oracle Corporation
    88 *
    99 * This file is part of VirtualBox Open Source Edition (OSE), as
    … …  
    6868    virtual ~GuestSessionTaskInternal(void) { }
    6969
     70    /** Returns the last set result code. */
    7071    int rc(void) const { return mRC; }
     72    /** Returns whether the last set result code indicates success or not. */
    7173    bool isOk(void) const { return RT_SUCCESS(mRC); }
     74    /** Returns the task's guest session object. */
    7275    const ComObjPtr<GuestSession> &Session(void) const { return mSession; }
    7376
    7477protected:
    7578
     79    /** Guest session the task belongs to. */
    7680    const ComObjPtr<GuestSession>    mSession;
     81    /** The last set result code. */
    7782    int                              mRC;
    7883};
    … …  
    183188 * yet. This needs to be done via the openSession() / openSessionAsync calls.
    184189 *
    185  * @return  IPRT status code.
    186  ** @todo Docs!
     190 * @returns VBox status code.
     191 * @param   pGuest              Guest object the guest session belongs to.
     192 * @param   ssInfo              Guest session startup info to use.
     193 * @param   guestCreds          Guest credentials to use for starting a guest session
     194 *                              with a specific guest account.
    187195 */
    188196int GuestSession::init(Guest *pGuest, const GuestSessionStartupInfo &ssInfo,
    … …  
    649657///////////////////////////////////////////////////////////////////////////////
    650658
     659/**
     660 * Closes a guest session on the guest.
     661 *
     662 * @returns VBox status code.
     663 * @param   uFlags              Guest session close flags.
     664 * @param   uTimeoutMS          Timeout (in ms) to wait.
     665 * @param   prcGuest            Where to return the guest error when VERR_GSTCTL_GUEST_ERROR
     666 *                              was returned. Optional.
     667 *
     668 * @note    Takes the write lock.
     669 */
    651670int GuestSession::i_closeSession(uint32_t uFlags, uint32_t uTimeoutMS, int *prcGuest)
    652671{
    … …  
    888907}
    889908
     909/**
     910 * Creates a directory on the guest.
     911 *
     912 * @returns VBox status code.
     913 * @param   strPath             Path on guest to directory to create.
     914 * @param   uMode               Creation mode to use (octal, 0777 max).
     915 * @param   uFlags              Directory creation flags to use.
     916 * @param   prcGuest            Where to return the guest error when VERR_GSTCTL_GUEST_ERROR
     917 *                              was returned. Optional.
     918 */
    890919int GuestSession::i_directoryCreate(const Utf8Str &strPath, uint32_t uMode,
    891920                                    uint32_t uFlags, int *prcGuest)
    … …  
    958987}
    959988
     989/**
     990 * Checks if a directory object exists and optionally returns its object.
     991 *
     992 * @returns \c true if directory object exists, or \c false if not.
     993 * @param   uDirID              ID of directory object to check.
     994 * @param   pDir                Where to return the found directory object on success.
     995 */
    960996inline bool GuestSession::i_directoryExists(uint32_t uDirID, ComObjPtr<GuestDirectory> *pDir)
    961997{
    … …  
    9981034
    9991035/**
    1000  * Unregisters a directory object from a session.
     1036 * Unregisters a directory object from a guest session.
    10011037 *
    10021038 * @return VBox status code. VERR_NOT_FOUND if the directory is not registered (anymore).
    … …  
    10431079}
    10441080
     1081/**
     1082 * Removes a directory on the guest.
     1083 *
     1084 * @returns VBox status code.
     1085 * @param   strPath             Path of directory on guest to remove.
     1086 * @param   fFlags              Directory remove flags to use.
     1087 * @param   prcGuest            Where to return the guest error when VERR_GSTCTL_GUEST_ERROR
     1088 *                              was returned. Optional.
     1089 */
    10451090int GuestSession::i_directoryRemove(const Utf8Str &strPath, uint32_t fFlags, int *prcGuest)
    10461091{
    … …  
    11691214}
    11701215
     1216/**
     1217 * Open a directory on the guest.
     1218 *
     1219 * @returns VBox status code.
     1220 * @returns VERR_GSTCTL_GUEST_ERROR on received guest error.
     1221 * @param   openInfo            Open information to use.
     1222 * @param   pDirectory          Where to return the guest directory object on success.
     1223 * @param   prcGuest            Where to return the guest error when VERR_GSTCTL_GUEST_ERROR
     1224 *                              was returned. Optional.
     1225 *
     1226 * @note    Takes the write lock.
     1227 */
    11711228int GuestSession::i_directoryOpen(const GuestDirectoryOpenInfo &openInfo,
    11721229                                  ComObjPtr<GuestDirectory> &pDirectory, int *prcGuest)
    … …  
    14151472}
    14161473
     1474/**
     1475 * Checks if a file object exists and optionally returns its object.
     1476 *
     1477 * @returns \c true if file object exists, or \c false if not.
     1478 * @param   uDirID              ID of file object to check.
     1479 * @param   pDir                Where to return the found file object on success.
     1480 */
    14171481inline bool GuestSession::i_fileExists(uint32_t uFileID, ComObjPtr<GuestFile> *pFile)
    14181482{
    … …  
    14281492
    14291493/**
    1430  * Unregisters a file object from a session.
     1494 * Unregisters a file object from a guest session.
    14311495 *
    14321496 * @return VBox status code. VERR_NOT_FOUND if the file is not registered (anymore).
    … …  
    14731537}
    14741538
     1539/**
     1540 * Removes a file from the guest.
     1541 *
     1542 * @returns VBox status code.
     1543 * @returns VERR_GSTCTL_GUEST_ERROR on received guest error.
     1544 * @param   strPath             Path of file on guest to remove.
     1545 * @param   prcGuest            Where to return the guest error when VERR_GSTCTL_GUEST_ERROR
     1546 *                              was returned. Optional.
     1547 */
    14751548int GuestSession::i_fileRemove(const Utf8Str &strPath, int *prcGuest)
    14761549{
    … …  
    15041577}
    15051578
     1579/**
     1580 * Opens a file on the guest.
     1581 *
     1582 * @returns VBox status code.
     1583 * @returns VERR_GSTCTL_GUEST_ERROR on received guest error.
     1584 * @param   aPath               File path on guest to open.
     1585 * @param   aAccessMode         Access mode to use.
     1586 * @param   aOpenAction         Open action to use.
     1587 * @param   aSharingMode        Sharing mode to use.
     1588 * @param   aCreationMode       Creation mode to use.
     1589 * @param   aFlags              Open flags to use.
     1590 * @param   pFile               Where to return the file object on success.
     1591 * @param   prcGuest            Where to return the guest error when VERR_GSTCTL_GUEST_ERROR
     1592 *                              was returned. Optional.
     1593 */
    15061594int GuestSession::i_fileOpenEx(const com::Utf8Str &aPath, FileAccessMode_T aAccessMode, FileOpenAction_T aOpenAction,
    15071595                               FileSharingMode_T aSharingMode, ULONG aCreationMode, const std::vector<FileOpenExFlag_T> &aFlags,
    … …  
    15231611}
    15241612
     1613/**
     1614 * Opens a file on the guest.
     1615 *
     1616 * @returns VBox status code.
     1617 * @returns VERR_GSTCTL_GUEST_ERROR on received guest error.
     1618 * @param   openInfo            Open information to use for opening the file.
     1619 * @param   pFile               Where to return the file object on success.
     1620 * @param   prcGuest            Where to return the guest error when VERR_GSTCTL_GUEST_ERROR
     1621 *                              was returned. Optional.
     1622 */
    15251623int GuestSession::i_fileOpen(const GuestFileOpenInfo &openInfo, ComObjPtr<GuestFile> &pFile, int *prcGuest)
    15261624{
    … …  
    16271725}
    16281726
     1727/**
     1728 * Queries the size of a file on the guest.
     1729 *
     1730 * @returns VBox status code.
     1731 * @returns VERR_GSTCTL_GUEST_ERROR on received guest error.
     1732 * @retval  VERR_
     1733 * @param   strPath             Path of file on guest to query size for.
     1734 * @param   fFollowSymlinks     \c true when wanting to follow symbolic links, \c false if not.
     1735 * @param   pllSize             Where to return the queried file size on success.
     1736 * @param   prcGuest            Where to return the guest error when VERR_GSTCTL_GUEST_ERROR
     1737 *                              was returned. Optional.
     1738 */
    16291739int GuestSession::i_fileQuerySize(const Utf8Str &strPath, bool fFollowSymlinks, int64_t *pllSize, int *prcGuest)
    16301740{
    … …  
    17001810}
    17011811
     1812/**
     1813 * Returns the guest credentials of a guest session.
     1814 *
     1815 * @returns Guest credentials.
     1816 */
    17021817const GuestCredentials& GuestSession::i_getCredentials(void)
    17031818{
    … …  
    17051820}
    17061821
     1822/**
     1823 * Returns the guest session (friendly) name.
     1824 *
     1825 * @returns Guest session name.
     1826 */
    17071827Utf8Str GuestSession::i_getName(void)
    17081828{
    … …  
    17101830}
    17111831
     1832/**
     1833 * Returns a stringified error description for a given guest result code.
     1834 *
     1835 * @returns Stringified error description.
     1836 */
    17121837/* static */
    17131838Utf8Str GuestSession::i_guestErrorToString(int rcGuest)
    … …  
    17861911
    17871912/**
    1788  * Returns whether a session status implies a terminated state or not.
     1913 * Returns whether a guest session status implies a terminated state or not.
    17891914 *
    17901915 * @returns \c true if it's a terminated state, or \c false if not.
    … …  
    19632088}
    19642089
     2090/**
     2091 * Returns the path separation style used on the guest.
     2092 *
     2093 * @returns Separation style used on the guest.
     2094 */
    19652095PathStyle_T GuestSession::i_getPathStyle(void)
    19662096{
    … …  
    19872117}
    19882118
     2119/**
     2120 * Starts the guest session on the guest.
     2121 *
     2122 * @returns VBox status code.
     2123 * @param   prcGuest            Where to return the guest error when VERR_GSTCTL_GUEST_ERROR
     2124 *                              was returned. Optional.
     2125 */
    19892126int GuestSession::i_startSession(int *prcGuest)
    19902127{
    … …  
    20732210
    20742211/**
    2075  * Starts the guest session asynchronously in a separate thread.
     2212 * Starts the guest session asynchronously in a separate worker thread.
    20762213 *
    20772214 * @returns IPRT status code.
    … …  
    22682405
    22692406/**
    2270  * Notifies all registered objects about a session status change.
     2407 * Notifies all registered objects about a guest session status change.
    22712408 *
    22722409 * @returns VBox status code.
    … …  
    23022439}
    23032440
     2441/**
     2442 * Renames a path on the guest.
     2443 *
     2444 * @returns VBox status code.
     2445 * @returns VERR_GSTCTL_GUEST_ERROR on received guest error.
     2446 * @param   strSource           Source path on guest to rename.
     2447 * @param   strDest             Destination path on guest to rename \a strSource to.
     2448 * @param   uFlags              Renaming flags.
     2449 * @param   prcGuest            Where to return the guest error when VERR_GSTCTL_GUEST_ERROR
     2450 *                              was returned. Optional.
     2451 * @note    Takes the write lock.
     2452 */
    23042453int GuestSession::i_pathRename(const Utf8Str &strSource, const Utf8Str &strDest, uint32_t uFlags, int *prcGuest)
    23052454{
    … …  
    24442593
    24452594/**
    2446  * Unregisters a process object from a session.
     2595 * Unregisters a process object from a guest session.
    24472596 *
    24482597 * @return VBox status code. VERR_NOT_FOUND if the process is not registered (anymore).
    … …  
    25982747}
    25992748
     2749/**
     2750 * Checks if a process object exists and optionally returns its object.
     2751 *
     2752 * @returns \c true if process object exists, or \c false if not.
     2753 * @param   uDirID              ID of process object to check.
     2754 * @param   pDir                Where to return the found process object on success.
     2755 *
     2756 * @note    No locking done!
     2757 */
    26002758inline bool GuestSession::i_processExists(uint32_t uProcessID, ComObjPtr<GuestProcess> *pProcess)
    26012759{
    … …  
    26102768}
    26112769
     2770/**
     2771 * Returns the process object from a guest PID.
     2772 *
     2773 * @returns VBox status code.
     2774 * @param   uPID                Guest PID to get process object for.
     2775 * @param   pProcess            Where to return the process object on success.
     2776 *
     2777 * @note    No locking done!
     2778 */
    26122779inline int GuestSession::i_processGetByPID(ULONG uPID, ComObjPtr<GuestProcess> *pProcess)
    26132780{
    … …  
    26382805}
    26392806
     2807/**
     2808 * Sends a message to the HGCM host service.
     2809 *
     2810 * @returns VBox status code.
     2811 * @param   uMessage            Message ID to send.
     2812 * @param   uParms              Number of parameters in \a paParms to send.
     2813 * @param   paParms             Array of HGCM parameters to send.
     2814 * @param   fDst                Host message destination flags of type VBOX_GUESTCTRL_DST_XXX.
     2815 */
    26402816int GuestSession::i_sendMessage(uint32_t uMessage, uint32_t uParms, PVBOXHGCMSVCPARM paParms,
    26412817                                uint64_t fDst /*= VBOX_GUESTCTRL_DST_SESSION*/)
    … …  
    27272903}
    27282904
     2905/** @todo Unused --remove? */
    27292906int GuestSession::i_signalWaiters(GuestSessionWaitResult_T enmWaitResult, int rc /*= VINF_SUCCESS */)
    27302907{
    … …  
    28102987 * session.
    28112988 *
    2812  * @return  IPRT status code.
     2989 * @returns VBox status code.
    28132990 */
    28142991int GuestSession::i_determineProtocolVersion(void)
    … …  
    28453022}
    28463023
     3024/**
     3025 * Waits for guest session events.
     3026 *
     3027 * @returns VBox status code.
     3028 * @returns VERR_GSTCTL_GUEST_ERROR on received guest error.
     3029 * @param   fWaitFlags          Wait flags to use.
     3030 * @param   uTimeoutMS          Timeout (in ms) to wait.
     3031 * @param   waitResult          Where to return the wait result on success.
     3032 * @param   prcGuest            Where to return the guest error when VERR_GSTCTL_GUEST_ERROR
     3033 *                              was returned. Optional.
     3034 *
     3035 * @note    Takes the read lock.
     3036 */
    28473037int GuestSession::i_waitFor(uint32_t fWaitFlags, ULONG uTimeoutMS, GuestSessionWaitResult_T &waitResult, int *prcGuest)
    28483038{
    … …  
    30113201
    30123202/**
    3013  * Undocumented, you guess what it does.
    3014  *
    3015  * @note Similar code in GuestFile::i_waitForStatusChange() and
    3016  *       GuestProcess::i_waitForStatusChange().
     3203 * Waits for guest session status changes.
     3204 *
     3205 * @returns VBox status code.
     3206 * @returns VERR_GSTCTL_GUEST_ERROR on received guest error.
     3207 * @param   pEvent              Wait event to use for waiting.
     3208 * @param   fWaitFlags          Wait flags to use.
     3209 * @param   uTimeoutMS          Timeout (in ms) to wait.
     3210 * @param   pSessionStatus      Where to return the guest session status.
     3211 * @param   prcGuest            Where to return the guest error when VERR_GSTCTL_GUEST_ERROR
     3212 *                              was returned. Optional.
     3213 *
     3214 * @note    Takes the read lock.
    30173215 */
    30183216int GuestSession::i_waitForStatusChange(GuestWaitEvent *pEvent, uint32_t fWaitFlags, uint32_t uTimeoutMS,

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

    r92822 r92897  
    55
    66/*
    7  * Copyright (C) 2012-2020 Oracle Corporation
     7 * Copyright (C) 2012-2021 Oracle Corporation
    88 *
    99 * This file is part of VirtualBox Open Source Edition (OSE), as
    … …  
    9191}
    9292
     93/**
     94 * Creates (and initializes / sets) the progress objects of a guest session task.
     95 *
     96 * @returns VBox status code.
     97 * @param   cOperations         Number of operation the task wants to perform.
     98 */
    9399int GuestSessionTask::createAndSetProgressObject(ULONG cOperations /* = 1 */)
    94100{
    … …  
    128134#endif
    129135
     136/**
     137 * Gets a guest property from the VM.
     138 *
     139 * @returns VBox status code.
     140 * @param   pGuest              Guest object of VM to get guest property from.
     141 * @param   strPath             Guest property to path to get.
     142 * @param   strValue            Where to store the guest property value on success.
     143 */
    130144int GuestSessionTask::getGuestProperty(const ComObjPtr<Guest> &pGuest,
    131145                                       const Utf8Str &strPath, Utf8Str &strValue)
    … …  
    148162}
    149163
     164/**
     165 * Sets the percentage of a guest session task progress.
     166 *
     167 * @returns VBox status code.
     168 * @param   uPercent            Percentage (0-100) to set.
     169 */
    150170int GuestSessionTask::setProgress(ULONG uPercent)
    151171{
    … …  
    171191}
    172192
     193/**
     194 * Sets the task's progress object to succeeded.
     195 *
     196 * @returns VBox status code.
     197 */
    173198int GuestSessionTask::setProgressSuccess(void)
    174199{
    … …  
    13341359}
    13351360
     1361/** @copydoc GuestSessionTask::Run */
    13361362int GuestSessionTaskOpen::Run(void)
    13371363{
    … …  
    13821408}
    13831409
     1410/**
     1411 * Initializes a copy-from-guest task.
     1412 *
     1413 * @returns HRESULT
     1414 * @param   strTaskDesc         Friendly task description.
     1415 */
    13841416HRESULT GuestSessionTaskCopyFrom::Init(const Utf8Str &strTaskDesc)
    13851417{
    … …  
    15441576}
    15451577
     1578/** @copydoc GuestSessionTask::Run */
    15461579int GuestSessionTaskCopyFrom::Run(void)
    15471580{
    … …  
    16761709}
    16771710
     1711/**
     1712 * Initializes a copy-to-guest task.
     1713 *
     1714 * @returns HRESULT
     1715 * @param   strTaskDesc         Friendly task description.
     1716 */
    16781717HRESULT GuestSessionTaskCopyTo::Init(const Utf8Str &strTaskDesc)
    16791718{
    … …  
    18131852}
    18141853
     1854/** @copydoc GuestSessionTask::Run */
    18151855int GuestSessionTaskCopyTo::Run(void)
    18161856{
    … …  
    20642104}
    20652105
     2106/**
     2107 * Adds arguments to existing process arguments.
     2108 * Identical / already existing arguments will be filtered out.
     2109 *
     2110 * @returns VBox status code.
     2111 * @param   aArgumentsDest      Destination to add arguments to.
     2112 * @param   aArgumentsSource    Arguments to add.
     2113 */
    20662114int GuestSessionTaskUpdateAdditions::addProcessArguments(ProcessArguments &aArgumentsDest, const ProcessArguments &aArgumentsSource)
    20672115{
    … …  
    21022150}
    21032151
     2152/**
     2153 * Helper function to copy a file from a VISO to the guest.
     2154 *
     2155 * @returns VBox status code.
     2156 * @param   pSession            Guest session to use.
     2157 * @param   hVfsIso             VISO handle to use.
     2158 * @param   strFileSrc          Source file path on VISO to copy.
     2159 * @param   strFileDst          Destination file path on guest.
     2160 * @param   fOptional           When set to \c true, the file is optional, i.e. can be skipped
     2161 *                              when not found, \c false if not.
     2162 */
    21042163int GuestSessionTaskUpdateAdditions::copyFileToGuest(GuestSession *pSession, RTVFS hVfsIso,
    21052164                                                     Utf8Str const &strFileSrc, const Utf8Str &strFileDst, bool fOptional)
    … …  
    21602219}
    21612220
     2221/**
     2222 * Helper function to run (start) a file on the guest.
     2223 *
     2224 * @returns VBox status code.
     2225 * @param   pSession            Guest session to use.
     2226 * @param   procInfo            Guest process startup info to use.
     2227 */
    21622228int GuestSessionTaskUpdateAdditions::runFileOnGuest(GuestSession *pSession, GuestProcessStartupInfo &procInfo)
    21632229{
    … …  
    22092275}
    22102276
     2277/** @copydoc GuestSessionTask::Run */
    22112278int GuestSessionTaskUpdateAdditions::Run(void)
    22122279{
Note: See TracChangeset for help on using the changeset viewer.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette