VirtualBox

Ignore:
Timestamp:
Nov 28, 2018 11:47:11 PM (6 years ago)
Author:
vboxsync
svn:sync-xref-src-repo-rev:
127001
Message:

VBoxGuestControl: Optimizing message handling - part 1. bugref:9313

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/include/VBox/HostServices/GuestControlSvc.h

    r75757 r75798  
    109109} VBOXGUESTCTRLHOSTCALLBACK, *PVBOXGUESTCTRLHOSTCALLBACK;
    110110
     111
     112/** @name Host message destiation flags.
     113 *
     114 * This is ORed into the context ID parameter Main after extending it to 64-bit.
     115 *
     116 * @internal Host internal.
     117 * @{ */
     118#define VBOX_GUESTCTRL_DST_ROOT_SVC     RT_BIT_64(63)
     119#define VBOX_GUESTCTRL_DST_SESSION      RT_BIT_64(62)
     120#define VBOX_GUESTCTRL_DST_BOTH         ( VBOX_GUESTCTRL_DST_ROOT_SVC | VBOX_GUESTCTRL_DST_SESSION )
     121/** @} */
     122
     123
    111124/**
    112125 * The service functions which are callable by host.
    … …  
    204217};
    205218
     219
     220/**
     221 * Translates a guest control host function function enum to at string.
     222 * @returns Enum string name.
     223 * @param   enmFunction     The function name to translate.
     224 */
     225DECLINLINE(const char *) GstCtrlHostFnName(enum eHostFn enmFunction)
     226{
     227    switch (enmFunction)
     228    {
     229        RT_CASE_RET_STR(HOST_CANCEL_PENDING_WAITS);
     230        RT_CASE_RET_STR(HOST_SESSION_CREATE);
     231        RT_CASE_RET_STR(HOST_SESSION_CLOSE);
     232        RT_CASE_RET_STR(HOST_EXEC_CMD);
     233        RT_CASE_RET_STR(HOST_EXEC_SET_INPUT);
     234        RT_CASE_RET_STR(HOST_EXEC_GET_OUTPUT);
     235        RT_CASE_RET_STR(HOST_EXEC_TERMINATE);
     236        RT_CASE_RET_STR(HOST_EXEC_WAIT_FOR);
     237        RT_CASE_RET_STR(HOST_FILE_OPEN);
     238        RT_CASE_RET_STR(HOST_FILE_CLOSE);
     239        RT_CASE_RET_STR(HOST_FILE_READ);
     240        RT_CASE_RET_STR(HOST_FILE_READ_AT);
     241        RT_CASE_RET_STR(HOST_FILE_WRITE);
     242        RT_CASE_RET_STR(HOST_FILE_WRITE_AT);
     243        RT_CASE_RET_STR(HOST_FILE_SEEK);
     244        RT_CASE_RET_STR(HOST_FILE_TELL);
     245        RT_CASE_RET_STR(HOST_DIR_REMOVE);
     246        RT_CASE_RET_STR(HOST_PATH_RENAME);
     247        RT_CASE_RET_STR(HOST_PATH_USER_DOCUMENTS);
     248        RT_CASE_RET_STR(HOST_PATH_USER_HOME);
     249    }
     250    return "Unknown";
     251}
     252
     253
    206254/**
    207255 * The service functions which are called by guest. The numbers may not change,
    … …  
    210258enum eGuestFn
    211259{
    212     /**
    213      * Guest waits for a new message the host wants to process on the guest side.
     260    /** Guest waits for a new message the host wants to process on the guest side.
    214261     * This is a blocking call and can be deferred.
    215262     *
    … …  
    231278     */
    232279    GUEST_MSG_WAIT = 1,
    233     /**
    234      * Guest asks the host to cancel all pending waits the guest itself waits on.
    235      * This becomes necessary when the guest wants to quit but still waits for
    236      * commands from the host.
    237      */
    238     GUEST_CANCEL_PENDING_WAITS = 2,
    239     /**
    240      * Guest disconnected (terminated normally or due to a crash HGCM
     280    /** Cancels pending calls for this client session.
     281     *
     282     * This should be used if a GUEST_MSG_PEEK_WAIT or GUEST_MSG_WAIT call gets
     283     * interrupted on the client end, so as to prevent being rebuffed with
     284     * VERR_RESOURCE_BUSY when restarting the call.
     285     *
     286     * @retval  VINF_SUCCESS if cancelled any calls.
     287     * @retval  VWRN_NOT_FOUND if no callers.
     288     * @retval  VERR_INVALID_CLIENT_ID
     289     * @retval  VERR_WRONG_PARAMETER_COUNT
     290     * @since   6.0
     291     */
     292    GUEST_MSG_CANCEL = 2,
     293    /** Guest disconnected (terminated normally or due to a crash HGCM
    241294     * detected when calling service::clientDisconnect().
     295     *
     296     * @note This is a host side notification message that has no business in this
     297     *       enum.  The guest cannot use this function number, host will reject it.
    242298     */
    243299    GUEST_DISCONNECTED = 3,
    244     /**
    245      * Sets a message filter to only get messages which have a certain
     300    /** Sets a message filter to only get messages which have a certain
    246301     * context ID scheme (that is, a specific session, object etc).
    247302     * Since VBox 4.3+.
     303     * @deprecated  Replaced by GUEST_SESSION_ACCEPT.
    248304     */
    249305    GUEST_MSG_FILTER_SET = 4,
    250     /**
    251      * Unsets (and resets) a previously set message filter.
     306    /** Unsets (and resets) a previously set message filter.
     307     * @retval  VERR_NOT_IMPLEMENTED since 6.0.
     308     * @deprecated  Never needed or used,
    252309     */
    253310    GUEST_MSG_FILTER_UNSET = 5,
    254     /**
    255      * Skips the current assigned message returned by GUEST_MSG_WAIT.
    256      * Needed for telling the host service to not keep stale
    257      * host commands in the queue.
    258      */
    259     GUEST_MSG_SKIP = 10,
    260     /**
    261      * General reply to a host message. Only contains basic data
    262      * along with a simple payload.
    263      */
    264     GUEST_MSG_REPLY = 11,
    265     /**
    266      * General message for updating a pending progress for
    267      * a long task.
    268      */
    269     GUEST_MSG_PROGRESS_UPDATE = 12,
    270 
    271311    /** Peeks at the next message, returning immediately.
    272312     *
    … …  
    279319     * @retval  VINF_SUCCESS if a message was pending and is being returned.
    280320     * @retval  VERR_TRY_AGAIN if no message pending.
    281      * @retval  VERR_INVALID_HANDLE if invalid client ID.
    282      * @retval  VERR_INVALID_PARAMETER if incorrect parameter count or types.
     321     * @retval  VERR_INVALID_CLIENT_ID
     322     * @retval  VERR_WRONG_PARAMETER_COUNT
     323     * @retval  VERR_WRONG_PARAMETER_TYPE
    283324     * @since   6.0
    284325     */
    285     GUEST_MSG_PEEK_NOWAIT,
     326    GUEST_MSG_PEEK_NOWAIT = 6,
    286327    /** Peeks at the next message, waiting for one to arrive.
    287328     *
    … …  
    294335     * @retval  VINF_SUCCESS if info about an pending message is being returned.
    295336     * @retval  VINF_TRY_AGAIN and message set to HOST_CANCEL_PENDING_WAITS if
    296      *          cancelled by GUEST_MSG_CANCEL or GUEST_CANCEL_PENDING_WAITS.
     337     *          cancelled by GUEST_MSG_CANCEL.
    297338     * @retval  VERR_RESOURCE_BUSY if another thread already made a waiting call.
    298      * @retval  VERR_INVALID_HANDLE if invalid client ID.
    299      * @retval  VERR_INVALID_PARAMETER if incorrect parameter count or types.
     339     * @retval  VERR_INVALID_CLIENT_ID
     340     * @retval  VERR_WRONG_PARAMETER_COUNT
     341     * @retval  VERR_WRONG_PARAMETER_TYPE
    300342     * @note    This replaces GUEST_MSG_WAIT.
    301343     * @since   6.0
    302344     */
    303     GUEST_MSG_PEEK_WAIT,
     345    GUEST_MSG_PEEK_WAIT = 7,
    304346    /** Gets the next message, returning immediately.
    305347     *
    … …  
    313355     * @retval  VERR_TRY_AGAIN if no message pending.
    314356     * @retval  VERR_MISMATCH if the incoming message ID does not match the pending.
    315      * @retval  VERR_OUT_OF_RANGE if the wrong parameter count.
    316      * @retval  VERR_WRONG_TYPE if a parameter has the wrong type.
    317357     * @retval  VERR_BUFFER_OVERFLOW if a parmeter buffer is too small.  The buffer
    318358     *          size was updated to reflect the required size.
    319      * @retval  VERR_INVALID_HANDLE if invalid client ID.
     359     * @retval  VERR_INVALID_CLIENT_ID
     360     * @retval  VERR_WRONG_PARAMETER_COUNT
     361     * @retval  VERR_WRONG_PARAMETER_TYPE
    320362     * @note    This replaces GUEST_MSG_WAIT.
    321363     * @since   6.0
    322364     */
    323     GUEST_MSG_GET,
    324     /** Cancels pending calls for this client session.
    325      *
    326      * This should be used if a GUEST_MSG_PEEK_WAIT or GUEST_MSG_WAIT call gets
    327      * interrupted on the client end, so as to prevent being rebuffed with
    328      * VERR_RESOURCE_BUSY when restarting the call.
    329      *
    330      * @retval  VINF_SUCCESS if cancelled any calls.
    331      * @retval  VWRN_NOT_FOUND if no callers.
    332      * @retval  VERR_INVALID_PARAMETER if any parameters specified (expects zero).
    333      * @retval  VERR_INVALID_HANDLE if invalid client ID.
     365    GUEST_MSG_GET = 8,
     366    /** Skip message.
     367     *
     368     * This skips the current message, replying to the sender with
     369     * VERR_NOT_SUPPORTED if appropriate.  No parameters.
     370     *
     371     * @retval  VINF_SUCCESS on success.
     372     * @retval  VERR_NOT_FOUND if no message pending.
     373     * @retval  VERR_INVALID_CLIENT_ID
     374     * @retval  VERR_WRONG_PARAMETER_COUNT
    334375     * @since   6.0
    335376     */
    336     GUEST_MSG_CANCEL,
    337 
     377    GUEST_MSG_SKIP = 9,
     378    /**
     379     * Skips the current assigned message returned by GUEST_MSG_WAIT.
     380     * Needed for telling the host service to not keep stale
     381     * host commands in the queue.
     382     * @deprecated  Replaced by GUEST_MSG_SKIP.
     383     */
     384    GUEST_MSG_SKIP_OLD = 10,
     385    /** General reply to a host message.
     386     * Only contains basic data along with a simple payload.
     387     * @todo proper docs.
     388     */
     389    GUEST_MSG_REPLY = 11,
     390    /** General message for updating a pending progress for a long task.
     391     * @todo proper docs.
     392     */
     393    GUEST_MSG_PROGRESS_UPDATE = 12,
     394    /** Sets the caller as the master.
     395     *
     396     * Called by the root VBoxService to explicitly tell the host that's the master
     397     * service.  Required to use main VBoxGuest device node.  No parameters.
     398     *
     399     * @retval  VINF_SUCCESS on success.
     400     * @retval  VERR_ACCESS_DENIED if not using main VBoxGuest device not
     401     * @retval  VERR_RESOURCE_BUSY if there is already a master.
     402     * @retval  VERR_VERSION_MISMATCH if VBoxGuest didn't supply requestor info.
     403     * @retval  VERR_INVALID_CLIENT_ID
     404     * @retval  VERR_WRONG_PARAMETER_COUNT
     405     * @since   6.0
     406     */
     407    GUEST_MAKE_ME_MASTER = 13,
     408    /** Prepares the starting of a session.
     409     *
     410     * VBoxService makes this call before spawning a session process (must be
     411     * master). The first parameter is the session ID and the second is a one time
     412     * key for identifying the right session process.  First parameter is a 32-bit
     413     * session ID with a value between 1 and 0xfff0.  The second parameter is a byte
     414     * buffer containing a key that GUEST_SESSION_ACCEPT checks against, minimum
     415     * length is 64 bytes, maximum 16384 bytes.
     416     *
     417     * @retval  VINF_SUCCESS on success.
     418     * @retval  VERR_OUT_OF_RESOURCES if too many pending sessions hanging around.
     419     * @retval  VERR_OUT_OF_RANGE if the session ID outside the allowed range.
     420     * @retval  VERR_BUFFER_OVERFLOW if key too large.
     421     * @retval  VERR_BUFFER_UNDERFLOW if key too small.
     422     * @retval  VERR_ACCESS_DENIED if not master or in legacy mode.
     423     * @retval  VERR_DUPLICATE if the session ID has been prepared already.
     424     * @retval  VERR_INVALID_CLIENT_ID
     425     * @retval  VERR_WRONG_PARAMETER_COUNT
     426     * @retval  VERR_WRONG_PARAMETER_TYPE
     427     * @since   6.0
     428     */
     429    GUEST_SESSION_PREPARE = 14,
     430    /** Cancels a prepared session.
     431     *
     432     * VBoxService makes this call to clean up after spawning a session process
     433     * failed.  One parameter, 32-bit session ID.  If UINT32_MAX is passed, all
     434     * prepared sessions are cancelled.
     435     *
     436     * @retval  VINF_SUCCESS on success.
     437     * @retval  VWRN_NOT_FOUND if no session with the specified ID.
     438     * @retval  VERR_ACCESS_DENIED if not master or in legacy mode.
     439     * @retval  VERR_INVALID_CLIENT_ID
     440     * @retval  VERR_WRONG_PARAMETER_COUNT
     441     * @retval  VERR_WRONG_PARAMETER_TYPE
     442     * @since   6.0
     443     */
     444    GUEST_SESSION_CANCEL_PREPARED = 15,
     445    /** Accepts a prepared session.
     446     *
     447     * The session processes makes this call to accept a prepared session.  The
     448     * session ID is then uniquely associated with the HGCM client ID of the caller.
     449     * The parameters must be identical to the matching GUEST_SESSION_PREPARE call.
     450     *
     451     * @retval  VINF_SUCCESS on success.
     452     * @retval  VERR_NOT_FOUND if the specified session ID wasn't found.
     453     * @retval  VERR_OUT_OF_RANGE if the session ID outside the allowed range.
     454     * @retval  VERR_BUFFER_OVERFLOW if key too large.
     455     * @retval  VERR_BUFFER_UNDERFLOW if key too small.
     456     * @retval  VERR_ACCESS_DENIED if we're in legacy mode or is master.
     457     * @retval  VERR_RESOURCE_BUSY if the client is already associated with a session.
     458     * @retval  VERR_MISMATCH if the key didn't match.
     459     * @retval  VERR_INVALID_CLIENT_ID
     460     * @retval  VERR_WRONG_PARAMETER_COUNT
     461     * @retval  VERR_WRONG_PARAMETER_TYPE
     462     * @since   6.0
     463     */
     464    GUEST_SESSION_ACCEPT = 16,
    338465    /**
    339466     * Guest reports back a guest session status.
     467     * @todo proper docs.
    340468     */
    341469    GUEST_SESSION_NOTIFY = 20,
    342470    /**
    343471     * Guest wants to close a specific guest session.
     472     * @todo proper docs.
    344473     */
    345474    GUEST_SESSION_CLOSE = 21,
    … …  
    347476    /**
    348477     * Guests sends output from an executed process.
     478     * @todo proper docs.
    349479     */
    350480    GUEST_EXEC_OUTPUT = 100,
    351481    /**
    352482     * Guest sends a status update of an executed process to the host.
     483     * @todo proper docs.
    353484     */
    354485    GUEST_EXEC_STATUS = 101,
    355486    /**
    356487     * Guests sends an input status notification to the host.
     488     * @todo proper docs.
    357489     */
    358490    GUEST_EXEC_INPUT_STATUS = 102,
    … …  
    362494     * how many data is available / can be sent without actually
    363495     * transmitting the data.
     496     * @todo proper docs.
    364497     */
    365498    GUEST_EXEC_IO_NOTIFY = 210,
    366499    /**
    367500     * Guest notifies the host about some directory event.
     501     * @todo proper docs.
    368502     */
    369503    GUEST_DIR_NOTIFY = 230,
    370504    /**
    371505     * Guest notifies the host about some file event.
     506     * @todo proper docs.
    372507     */
    373508    GUEST_FILE_NOTIFY = 240
    374509};
     510
     511/**
     512 * Translates a guest control host function function enum to at string.
     513 * @returns Enum string name.
     514 * @param   enmFunction     The function name to translate.
     515 */
     516DECLINLINE(const char *) GstCtrlGuestFnName(enum eGuestFn enmFunction)
     517{
     518    switch (enmFunction)
     519    {
     520        RT_CASE_RET_STR(GUEST_MSG_WAIT);
     521        RT_CASE_RET_STR(GUEST_MSG_CANCEL);
     522        RT_CASE_RET_STR(GUEST_DISCONNECTED);
     523        RT_CASE_RET_STR(GUEST_MSG_FILTER_SET);
     524        RT_CASE_RET_STR(GUEST_MSG_FILTER_UNSET);
     525        RT_CASE_RET_STR(GUEST_MSG_PEEK_NOWAIT);
     526        RT_CASE_RET_STR(GUEST_MSG_PEEK_WAIT);
     527        RT_CASE_RET_STR(GUEST_MSG_GET);
     528        RT_CASE_RET_STR(GUEST_MSG_SKIP_OLD);
     529        RT_CASE_RET_STR(GUEST_MSG_REPLY);
     530        RT_CASE_RET_STR(GUEST_MSG_PROGRESS_UPDATE);
     531        RT_CASE_RET_STR(GUEST_MSG_SKIP);
     532        RT_CASE_RET_STR(GUEST_MAKE_ME_MASTER);
     533        RT_CASE_RET_STR(GUEST_SESSION_PREPARE);
     534        RT_CASE_RET_STR(GUEST_SESSION_CANCEL_PREPARED);
     535        RT_CASE_RET_STR(GUEST_SESSION_ACCEPT);
     536        RT_CASE_RET_STR(GUEST_SESSION_NOTIFY);
     537        RT_CASE_RET_STR(GUEST_SESSION_CLOSE);
     538        RT_CASE_RET_STR(GUEST_EXEC_OUTPUT);
     539        RT_CASE_RET_STR(GUEST_EXEC_STATUS);
     540        RT_CASE_RET_STR(GUEST_EXEC_INPUT_STATUS);
     541        RT_CASE_RET_STR(GUEST_EXEC_IO_NOTIFY);
     542        RT_CASE_RET_STR(GUEST_DIR_NOTIFY);
     543        RT_CASE_RET_STR(GUEST_FILE_NOTIFY);
     544    }
     545    return "Unknown";
     546}
     547
    375548
    376549/**
Note: See TracChangeset for help on using the changeset viewer.

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