VirtualBox

Changeset 77116 in vbox for trunk/src/VBox


Ignore:
Timestamp:
Feb 1, 2019 2:20:52 PM (6 years ago)
Author:
vboxsync
Message:

Guest Control/Main: Docs.

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

Legend:

Unmodified
Added
Removed

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

    r77079 r77116  
    6565    Utf8Str                     mDomain;
    6666};
    67 
    6867
    6968
    … …  
    224223    }
    225224
    226 
    227225    /**
    228226     * See RTEnvQueryUtf8Block for details.
    … …  
    291289        return rc;
    292290    }
    293 
    294291
    295292    /**

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

    r77113 r77116  
    6565 *
    6666 * @returns VBox status code.
     67 * @param   pvExtension         Pointer to HGCM service extension.
     68 * @param   idMessage           HGCM message ID the callback was called for.
     69 * @param   pvData              Pointer to user-supplied callback data.
     70 * @param   cbData              Size (in bytes) of user-supplied callback data.
    6771 */
    6872/* static */
    … …  
    118122/////////////////////////////////////////////////////////////////////////////
    119123
     124/**
     125 * Dispatches a host service callback to the appropriate guest control session object.
     126 *
     127 * @returns VBox status code.
     128 * @param   pCtxCb              Pointer to host callback context.
     129 * @param   pSvcCb              Pointer to callback parameters.
     130 */
    120131int Guest::i_dispatchToSession(PVBOXGUESTCTRLHOSTCBCTX pCtxCb, PVBOXGUESTCTRLHOSTCALLBACK pSvcCb)
    121132{
    … …  
    211222}
    212223
     224/**
     225 * Removes a guest control session from the internal list and destroys the session.
     226 *
     227 * @returns VBox status code.
     228 * @param   uSessionID          ID of the guest control session to remove.
     229 */
    213230int Guest::i_sessionRemove(uint32_t uSessionID)
    214231{
    … …  
    244261}
    245262
     263/**
     264 * Creates a new guest session.
     265 * This will invoke VBoxService running on the guest creating a new (dedicated) guest session
     266 * On older Guest Additions this call has no effect on the guest, and only the credentials will be
     267 * used for starting/impersonating guest processes.
     268 *
     269 * @returns VBox status code.
     270 * @param   ssInfo              Guest session startup information.
     271 * @param   guestCreds          Guest OS (user) credentials to use on the guest for creating the session.
     272 *                              The specified user must be able to logon to the guest and able to start new processes.
     273 * @param   pGuestSession       Where to store the created guest session on success.
     274 */
    246275int Guest::i_sessionCreate(const GuestSessionStartupInfo &ssInfo,
    247276                           const GuestCredentials &guestCreds, ComObjPtr<GuestSession> &pGuestSession)
    … …  
    325354}
    326355
     356/**
     357 * Returns whether a guest control session with a specific ID exists or not.
     358 *
     359 * @returns Returns \c true if the session exists, \c false if not.
     360 * @param   uSessionID          ID to check for.
     361 */
    327362inline bool Guest::i_sessionExists(uint32_t uSessionID)
    328363{

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

    r77097 r77116  
    235235}
    236236
     237/**
     238 * Parses stream block output data which came from the 'stat' (vbox_stat)
     239 * VBoxService toolbox command. The result will be stored in this object.
     240 *
     241 * @returns VBox status code.
     242 * @param   strmBlk             Stream block output data to parse.
     243 */
    237244int GuestFsObjData::FromStat(const GuestProcessStreamBlock &strmBlk)
    238245{
    … …  
    241248}
    242249
     250/**
     251 * Parses stream block output data which came from the 'mktemp' (vbox_mktemp)
     252 * VBoxService toolbox command. The result will be stored in this object.
     253 *
     254 * @returns VBox status code.
     255 * @param   strmBlk             Stream block output data to parse.
     256 */
    243257int GuestFsObjData::FromMkTemp(const GuestProcessStreamBlock &strmBlk)
    244258{
    … …  
    259273}
    260274
    261 
    262 
    263275/**
    264276 * Returns the IPRT-compatible file mode.
    … …  
    304316}
    305317
    306 /*
    307 GuestProcessStreamBlock::GuestProcessStreamBlock(const GuestProcessStreamBlock &otherBlock)
    308 {
    309     for (GuestCtrlStreamPairsIter it = otherBlock.mPairs.begin();
    310          it != otherBlock.end(); ++it)
    311     {
    312         mPairs[it->first] = new
    313         if (it->second.pszValue)
    314         {
    315             RTMemFree(it->second.pszValue);
    316             it->second.pszValue = NULL;
    317         }
    318     }
    319 }*/
    320 
    321318GuestProcessStreamBlock::~GuestProcessStreamBlock()
    322319{
    … …  
    325322
    326323/**
    327  * Destroys the currently stored stream pairs.
    328  *
    329  * @return  IPRT status code.
     324 * Clears (destroys) the currently stored stream pairs.
    330325 */
    331326void GuestProcessStreamBlock::Clear(void)
    … …  
    335330
    336331#ifdef DEBUG
     332/**
     333 * Dumps the currently stored stream pairs to the (debug) log.
     334 */
    337335void GuestProcessStreamBlock::DumpToLog(void) const
    338336{
    … …  
    351349 * Returns a 64-bit signed integer of a specified key.
    352350 *
    353  * @return  IPRT status code. VERR_NOT_FOUND if key was not found.
     351 * @return VBox status code. VERR_NOT_FOUND if key was not found.
    354352 * @param  pszKey               Name of key to get the value for.
    355353 * @param  piVal                Pointer to value to return.
    … …  
    395393 * Gets the return code (name = "rc") of this stream block.
    396394 *
    397  * @return  IPRT status code.
     395 * @return  VBox status code.
    398396 */
    399397int GuestProcessStreamBlock::GetRc(void) const
    … …  
    433431 * Returns a 32-bit unsigned integer of a specified key.
    434432 *
    435  * @return  IPRT status code. VERR_NOT_FOUND if key was not found.
     433 * @return  VBox status code. VERR_NOT_FOUND if key was not found.
    436434 * @param   pszKey              Name of key to get the value for.
    437435 * @param   puVal               Pointer to value to return.
    … …  
    487485 * Sets a value to a key or deletes a key by setting a NULL value.
    488486 *
    489  * @return  IPRT status code.
     487 * @return  VBox status code.
    490488 * @param   pszKey              Key name to process.
    491489 * @param   pszValue            Value to set. Set NULL for deleting the key.
    … …  
    542540 * are multiple rounds of adding data needed.
    543541 *
    544  * @return  IPRT status code.
     542 * @return  VBox status code.
    545543 * @param   pbData              Pointer to data to add.
    546544 * @param   cbData              Size (in bytes) of data to add.
    … …  
    627625
    628626#ifdef DEBUG
     627/**
     628 * Dumps the raw guest process output to a file on the host.
     629 * If the file on the host already exists, it will be overwritten.
     630 *
     631 * @param   pszFile             Absolute path to host file to dump the output to.
     632 */
    629633void GuestProcessStream::Dump(const char *pszFile)
    630634{
    … …  
    656660 * block (with zero or more pairs stored in stream block).
    657661 *
    658  * @return IPRT status code.
     662 * @return VBox status code.
    659663 * @param streamBlock               Reference to guest stream block to fill.
    660  *
    661664 */
    662665int GuestProcessStream::ParseBlock(GuestProcessStreamBlock &streamBlock)
    … …  
    736739}
    737740
     741/**
     742 * Separate initialization function for the base class.
     743 *
     744 * @returns VBox status code.
     745 */
    738746int GuestBase::baseInit(void)
    739747{
    … …  
    744752}
    745753
     754/**
     755 * Separate uninitialization function for the base class.
     756 */
    746757void GuestBase::baseUninit(void)
    747758{
    … …  
    755766}
    756767
     768/**
     769 * Cancels all outstanding wait events.
     770 *
     771 * @returns VBox status code.
     772 */
    757773int GuestBase::cancelWaitEvents(void)
    758774{
    … …  
    861877}
    862878
     879/**
     880 * Generates a context ID (CID) by incrementing the object's count.
     881 * A CID consists of a session ID, an object ID and a count.
     882 *
     883 * Note: This function does not guarantee that the returned CID is unique;
     884 *       the caller has to take care of that and eventually retry.
     885 *
     886 * @returns VBox status code.
     887 * @param   uSessionID          Session ID to use for CID generation.
     888 * @param   uObjectID           Object ID to use for CID generation.
     889 * @param   puContextID         Where to store the generated CID on success.
     890 */
    863891int GuestBase::generateContextID(uint32_t uSessionID, uint32_t uObjectID, uint32_t *puContextID)
    864892{
    … …  
    890918 * around once at a time.
    891919 *
    892  * @returns IPRT status code.
     920 * @returns VBox status code.
    893921 * @retval  VERR_GSTCTL_MAX_CID_COUNT_REACHED if unable to generate a free context ID (CID, the count part (bits 15:0)).
    894922 * @param   uSessionID              Session ID to register wait event for.
    … …  
    10251053}
    10261054
     1055/**
     1056 * Signals all wait events of a specific type (if found)
     1057 * and notifies external events accordingly.
     1058 *
     1059 * @returns VBox status code.
     1060 * @param   aType               Event type to signal.
     1061 * @param   aEvent              Which external event to notify.
     1062 */
    10271063int GuestBase::signalWaitEvent(VBoxEventType_T aType, IEvent *aEvent)
    10281064{
    … …  
    10811117}
    10821118
     1119/**
     1120 * Signals a wait event which is registered to a specific callback (bound to a context ID (CID)).
     1121 *
     1122 * @returns VBox status code.
     1123 * @param   pCbCtx              Pointer to host service callback context.
     1124 * @param   rcGuest             Guest return code (rc) to set additionally, if rc is set to VERR_GSTCTL_GUEST_ERROR.
     1125 * @param   pPayload            Additional wait event payload data set set on return. Optional.
     1126 */
    10831127int GuestBase::signalWaitEventInternal(PVBOXGUESTCTRLHOSTCBCTX pCbCtx,
    10841128                                       int rcGuest, const GuestWaitEventPayload *pPayload)
    … …  
    10921136}
    10931137
     1138/**
     1139 * Signals a wait event which is registered to a specific callback (bound to a context ID (CID)).
     1140 * Extended version.
     1141 *
     1142 * @returns VBox status code.
     1143 * @param   pCbCtx              Pointer to host service callback context.
     1144 * @param   rc                  Return code (rc) to set as wait result.
     1145 * @param   rcGuest             Guest return code (rc) to set additionally, if rc is set to VERR_GSTCTL_GUEST_ERROR.
     1146 * @param   pPayload            Additional wait event payload data set set on return. Optional.
     1147 */
    10941148int GuestBase::signalWaitEventInternalEx(PVBOXGUESTCTRLHOSTCBCTX pCbCtx,
    10951149                                         int rc, int rcGuest,
    … …  
    11271181 * After successful unregistration the event will not be valid anymore.
    11281182 *
    1129  * @returns IPRT status code.
     1183 * @returns VBox status code.
    11301184 * @param   pWaitEvt        Wait event to unregister (delete).
    11311185 */
    … …  
    12071261 * Waits for an already registered guest wait event.
    12081262 *
    1209  * @return  IPRT status code.
     1263 * @return  VBox status code.
    12101264 * @param   pWaitEvt                Pointer to event to wait for.
    12111265 * @param   msTimeout               Timeout (in ms) for waiting.
    … …  
    12681322}
    12691323
     1324/**
     1325 * Binds this guest (control) object to a specific guest (control) session.
     1326 *
     1327 * @returns VBox status code.
     1328 * @param   pConsole            Pointer to console object to use.
     1329 * @param   pSession            Pointer to session to bind this object to.
     1330 * @param   uObjectID           Object ID for this object to use within that specific session.
     1331 *                              Each object ID must be unique per session.
     1332 */
    12701333int GuestObject::bindToSession(Console *pConsole, GuestSession *pSession, uint32_t uObjectID)
    12711334{
    … …  
    12801343}
    12811344
     1345/**
     1346 * Registers (creates) a new wait event.
     1347 *
     1348 * @returns VBox status code.
     1349 * @param   lstEvents           List of events which the new wait event gets triggered at.
     1350 * @param   ppEvent             Returns the new wait event on success.
     1351 */
    12821352int GuestObject::registerWaitEvent(const GuestEventTypes &lstEvents,
    12831353                                   GuestWaitEvent **ppEvent)
    … …  
    12871357}
    12881358
     1359/**
     1360 * Sends a HGCM message to the guest (via the guest control host service).
     1361 *
     1362 * @returns VBox status code.
     1363 * @param   uMessage            Message ID of message to send.
     1364 * @param   cParms              Number of HGCM message parameters to send.
     1365 * @param   paParms             Array of HGCM message parameters to send.
     1366 */
    12891367int GuestObject::sendMessage(uint32_t uMessage, uint32_t cParms, PVBOXHGCMSVCPARM paParms)
    12901368{
    … …  
    13411419}
    13421420
     1421/**
     1422 * Initializes a wait event with a specific context ID (CID).
     1423 *
     1424 * @returns VBox status code.
     1425 * @param   uCID                Context ID (CID) to initialize wait event with.
     1426 */
    13431427int GuestWaitEventBase::Init(uint32_t uCID)
    13441428{
    … …  
    13481432}
    13491433
     1434/**
     1435 * Signals a wait event.
     1436 *
     1437 * @returns VBox status code.
     1438 * @param   rc                  Return code (rc) to set as wait result.
     1439 * @param   rcGuest             Guest return code (rc) to set additionally, if rc is set to VERR_GSTCTL_GUEST_ERROR.
     1440 * @param   pPayload            Additional wait event payload data set set on return. Optional.
     1441 */
    13501442int GuestWaitEventBase::SignalInternal(int rc, int rcGuest,
    13511443                                       const GuestWaitEventPayload *pPayload)
    … …  
    13771469}
    13781470
     1471/**
     1472 * Waits for the event to get triggered. Will return success if the
     1473 * wait was successufl (e.g. was being triggered), otherwise an error will be returned.
     1474 *
     1475 * @returns VBox status code.
     1476 * @param   msTimeout           Timeout (in ms) to wait.
     1477 *                              Specifiy 0 to wait indefinitely.
     1478 */
    13791479int GuestWaitEventBase::Wait(RTMSINTERVAL msTimeout)
    13801480{
    … …  
    14281528 * Initializes a wait event with a given context ID (CID).
    14291529 *
    1430  * @returns IPRT status code.
     1530 * @returns VBox status code.
    14311531 * @param   uCID                Context ID to initialize wait event with.
    14321532 */
    … …  
    14391539 * Initializes a wait event with a given context ID (CID) and a list of event types to wait for.
    14401540 *
    1441  * @returns IPRT status code.
     1541 * @returns VBox status code.
    14421542 * @param   uCID                Context ID to initialize wait event with.
    14431543 * @param   lstEvents           List of event types to wait for this wait event to get signalled.
    … …  
    14571557 * Signals the event.
    14581558 *
    1459  * @return  IPRT status code.
     1559 * @return  VBox status code.
    14601560 * @param   pEvent              Public IEvent to associate.
    14611561 *                              Optional.
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