VirtualBox

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


Ignore:
Timestamp:
Feb 10, 2023 3:10:50 PM (2 years ago)
Author:
vboxsync
Message:

Guest Control: Initial commit (work in progress, disabled by default). bugref:9783

IGuestDirectory:

Added new attributes id + status + an own event source. Also added for rewind support via rewind().

New event types for guest directory [un]registration, state changes and entry reads.

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r98103 r98526  
    4141#endif
    4242
     43#include <iprt/assert.h>
     44#include <VBox/hgcmsvc.h>
     45
    4346#include <VBox/VMMDevCoreTypes.h>
     47#include <VBox/GuestHost/GuestControl.h>
    4448#include <VBox/VBoxGuestCoreTypes.h>
    45 #include <VBox/hgcmsvc.h>
    46 #include <iprt/assert.h>
    4749
    4850/* Everything defined in this file lives in this namespace. */
    … …  
    200202     * Gets the current file position of an opened guest file.
    201203     */
    202     HOST_MSG_FILE_TELL,
     204    HOST_MSG_FILE_TELL = 271,
    203205    /**
    204206     * Changes the file size.
    205207     */
    206     HOST_MSG_FILE_SET_SIZE,
     208    HOST_MSG_FILE_SET_SIZE = 272,
     209#ifdef VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS
     210    /**
     211     * Removes a file on the guest.
     212     */
     213    HOST_MSG_FILE_REMOVE = 273,
     214    /**
     215     * Opens (creates) a directory on the guest.
     216     */
     217    HOST_MSG_DIR_OPEN = 310,
     218    /**
     219     * Closes a directory on the guest.
     220     */
     221    HOST_MSG_DIR_CLOSE = 311,
     222    /**
     223     * Reads the next directory entry on the guest.
     224     */
     225    HOST_MSG_DIR_READ = 312,
     226    /**
     227     * Rewinds and restarts the directory reading on the guest.
     228     */
     229    HOST_MSG_DIR_REWIND = 313,
     230    /**
     231     * Creates a directory on the guest.
     232     */
     233    HOST_MSG_DIR_CREATE = 314,
     234#endif /* VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS */
    207235    /**
    208236     * Removes a directory on the guest.
    … …  
    216244     * Retrieves the user's documents directory.
    217245     */
    218     HOST_MSG_PATH_USER_DOCUMENTS,
     246    HOST_MSG_PATH_USER_DOCUMENTS = 331,
    219247    /**
    220248     * Retrieves the user's home directory.
    221249     */
    222     HOST_MSG_PATH_USER_HOME,
     250    HOST_MSG_PATH_USER_HOME = 332,
    223251    /**
    224252     * Issues a shutdown / reboot of the guest OS.
    225253     */
    226     HOST_MSG_SHUTDOWN,
    227 
     254    HOST_MSG_SHUTDOWN = 333,
     255#ifdef VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS
     256    /**
     257     * Retrieves information about a file system object.
     258     */
     259    HOST_MSG_FS_QUERY_INFO = 334,
     260    /**
     261     * Creates a temporary file or directory.
     262     */
     263    HOST_MSG_FS_CREATE_TEMP = 335,
     264#endif /* VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS */
    228265    /** Blow the type up to 32-bits. */
    229266    HOST_MSG_32BIT_HACK = 0x7fffffff
    … …  
    258295        RT_CASE_RET_STR(HOST_MSG_FILE_TELL);
    259296        RT_CASE_RET_STR(HOST_MSG_FILE_SET_SIZE);
     297#ifdef VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS
     298        RT_CASE_RET_STR(HOST_MSG_FILE_REMOVE);
     299        RT_CASE_RET_STR(HOST_MSG_DIR_OPEN);
     300        RT_CASE_RET_STR(HOST_MSG_DIR_CLOSE);
     301        RT_CASE_RET_STR(HOST_MSG_DIR_READ);
     302        RT_CASE_RET_STR(HOST_MSG_DIR_REWIND);
     303        RT_CASE_RET_STR(HOST_MSG_DIR_CREATE);
     304#endif /* VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS */
    260305        RT_CASE_RET_STR(HOST_MSG_DIR_REMOVE);
    261306        RT_CASE_RET_STR(HOST_MSG_PATH_RENAME);
    … …  
    263308        RT_CASE_RET_STR(HOST_MSG_PATH_USER_HOME);
    264309        RT_CASE_RET_STR(HOST_MSG_SHUTDOWN);
     310#ifdef VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS
     311        RT_CASE_RET_STR(HOST_MSG_FS_QUERY_INFO);
     312        RT_CASE_RET_STR(HOST_MSG_FS_CREATE_TEMP);
     313#endif /* VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS */
    265314        RT_CASE_RET_STR(HOST_MSG_32BIT_HACK);
    266315    }
    … …  
    579628     * @todo proper docs.
    580629     */
    581     GUEST_MSG_FILE_NOTIFY = 240
     630    GUEST_MSG_FILE_NOTIFY = 240,
     631#ifdef VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS
     632    /**
     633     *  Guest notifies the host about some file system event.
     634     *
     635     * @retval  VINF_SUCCESS on success.
     636     * @retval  VERR_INVALID_CLIENT_ID
     637     * @retval  VERR_WRONG_PARAMETER_COUNT
     638     * @retval  VERR_WRONG_PARAMETER_TYPE
     639     * @since   7.1
     640     */
     641    GUEST_MSG_FS_NOTIFY  = 241
     642#endif
    582643};
    583644
    … …  
    618679        RT_CASE_RET_STR(GUEST_MSG_DIR_NOTIFY);
    619680        RT_CASE_RET_STR(GUEST_MSG_FILE_NOTIFY);
     681#ifdef VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS
     682        RT_CASE_RET_STR(GUEST_MSG_FS_NOTIFY);
     683#endif
    620684    }
    621685    return "Unknown";
    622686}
    623 
    624687
    625688/**
    … …  
    650713/**
    651714 * Guest directory notification types.
    652  * @sa HGCMMsgDirNotify.
     715 * @sa HGCMMsgReplyDirNotify.
    653716 */
    654717enum GUEST_DIR_NOTIFYTYPE
    … …  
    661724    /** Guest directory closed. */
    662725    GUEST_DIR_NOTIFYTYPE_CLOSE = 20,
     726#ifdef VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS
     727    /** Guest directory read. */
     728    GUEST_DIR_NOTIFYTYPE_READ = 21,
     729    /** Guest directory was rewind. */
     730    GUEST_DIR_NOTIFYTYPE_REWIND = 22,
     731#endif
    663732    /** Information about an open guest directory. */
    664733    GUEST_DIR_NOTIFYTYPE_INFO = 40,
    … …  
    686755    GUEST_FILE_NOTIFYTYPE_TELL = 60,
    687756    GUEST_FILE_NOTIFYTYPE_SET_SIZE
     757};
     758
     759/**
     760 * Guest file system notification types.
     761 */
     762enum GUEST_FS_NOTIFYTYPE
     763{
     764    /** Unknown fs notification type; do not use. */
     765    GUEST_FS_NOTIFYTYPE_UNKNOWN     = 0,
     766    /** File system query information notification from the guest.
     767     *  @since 7.1 */
     768    GUEST_FS_NOTIFYTYPE_QUERY_INFO  = 2,
     769    /** Temporary directory creation notification from the guest.
     770     *  @since 7.1 */
     771    GUEST_FS_NOTIFYTYPE_CREATE_TEMP = 1,
    688772};
    689773
    … …  
    716800/** Supports shutting down / rebooting the guest. */
    717801#define VBOX_GUESTCTRL_GF_0_SHUTDOWN                RT_BIT_64(3)
     802/** VBoxService' toolbox commands (vbox_rm, vbox_stat, ++) are supported by
     803 * dedicated built-in HGCM commands.
     804 *
     805 * The toolbox commands now are being marked as deprecated.
     806 * @since 7.1 */
     807# define VBOX_GUESTCTRL_GF_0_TOOLBOX_AS_CMDS        RT_BIT_64(4)
    718808/** Bit that must be set in the 2nd parameter, will be cleared if the host reponds
    719809 * correctly (old hosts might not). */
    … …  
    804894} HGCMMsgCancelPendingWaits;
    805895
    806 typedef struct HGCMMsgReply
     896/**
     897 * Generic reply header for reply-based messages.
     898 *
     899 * @note Be careful when changing this, as older Guest Additions might depend on this
     900 *       and other stuff can break, too. So better leave this alone.
     901 */
     902typedef struct HGCMReplyHdr
    807903{
    808904    VBGLIOCHGCMCALL hdr;
    … …  
    813909    /** IPRT result of overall operation. */
    814910    HGCMFunctionParameter rc;
    815     /** Optional payload to this reply. */
     911} HGCMReplyHdr;
     912
     913/** Number of HGCM parameters the HGCMReplyHdr has. */
     914#define GSTCTL_HGCM_REPLY_HDR_PARMS     3
     915
     916/**
     917 * Generic reply message from guest to the host.
     918 */
     919typedef struct HGCMMsgReply
     920{
     921    VBGLIOCHGCMCALL hdr;
     922    /** Context ID. */
     923    HGCMFunctionParameter context;
     924    /** Message type. */
     925    HGCMFunctionParameter type;
     926    /** IPRT result of overall operation. */
     927    HGCMFunctionParameter rc;
     928    /** Optional payload to this reply
     929     *  Uses the REPLY_PAYLOAD_XXX structs. */
    816930    HGCMFunctionParameter payload;
    817931} HGCMMsgReply;
     932
     933#ifdef VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS
     934/**
     935 * Creates a temporary directory / file on the guest.
     936 */
     937typedef struct HGCMMsgFsCreateTemp
     938{
     939    VBGLIOCHGCMCALL hdr;
     940    /** Context ID. */
     941    HGCMFunctionParameter context;
     942    /** Template name to use for file/directory creation.
     943     *  If \a tmpdir is set, this path will be relative to \a tmpdir and  must not be an absolute path. */
     944    HGCMFunctionParameter template_name;
     945    /** Temporary directory to use.
     946     *  If empty, the guest OS' temporary directory will be determined via IPRT on the guest side. */
     947    HGCMFunctionParameter tmpdir;
     948    /** Creation flags.
     949     *  See GSTCTL_CREATETEMP_F_XXX. */
     950    HGCMFunctionParameter flags;
     951    /** File mode to use for creation (ignored if GSTCTL_CREATETEMP_F_SECURE is defined).
     952     *  See GSTCTL_CREATETEMP_F_XXX. */
     953    HGCMFunctionParameter mode;
     954} HGCMMsgFsCreateTemp;
     955
     956/**
     957 * Queries information for a file system object on the guest.
     958 */
     959typedef struct HGCMMsgFsQueryInfo
     960{
     961    VBGLIOCHGCMCALL hdr;
     962    /** Context ID. */
     963    HGCMFunctionParameter context;
     964    /** Path to query information for. */
     965    HGCMFunctionParameter path;
     966    /** Additional file system attributes to lookup (GSTCTLFSOBJATTRADD). */
     967    HGCMFunctionParameter add_attributes;
     968    /** Flags (GSTCTL_QUERYINFO_F_XXX). */
     969    HGCMFunctionParameter flags;
     970} HGCMMsgFsQueryInfo;
     971#endif /* VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS */
    818972
    819973/**
    … …  
    8631017    HGCMFunctionParameter result;
    8641018} HGCMMsgSessionNotify;
     1019
     1020#ifdef VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS
     1021/**
     1022 * Opens a guest directory.
     1023 */
     1024typedef struct HGCMMsgDirOpen
     1025{
     1026    VBGLIOCHGCMCALL hdr;
     1027    /** Context ID. */
     1028    HGCMFunctionParameter context;
     1029    /** Path of directory to open. */
     1030    HGCMFunctionParameter path;
     1031    /** Filter string to use (wildcard style). */
     1032    HGCMFunctionParameter filter;
     1033    /** Filter type to use when walking the directory (GSTCTLDIRFILTER). */
     1034    HGCMFunctionParameter filter_type;
     1035    /** Directory open flags (GSTCTLDIR_F_XXX). */
     1036    HGCMFunctionParameter flags;
     1037} HGCMMsgDirOpen;
     1038
     1039/**
     1040 * Closes a guest directory.
     1041 */
     1042typedef struct HGCMMsgDirClose
     1043{
     1044    VBGLIOCHGCMCALL hdr;
     1045    /** Context ID. */
     1046    HGCMFunctionParameter context;
     1047    /** Directory handle to close. */
     1048    HGCMFunctionParameter handle;
     1049} HGCMMsgDirClose;
     1050
     1051/**
     1052 * Reads the next entry of a guest directory.
     1053 */
     1054typedef struct HGCMMsgDirRead
     1055{
     1056    VBGLIOCHGCMCALL hdr;
     1057    /** Context ID. */
     1058    HGCMFunctionParameter context;
     1059    /** Handle of directory listing to read the next entry for. */
     1060    HGCMFunctionParameter handle;
     1061    /** Custom directory entry size (in bytes) to use. */
     1062    HGCMFunctionParameter entry_size;
     1063    /** Additional directory attributes to use (GSTCTLFSOBJATTRADD). */
     1064    HGCMFunctionParameter add_attributes;
     1065    /** Directory reading flags. */
     1066    HGCMFunctionParameter flags;
     1067} HGCMMsgDirRead;
     1068
     1069/**
     1070 * Rewinds the listing of a guest directory.
     1071 */
     1072typedef struct HGCMMsgDirRewind
     1073{
     1074    VBGLIOCHGCMCALL hdr;
     1075    /** Context ID. */
     1076    HGCMFunctionParameter context;
     1077    /** Handle of directory listing to rewind. */
     1078    HGCMFunctionParameter handle;
     1079} HGCMMsgDirRewind;
     1080
     1081/**
     1082 * Creates a directory on the guest.
     1083 */
     1084typedef struct HGCMMsgDirCreate
     1085{
     1086    VBGLIOCHGCMCALL hdr;
     1087    /** Context ID. */
     1088    HGCMFunctionParameter context;
     1089    /** Path of directory to create. */
     1090    HGCMFunctionParameter path;
     1091    /** Creation mode. */
     1092    HGCMFunctionParameter mode;
     1093    /** Creation flags (GSTCTL_CREATEDIRECTORY_F_XXX). */
     1094    HGCMFunctionParameter flags;
     1095} HGCMMsgDirCreate;
     1096#endif /* VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS */
    8651097
    8661098typedef struct HGCMMsgPathRename
    … …  
    12141446} HGCMMsgFileSetSize;
    12151447
     1448/**
     1449 * Removes (deletes) a guest file.
     1450 *
     1451 * @since 7.1
     1452 */
     1453typedef struct HGCMMsgFileRemove
     1454{
     1455    VBGLIOCHGCMCALL       hdr;
     1456    /** UInt32: Context ID. */
     1457    HGCMFunctionParameter context;
     1458    /** File to open. */
     1459    HGCMFunctionParameter filename;
     1460} HGCMMsgFileRemove;
     1461
    12161462
    12171463/******************************************************************************
    … …  
    12781524typedef struct HGCMReplyDirNotify
    12791525{
    1280     VBGLIOCHGCMCALL hdr;
    1281     /** Context ID. */
    1282     HGCMFunctionParameter context;
    1283     /** Notification type. */
    1284     HGCMFunctionParameter type;
    1285     /** IPRT result of overall operation. */
    1286     HGCMFunctionParameter rc;
     1526    /** The generic reply header. */
     1527    HGCMReplyHdr reply_hdr;
     1528    /** Union based on \a reply_hdr.type. */
    12871529    union
    12881530    {
    1289         struct
    1290         {
    1291             /** Directory information. */
    1292             HGCMFunctionParameter objInfo;
    1293         } info;
     1531        /**
     1532         * Parameters used for \a type GUEST_DIR_NOTIFYTYPE_OPEN.
     1533         *
     1534         * @since 7.1
     1535         */
    12941536        struct
    12951537        {
    … …  
    12971539            HGCMFunctionParameter handle;
    12981540        } open;
    1299         struct
    1300         {
    1301             /** Current read directory entry. */
     1541        /**
     1542         * Parameters used for \a type GUEST_DIR_NOTIFYTYPE_READ.
     1543         *
     1544         * @since 7.1
     1545         */
     1546        struct
     1547        {
     1548            /** Current read directory entry (GSTCTLDIRENTRYEX). */
    13021549            HGCMFunctionParameter entry;
    1303             /** Extended entry object information. Optional. */
    1304             HGCMFunctionParameter objInfo;
     1550            /** Resolved user ID as a string (uid). */
     1551            HGCMFunctionParameter user;
     1552            /** Resolved group IDs as a string.
     1553             *
     1554             *  Multiple groups are delimited by "\r\n", whereas
     1555             *  the first group always is the primary group. */
     1556            HGCMFunctionParameter groups;
     1557            /** @todo ACL; not implemented yet.
     1558             * Windows ACL, defined in SDDL. */
     1559            HGCMFunctionParameter acl;
    13051560        } read;
    13061561    } u;
    13071562} HGCMReplyDirNotify;
    13081563
     1564/**
     1565 * Reply to a HOST_MSG_FS_QUERY_INFO or HOST_MSG_FS_CREATE_TEMP message.
     1566 *
     1567 * @since 7.1
     1568 */
     1569typedef struct HGCMReplyFsNotify
     1570{
     1571    /** The generic reply header. */
     1572    HGCMReplyHdr reply_hdr;
     1573    /** Union based on \a reply_hdr.type. */
     1574    union
     1575    {
     1576        /**
     1577         * Parameters used for \a type GUEST_FS_NOTIFYTYPE_QUERY_INFO.
     1578         *
     1579         * @since 7.1
     1580         */
     1581        struct
     1582        {
     1583            /** File system object information (GSTCTLFSOBJINFO). */
     1584            HGCMFunctionParameter obj_info;
     1585            /** Resolved user ID as a string (uid). */
     1586            HGCMFunctionParameter user;
     1587            /** Resolved group IDs as a string.
     1588             *
     1589             *  Multiple groups are delimited by "\r\n", whereas
     1590             *  the first group always is the primary group. */
     1591            HGCMFunctionParameter groups;
     1592            /** @todo ACL; not implemented yet.
     1593             * Windows ACL, defined in SDDL. */
     1594            HGCMFunctionParameter acl;
     1595        } queryinfo;
     1596        /**
     1597         * Parameters used for \a type GUEST_FS_NOTIFYTYPE_CREATE_TEMP.
     1598         *
     1599         * @since 7.1
     1600         */
     1601        struct
     1602        {
     1603            /** The create temporary file / directory when \a rc
     1604             *  indicates success. */
     1605            HGCMFunctionParameter path;
     1606        } createtemp;
     1607    } u;
     1608} HGCMReplyFsNotify;
    13091609#pragma pack ()
     1610
    13101611
    13111612/******************************************************************************
    … …  
    14211722        struct
    14221723        {
    1423             /** Size (in bytes) of directory information. */
    1424             uint32_t cbObjInfo;
    14251724            /** Pointer to directory information. */
    1426             void *pvObjInfo;
     1725            PGSTCTLFSOBJINFO pObjInfo;
    14271726        } info;
    14281727        struct
    … …  
    14351734        {
    14361735            /** Size (in bytes) of directory entry information. */
    1437             uint32_t cbEntry;
     1736            uint32_t          cbEntry;
    14381737            /** Pointer to directory entry information. */
    1439             void *pvEntry;
    1440             /** Size (in bytes) of directory entry object information. */
    1441             uint32_t cbObjInfo;
    1442             /** Pointer to directory entry object information. */
    1443             void *pvObjInfo;
     1738            GSTCTLDIRENTRYEX *pEntry;
    14441739        } read;
    14451740    } u;
    … …  
    14951790} CALLBACKDATA_FILE_NOTIFY, *PCALLBACKDATA_FILE_NOTIFY;
    14961791
     1792
     1793/*******************************************************************************
     1794* Payload structures for the generic reply message (HGCMMsgReply).             *
     1795*                                                                              *
     1796* The name suffix must match the host command name, e.g.                       *
     1797*     Host command HOST_MSG_FOO_BAR -> REPLY_PAYLOAD_FOO_BAR                   *
     1798*******************************************************************************/
     1799
     1800typedef struct REPLY_PAYLOAD_FS_QUERY_INFO
     1801{
     1802    GSTCTLFSOBJINFO objInfo;
     1803
     1804} REPLY_PAYLOAD_FS_QUERY_INFO;
    14971805} /* namespace guestControl */
    14981806
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