VirtualBox

Changeset 76958 in vbox for trunk/include/VBox/HostServices


Ignore:
Timestamp:
Jan 23, 2019 6:23:04 PM (6 years ago)
Author:
vboxsync
Message:

Guest Control: Unifying terminology for (client/host) commands, functions and messages; it's all about messages now. Renaming, no functional changes.

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r76585 r76958  
    8787typedef struct VBoxGuestCtrlHostCbCtx
    8888{
    89     /** HGCM Function number. */
    90     uint32_t uFunction;
     89    /** HGCM message number. */
     90    uint32_t uMessage;
    9191    /** The context ID. */
    9292    uint32_t uContextID;
    … …  
    126126
    127127/**
    128  * The service functions which are callable by host.
    129  */
    130 enum eHostFn
     128 * The service messages which are callable by host.
     129 */
     130enum eHostMsg
    131131{
    132132    /**
    133133     * The host asks the client to cancel all pending waits and exit.
    134134     */
    135     HOST_CANCEL_PENDING_WAITS = 0,
     135    HOST_MSG_CANCEL_PENDING_WAITS = 0,
    136136    /**
    137137     * The host wants to create a guest session.
    138138     */
    139     HOST_SESSION_CREATE = 20,
     139    HOST_MSG_SESSION_CREATE = 20,
    140140    /**
    141141     * The host wants to close a guest session.
    142142     */
    143     HOST_SESSION_CLOSE = 21,
     143    HOST_MSG_SESSION_CLOSE = 21,
    144144    /**
    145145     * The host wants to execute something in the guest. This can be a command line
    146146     * or starting a program.
    147      ** Note: Legacy (VBox < 4.3) command.
    148      */
    149     HOST_EXEC_CMD = 100,
     147     ** Note: Legacy (VBox < 4.3) message.
     148     */
     149    HOST_MSG_EXEC_CMD = 100,
    150150    /**
    151151     * Sends input data for stdin to a running process executed by HOST_EXEC_CMD.
    152      ** Note: Legacy (VBox < 4.3) command.
    153      */
    154     HOST_EXEC_SET_INPUT = 101,
     152     ** Note: Legacy (VBox < 4.3) message.
     153     */
     154    HOST_MSG_EXEC_SET_INPUT = 101,
    155155    /**
    156156     * Gets the current status of a running process, e.g.
    157157     * new data on stdout/stderr, process terminated etc.
    158      * @note Legacy (VBox < 4.3) command.
    159      */
    160     HOST_EXEC_GET_OUTPUT = 102,
     158     * @note Legacy (VBox < 4.3) message.
     159     */
     160    HOST_MSG_EXEC_GET_OUTPUT = 102,
    161161    /**
    162162     * Terminates a running guest process.
    163163     */
    164     HOST_EXEC_TERMINATE = 110,
     164    HOST_MSG_EXEC_TERMINATE = 110,
    165165    /**
    166166     * Waits for a certain event to happen. This can be an input, output
    167167     * or status event.
    168168     */
    169     HOST_EXEC_WAIT_FOR = 120,
     169    HOST_MSG_EXEC_WAIT_FOR = 120,
    170170    /**
    171171     * Opens a guest file.
    172172     */
    173     HOST_FILE_OPEN = 240,
     173    HOST_MSG_FILE_OPEN = 240,
    174174    /**
    175175     * Closes a guest file.
    176176     */
    177     HOST_FILE_CLOSE = 241,
     177    HOST_MSG_FILE_CLOSE = 241,
    178178    /**
    179179     * Reads from an opened guest file.
    180180     */
    181     HOST_FILE_READ = 250,
     181    HOST_MSG_FILE_READ = 250,
    182182    /**
    183183     * Reads from an opened guest file at
    184184     * a specified offset.
    185185     */
    186     HOST_FILE_READ_AT = 251,
     186    HOST_MSG_FILE_READ_AT = 251,
    187187    /**
    188188     * Write to an opened guest file.
    189189     */
    190     HOST_FILE_WRITE = 260,
     190    HOST_MSG_FILE_WRITE = 260,
    191191    /**
    192192     * Write to an opened guest file at
    193193     * a specified offset.
    194194     */
    195     HOST_FILE_WRITE_AT = 261,
     195    HOST_MSG_FILE_WRITE_AT = 261,
    196196    /**
    197197     * Changes the read & write position of an opened guest file.
    198198     */
    199     HOST_FILE_SEEK = 270,
     199    HOST_MSG_FILE_SEEK = 270,
    200200    /**
    201201     * Gets the current file position of an opened guest file.
    202202     */
    203     HOST_FILE_TELL = 271,
     203    HOST_MSG_FILE_TELL = 271,
    204204    /**
    205205     * Removes a directory on the guest.
    206206     */
    207     HOST_DIR_REMOVE = 320,
     207    HOST_MSG_DIR_REMOVE = 320,
    208208    /**
    209209     * Renames a path on the guest.
    210210     */
    211     HOST_PATH_RENAME = 330,
     211    HOST_MSG_PATH_RENAME = 330,
    212212    /**
    213213     * Retrieves the user's documents directory.
    214214     */
    215     HOST_PATH_USER_DOCUMENTS = 331,
     215    HOST_MSG_PATH_USER_DOCUMENTS = 331,
    216216    /**
    217217     * Retrieves the user's home directory.
    218218     */
    219     HOST_PATH_USER_HOME = 332
     219    HOST_MSG_PATH_USER_HOME = 332
    220220};
    221221
    222222
    223223/**
    224  * Translates a guest control host function function enum to at string.
     224 * Translates a guest control host message enum to a string.
     225 *
    225226 * @returns Enum string name.
    226  * @param   enmFunction     The function name to translate.
    227  */
    228 DECLINLINE(const char *) GstCtrlHostFnName(enum eHostFn enmFunction)
    229 {
    230     switch (enmFunction)
     227 * @param   enmMsg              The message to translate.
     228 */
     229DECLINLINE(const char *) GstCtrlHostMsgtoStr(enum eHostMsg enmMsg)
     230{
     231    switch (enmMsg)
    231232    {
    232         RT_CASE_RET_STR(HOST_CANCEL_PENDING_WAITS);
    233         RT_CASE_RET_STR(HOST_SESSION_CREATE);
    234         RT_CASE_RET_STR(HOST_SESSION_CLOSE);
    235         RT_CASE_RET_STR(HOST_EXEC_CMD);
    236         RT_CASE_RET_STR(HOST_EXEC_SET_INPUT);
    237         RT_CASE_RET_STR(HOST_EXEC_GET_OUTPUT);
    238         RT_CASE_RET_STR(HOST_EXEC_TERMINATE);
    239         RT_CASE_RET_STR(HOST_EXEC_WAIT_FOR);
    240         RT_CASE_RET_STR(HOST_FILE_OPEN);
    241         RT_CASE_RET_STR(HOST_FILE_CLOSE);
    242         RT_CASE_RET_STR(HOST_FILE_READ);
    243         RT_CASE_RET_STR(HOST_FILE_READ_AT);
    244         RT_CASE_RET_STR(HOST_FILE_WRITE);
    245         RT_CASE_RET_STR(HOST_FILE_WRITE_AT);
    246         RT_CASE_RET_STR(HOST_FILE_SEEK);
    247         RT_CASE_RET_STR(HOST_FILE_TELL);
    248         RT_CASE_RET_STR(HOST_DIR_REMOVE);
    249         RT_CASE_RET_STR(HOST_PATH_RENAME);
    250         RT_CASE_RET_STR(HOST_PATH_USER_DOCUMENTS);
    251         RT_CASE_RET_STR(HOST_PATH_USER_HOME);
     233        RT_CASE_RET_STR(HOST_MSG_CANCEL_PENDING_WAITS);
     234        RT_CASE_RET_STR(HOST_MSG_SESSION_CREATE);
     235        RT_CASE_RET_STR(HOST_MSG_SESSION_CLOSE);
     236        RT_CASE_RET_STR(HOST_MSG_EXEC_CMD);
     237        RT_CASE_RET_STR(HOST_MSG_EXEC_SET_INPUT);
     238        RT_CASE_RET_STR(HOST_MSG_EXEC_GET_OUTPUT);
     239        RT_CASE_RET_STR(HOST_MSG_EXEC_TERMINATE);
     240        RT_CASE_RET_STR(HOST_MSG_EXEC_WAIT_FOR);
     241        RT_CASE_RET_STR(HOST_MSG_FILE_OPEN);
     242        RT_CASE_RET_STR(HOST_MSG_FILE_CLOSE);
     243        RT_CASE_RET_STR(HOST_MSG_FILE_READ);
     244        RT_CASE_RET_STR(HOST_MSG_FILE_READ_AT);
     245        RT_CASE_RET_STR(HOST_MSG_FILE_WRITE);
     246        RT_CASE_RET_STR(HOST_MSG_FILE_WRITE_AT);
     247        RT_CASE_RET_STR(HOST_MSG_FILE_SEEK);
     248        RT_CASE_RET_STR(HOST_MSG_FILE_TELL);
     249        RT_CASE_RET_STR(HOST_MSG_DIR_REMOVE);
     250        RT_CASE_RET_STR(HOST_MSG_PATH_RENAME);
     251        RT_CASE_RET_STR(HOST_MSG_PATH_USER_DOCUMENTS);
     252        RT_CASE_RET_STR(HOST_MSG_PATH_USER_HOME);
    252253    }
    253254    return "Unknown";
    … …  
    256257
    257258/**
    258  * The service functions which are called by guest.
     259 * The service messages which are callable by the guest.
    259260 *
    260  * @note The function numbers cannot be changed.  Please use the first non-zero
    261  *       number that's not in use when adding new functions.
     261 * @note The message numbers cannot be changed.  Please use the first non-zero
     262 *       number that's not in use when adding new messages.
    262263 *
    263  * @note Remember to update service.cpp when adding new functions/events for
    264  *       Main, as it validates all incoming commands before passing them on.
    265  */
    266 enum eGuestFn
     264 * @note Remember to update service.cpp when adding new messages for Main,
     265 *       as it validates all incoming messages before passing them on.
     266 */
     267enum eGuestMsg
    267268{
    268269    /** Guest waits for a new message the host wants to process on the guest side.
    269270     * This is a blocking call and can be deferred.
    270271     *
    271      * @note This command is rather odd.  The above description isn't really
     272     * @note This message is rather odd.  The above description isn't really
    272273     *       correct.  Yes, it (1) waits for a new message and will return the
    273274     *       mesage number and parameter count when one is available.   However, it
    … …  
    303304     *
    304305     * @note This is a host side notification message that has no business in this
    305      *       enum.  The guest cannot use this function number, host will reject it.
    306      */
    307     GUEST_DISCONNECTED = 3,
     306     *       enum.  The guest cannot use this message number, host will reject it.
     307     */
     308    GUEST_MSG_DISCONNECTED = 3,
    308309    /** Sets a message filter to only get messages which have a certain
    309310     * context ID scheme (that is, a specific session, object etc).
    … …  
    391392     * This skips the current message, replying to the main backend as best it can.
    392393     * Takes between zero and two parameters.  The first parameter is the 32-bit
    393      * VBox status code to pass onto Main when skipping the command, defaults to
     394     * VBox status code to pass onto Main when skipping the message, defaults to
    394395     * VERR_NOT_SUPPORTED.  The second parameter is the 32-bit message ID of the
    395      * command to skip, by default whatever is first in the queue is removed.  This
     396     * message to skip, by default whatever is first in the queue is removed.  This
    396397     * is also the case if UINT32_MAX is specified.
    397398     *
    … …  
    407408     * Skips the current assigned message returned by GUEST_MSG_WAIT.
    408409     * Needed for telling the host service to not keep stale
    409      * host commands in the queue.
     410     * host messages in the queue.
    410411     * @deprecated  Replaced by GUEST_MSG_SKIP.
    411412     */
    … …  
    433434     * @since   6.0
    434435     */
    435     GUEST_MAKE_ME_MASTER = 13,
     436    GUEST_MSG_MAKE_ME_MASTER = 13,
    436437    /** Prepares the starting of a session.
    437438     *
    … …  
    455456     * @since   6.0
    456457     */
    457     GUEST_SESSION_PREPARE = 14,
     458    GUEST_MSG_SESSION_PREPARE = 14,
    458459    /** Cancels a prepared session.
    459460     *
    … …  
    470471     * @since   6.0
    471472     */
    472     GUEST_SESSION_CANCEL_PREPARED = 15,
     473    GUEST_MSG_SESSION_CANCEL_PREPARED = 15,
    473474    /** Accepts a prepared session.
    474475     *
    … …  
    490491     * @since   6.0
    491492     */
    492     GUEST_SESSION_ACCEPT = 16,
     493    GUEST_MSG_SESSION_ACCEPT = 16,
    493494    /**
    494495     * Guest reports back a guest session status.
    495496     * @todo proper docs.
    496497     */
    497     GUEST_SESSION_NOTIFY = 20,
     498    GUEST_MSG_SESSION_NOTIFY = 20,
    498499    /**
    499500     * Guest wants to close a specific guest session.
    500501     * @todo proper docs.
    501502     */
    502     GUEST_SESSION_CLOSE = 21,
     503    GUEST_MSG_SESSION_CLOSE = 21,
    503504
    504505    /**
    … …  
    506507     * @todo proper docs.
    507508     */
    508     GUEST_EXEC_OUTPUT = 100,
     509    GUEST_MSG_EXEC_OUTPUT = 100,
    509510    /**
    510511     * Guest sends a status update of an executed process to the host.
    511512     * @todo proper docs.
    512513     */
    513     GUEST_EXEC_STATUS = 101,
     514    GUEST_MSG_EXEC_STATUS = 101,
    514515    /**
    515516     * Guests sends an input status notification to the host.
    516517     * @todo proper docs.
    517518     */
    518     GUEST_EXEC_INPUT_STATUS = 102,
     519    GUEST_MSG_EXEC_INPUT_STATUS = 102,
    519520    /**
    520521     * Guest notifies the host about some I/O event. This can be
    … …  
    524525     * @todo proper docs.
    525526     */
    526     GUEST_EXEC_IO_NOTIFY = 210,
     527    GUEST_MSG_EXEC_IO_NOTIFY = 210,
    527528    /**
    528529     * Guest notifies the host about some directory event.
    529530     * @todo proper docs.
    530531     */
    531     GUEST_DIR_NOTIFY = 230,
     532    GUEST_MSG_DIR_NOTIFY = 230,
    532533    /**
    533534     * Guest notifies the host about some file event.
    534535     * @todo proper docs.
    535536     */
    536     GUEST_FILE_NOTIFY = 240
     537    GUEST_MSG_FILE_NOTIFY = 240
    537538};
    538539
    539540/**
    540  * Translates a guest control host function function enum to at string.
     541 * Translates a guest control guest message enum to a string.
     542 *
    541543 * @returns Enum string name.
    542  * @param   enmFunction     The function name to translate.
    543  */
    544 DECLINLINE(const char *) GstCtrlGuestFnName(enum eGuestFn enmFunction)
    545 {
    546     switch (enmFunction)
     544 * @param   enmMsg              The message to translate.
     545 */
     546DECLINLINE(const char *) GstCtrlGuestMsgToStr(enum eGuestMsg enmMsg)
     547{
     548    switch (enmMsg)
    547549    {
    548550        RT_CASE_RET_STR(GUEST_MSG_WAIT);
    549551        RT_CASE_RET_STR(GUEST_MSG_CANCEL);
    550         RT_CASE_RET_STR(GUEST_DISCONNECTED);
     552        RT_CASE_RET_STR(GUEST_MSG_DISCONNECTED);
    551553        RT_CASE_RET_STR(GUEST_MSG_FILTER_SET);
    552554        RT_CASE_RET_STR(GUEST_MSG_FILTER_UNSET);
    … …  
    558560        RT_CASE_RET_STR(GUEST_MSG_PROGRESS_UPDATE);
    559561        RT_CASE_RET_STR(GUEST_MSG_SKIP);
    560         RT_CASE_RET_STR(GUEST_MAKE_ME_MASTER);
    561         RT_CASE_RET_STR(GUEST_SESSION_PREPARE);
    562         RT_CASE_RET_STR(GUEST_SESSION_CANCEL_PREPARED);
    563         RT_CASE_RET_STR(GUEST_SESSION_ACCEPT);
    564         RT_CASE_RET_STR(GUEST_SESSION_NOTIFY);
    565         RT_CASE_RET_STR(GUEST_SESSION_CLOSE);
    566         RT_CASE_RET_STR(GUEST_EXEC_OUTPUT);
    567         RT_CASE_RET_STR(GUEST_EXEC_STATUS);
    568         RT_CASE_RET_STR(GUEST_EXEC_INPUT_STATUS);
    569         RT_CASE_RET_STR(GUEST_EXEC_IO_NOTIFY);
    570         RT_CASE_RET_STR(GUEST_DIR_NOTIFY);
    571         RT_CASE_RET_STR(GUEST_FILE_NOTIFY);
     562        RT_CASE_RET_STR(GUEST_MSG_MAKE_ME_MASTER);
     563        RT_CASE_RET_STR(GUEST_MSG_SESSION_PREPARE);
     564        RT_CASE_RET_STR(GUEST_MSG_SESSION_CANCEL_PREPARED);
     565        RT_CASE_RET_STR(GUEST_MSG_SESSION_ACCEPT);
     566        RT_CASE_RET_STR(GUEST_MSG_SESSION_NOTIFY);
     567        RT_CASE_RET_STR(GUEST_MSG_SESSION_CLOSE);
     568        RT_CASE_RET_STR(GUEST_MSG_EXEC_OUTPUT);
     569        RT_CASE_RET_STR(GUEST_MSG_EXEC_STATUS);
     570        RT_CASE_RET_STR(GUEST_MSG_EXEC_INPUT_STATUS);
     571        RT_CASE_RET_STR(GUEST_MSG_EXEC_IO_NOTIFY);
     572        RT_CASE_RET_STR(GUEST_MSG_DIR_NOTIFY);
     573        RT_CASE_RET_STR(GUEST_MSG_FILE_NOTIFY);
    572574    }
    573575    return "Unknown";
    … …  
    655657
    656658/**
    657  * Waits for a host command to arrive. The structure then contains the
     659 * Waits for a host message to arrive. The structure then contains the
    658660 * actual message type + required number of parameters needed to successfully
    659  * retrieve that host command (in a next round).
    660  */
    661 typedef struct HGCMMsgCmdWaitFor
    662 {
    663     VBGLIOCHGCMCALL hdr;
    664     /**
    665      * The returned command the host wants to
    666      * run on the guest.
    667      */
     661 * retrieve that host message (in a next round).
     662 */
     663typedef struct HGCMMsgWaitFor
     664{
     665    VBGLIOCHGCMCALL hdr;
     666    /** The returned message the host wants to run on the guest. */
    668667    HGCMFunctionParameter msg;       /* OUT uint32_t */
    669668    /** Number of parameters the message needs. */
    670669    HGCMFunctionParameter num_parms; /* OUT uint32_t */
    671 } HGCMMsgCmdWaitFor;
    672 
    673 /**
    674  * Asks the guest control host service to set a command
     670} HGCMMsgWaitFor;
     671
     672/**
     673 * Asks the guest control host service to set a message
    675674 * filter for this client. This filter will then only
    676675 * deliver messages to the client which match the
    677676 * wanted context ID (ranges).
    678677 */
    679 typedef struct HGCMMsgCmdFilterSet
    680 {
    681     VBGLIOCHGCMCALL hdr;
    682     /** Value to filter for after filter mask
    683      *  was applied. */
     678typedef struct HGCMMsgFilterSet
     679{
     680    VBGLIOCHGCMCALL hdr;
     681    /** Value to filter for after filter mask was applied. */
    684682    HGCMFunctionParameter value;         /* IN uint32_t */
    685683    /** Mask to add to the current set filter. */
    … …  
    689687    /** Filter flags; currently unused. */
    690688    HGCMFunctionParameter flags;         /* IN uint32_t */
    691 } HGCMMsgCmdFilterSet;
     689} HGCMMsgFilterSet;
    692690
    693691/**
    … …  
    695693 * a previously set message filter again.
    696694 */
    697 typedef struct HGCMMsgCmdFilterUnset
     695typedef struct HGCMMsgFilterUnset
    698696{
    699697    VBGLIOCHGCMCALL hdr;
    700698    /** Unset flags; currently unused. */
    701699    HGCMFunctionParameter flags;    /* IN uint32_t */
    702 } HGCMMsgCmdFilterUnset;
     700} HGCMMsgFilterUnset;
    703701
    704702/**
    705703 * Asks the guest control host service to skip the
    706  * currently assigned host command returned by
     704 * currently assigned host message returned by
    707705 * VbglR3GuestCtrlMsgWaitFor().
    708706 */
    709 typedef struct HGCMMsgCmdSkip
     707typedef struct HGCMMsgSkip
    710708{
    711709    VBGLIOCHGCMCALL hdr;
    712710    /** Skip flags; currently unused. */
    713711    HGCMFunctionParameter flags;    /* IN uint32_t */
    714 } HGCMMsgCmdSkip;
     712} HGCMMsgSkip;
    715713
    716714/**
    … …  
    723721} HGCMMsgCancelPendingWaits;
    724722
    725 typedef struct HGCMMsgCmdReply
     723typedef struct HGCMMsgReply
    726724{
    727725    VBGLIOCHGCMCALL hdr;
    … …  
    734732    /** Optional payload to this reply. */
    735733    HGCMFunctionParameter payload;
    736 } HGCMMsgCmdReply;
     734} HGCMMsgReply;
    737735
    738736/**
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