VirtualBox

Changeset 98526 in vbox for trunk/include


Ignore:
Timestamp:
Feb 10, 2023 3:10:50 PM (22 months 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.

Location:
trunk/include/VBox
Files:
4 edited

Legend:

Unmodified
Added
Removed

  • trunk/include/VBox/GuestHost/GuestControl.h

    r98103 r98526  
    4343#endif
    4444
     45#include <iprt/time.h>
    4546#include <iprt/types.h>
    4647
    … …  
    142143/** @} */
    143144
     145/** @name GSTCTL_CREATETEMP_F_XXX - Guest temporary directory/file creation flags.
     146 * @{
     147 */
     148/** Does not specify anything. */
     149#define GSTCTL_CREATETEMP_F_NONE            UINT32_C(0)
     150/** Creates a directory instead of a file. */
     151#define GSTCTL_CREATETEMP_F_DIRECTORY       RT_BIT(0)
     152/** Creates a secure temporary file / directory.
     153 *  Might not be supported on all (guest) OSes.
     154 *
     155 *  @sa IPRT's implementation of RTDirCreateTempSecure() / RTFileCreateTempSecumre(). */
     156#define GSTCTL_CREATETEMP_F_SECURE          RT_BIT(1)
     157/** Mask of valid flags. */
     158#define GSTCTL_CREATETEMP_F_VALID_MASK      UINT32_C(0x00000003)
     159/** @} */
     160
     161/** @name GSTCTL_CREATEDIRECTORY_F_XXX - Guest directory creation flags.
     162 * @{
     163 */
     164/** Does not specify anything. */
     165#define GSTCTL_CREATEDIRECTORY_F_NONE       UINT32_C(0)
     166/** Also creates parent directories if they don't exist yet. */
     167#define GSTCTL_CREATEDIRECTORY_F_PARENTS    RT_BIT(0)
     168/** Mask of valid flags. */
     169#define GSTCTL_CREATEDIRECTORY_F_VALID_MASK UINT32_C(0x00000001)
     170/** @} */
     171
    144172/** @name GUEST_SHUTDOWN_FLAG_XXX - Guest shutdown flags.
    145173 * Must match Main's GuestShutdownFlag_ definitions.
    … …  
    229257};
    230258
    231 
     259/**
     260 * Guest file system object -- additional information in a GSTCTLFSOBJATTR object.
     261 */
     262enum GSTCTLFSOBJATTRADD
     263{
     264    /** No additional information is available / requested. */
     265    GSTCTLFSOBJATTRADD_NOTHING = 1,
     266    /** The additional unix attributes (RTFSOBJATTR::u::Unix) are available /
     267     *  requested. */
     268    GSTCTLFSOBJATTRADD_UNIX,
     269    /** The additional unix attributes (RTFSOBJATTR::u::UnixOwner) are
     270     * available / requested. */
     271    GSTCTLFSOBJATTRADD_UNIX_OWNER,
     272    /** The additional unix attributes (RTFSOBJATTR::u::UnixGroup) are
     273     * available / requested. */
     274    GSTCTLFSOBJATTRADD_UNIX_GROUP,
     275    /** The additional extended attribute size (RTFSOBJATTR::u::EASize) is available / requested. */
     276    GSTCTLFSOBJATTRADD_EASIZE,
     277    /** The last valid item (inclusive).
     278     * The valid range is RTFSOBJATTRADD_NOTHING thru RTFSOBJATTRADD_LAST.  */
     279    GSTCTLFSOBJATTRADD_LAST = GSTCTLFSOBJATTRADD_EASIZE,
     280
     281    /** The usual 32-bit hack. */
     282    GSTCTLFSOBJATTRADD_32BIT_SIZE_HACK = 0x7fffffff
     283};
     284
     285/** The number of bytes reserved for the additional attribute union. */
     286#define GSTCTLFSOBJATTRUNION_MAX_SIZE       128
     287
     288/**
     289 * Additional Unix Attributes (GSTCTLFSOBJATTRADD_UNIX).
     290 */
     291typedef struct GSTCTLFSOBJATTRUNIX
     292{
     293    /** The user owning the filesystem object (st_uid).
     294     * This field is NIL_RTUID if not supported. */
     295    RTUID           uid;
     296
     297    /** The group the filesystem object is assigned (st_gid).
     298     * This field is NIL_RTGID if not supported. */
     299    RTGID           gid;
     300
     301    /** Number of hard links to this filesystem object (st_nlink).
     302     * This field is 1 if the filesystem doesn't support hardlinking or
     303     * the information isn't available.
     304     */
     305    uint32_t        cHardlinks;
     306
     307    /** The device number of the device which this filesystem object resides on (st_dev).
     308     * This field is 0 if this information is not available. */
     309    RTDEV           INodeIdDevice;
     310
     311    /** The unique identifier (within the filesystem) of this filesystem object (st_ino).
     312     * Together with INodeIdDevice, this field can be used as a OS wide unique id
     313     * when both their values are not 0.
     314     * This field is 0 if the information is not available.
     315     *
     316     * @remarks  The special '..' dir always shows up with 0 on NTFS/Windows. */
     317    RTINODE         INodeId;
     318
     319    /** User flags (st_flags).
     320     * This field is 0 if this information is not available. */
     321    uint32_t        fFlags;
     322
     323    /** The current generation number (st_gen).
     324     * This field is 0 if this information is not available. */
     325    uint32_t        GenerationId;
     326
     327    /** The device number of a character or block device type object (st_rdev).
     328     * This field is 0 if the file isn't of a character or block device type and
     329     * when the OS doesn't subscribe to the major+minor device idenfication scheme. */
     330    RTDEV           Device;
     331} GSTCTLFSOBJATTRUNIX;
     332
     333/**
     334 * Additional guest Unix attributes (GSTCTLFSOBJATTRADD_UNIX_OWNER).
     335 */
     336typedef struct GSTCTLFSOBJATTRUNIXOWNER
     337{
     338    /** The user owning the filesystem object (st_uid).
     339     * This field is NIL_RTUID if not supported. */
     340    RTUID           uid;
     341    /** The user name.
     342     * Empty if not available or not supported, truncated if too long. */
     343    char            szName[GSTCTLFSOBJATTRUNION_MAX_SIZE - sizeof(RTUID)];
     344} GSTCTLFSOBJATTRUNIXOWNER;
     345
     346/**
     347 * Additional guest Unix attributes (GSTCTLFSOBJATTRADD_UNIX_GROUP).
     348 */
     349typedef struct GSTCTLFSOBJATTRUNIXGROUP
     350{
     351    /** The user owning the filesystem object (st_uid).
     352     * This field is NIL_RTUID if not supported. */
     353    RTGID           gid;
     354    /** The group name.
     355     * Empty if not available or not supported, truncated if too long. */
     356    char            szName[GSTCTLFSOBJATTRUNION_MAX_SIZE - sizeof(RTGID)];
     357} GSTCTLFSOBJATTRUNIXGROUP;
     358
     359/**
     360 * Guest filesystem object attributes.
     361 */
     362#pragma pack(1)
     363typedef struct GSTCTLFSOBJATTR
     364{
     365    /** Mode flags (st_mode). RTFS_UNIX_*, RTFS_TYPE_*, and RTFS_DOS_*. */
     366    RTFMODE                     fMode;
     367
     368    /** The additional attributes available. */
     369    GSTCTLFSOBJATTRADD          enmAdditional;
     370
     371    /**
     372     * Additional attributes.
     373     *
     374     * Unless explicitly specified to an API, the API can provide additional
     375     * data as it is provided by the underlying OS.
     376     */
     377    union GSTCTLFSOBJATTRUNION
     378    {
     379        /** Additional Unix Attributes - GUEST_FSOBJATTRADD_UNIX. */
     380        GSTCTLFSOBJATTRUNIX         Unix;
     381        /** Additional Unix Owner Attributes - GUEST_FSOBJATTRADD_UNIX_OWNER. */
     382        GSTCTLFSOBJATTRUNIXOWNER    UnixOwner;
     383        /** Additional Unix Group Attributes - GUEST_FSOBJATTRADD_UNIX_GROUP. */
     384        GSTCTLFSOBJATTRUNIXGROUP    UnixGroup;
     385
     386        /**
     387         * Extended attribute size is available when RTFS_DOS_HAVE_EA_SIZE is set.
     388         */
     389        struct GSTCTLFSOBJATTREASIZE
     390        {
     391            /** Size of EAs. */
     392            RTFOFF          cb;
     393        } EASize;
     394        /** Reserved space. */
     395        uint8_t         abReserveSpace[128];
     396    } u;
     397} GSTCTLFSOBJATTR;
     398#pragma pack()
     399/** Pointer to a guest filesystem object attributes structure. */
     400typedef GSTCTLFSOBJATTR *PGSTCTLFSOBJATTR;
     401/** Pointer to a const guest filesystem object attributes structure. */
     402typedef const GSTCTLFSOBJATTR *PCGSTCTLFSOBJATTR;
     403
     404/** @name GSTCTL_QUERYINFO_F_XXX - Generic flags for querying guest file system information.
     405 * @{ */
     406/** No guest stat flags specified. */
     407#define GSTCTL_QUERYINFO_F_NONE               UINT32_C(0)
     408/** Last component: Work on the link. */
     409#define GSTCTL_QUERYINFO_F_ON_LINK            RT_BIT_32(0)
     410/** Last component: Follow if link. */
     411#define GSTCTL_QUERYINFO_F_FOLLOW_LINK        RT_BIT_32(1)
     412/** Don't allow symbolic links as part of the path.
     413 * @remarks this flag is currently not implemented and will be ignored. */
     414#define GSTCTL_QUERYINFO_F_NO_SYMLINKS        RT_BIT_32(2)
     415/** GSTCTL_QUERYINFO_F_XXX flag valid mask. */
     416#define GSTCTL_QUERYINFO_F_VALID_MASK         UINT32_C(0x00000007)
     417/** @} */
     418
     419/**
     420 * Filter option for HOST_MSG_DIR_OPEN.
     421 */
     422typedef enum GSTCTLDIRFILTER
     423{
     424    /** The usual invalid 0 entry. */
     425    GSTCTLDIRFILTER_INVALID = 0,
     426    /** No filter should be applied (and none was specified). */
     427    GSTCTLDIRFILTER_NONE,
     428    /** The Windows NT filter.
     429     * The following wildcard chars: *, ?, <, > and "
     430     * The matching is done on the uppercased strings.  */
     431    GSTCTLDIRFILTER_WINNT,
     432    /** The UNIX filter.
     433     * The following wildcard chars: *, ?, [..]
     434     * The matching is done on exact case. */
     435    GSTCTLDIRFILTER_UNIX,
     436    /** The UNIX filter, uppercased matching.
     437     * Same as GSTCTLDIRFILTER_UNIX except that the strings are uppercased before comparing. */
     438    GSTCTLDIRFILTER_UNIX_UPCASED,
     439
     440    /** The usual full 32-bit value. */
     441    GSTCTLDIRFILTER_32BIT_HACK = 0x7fffffff
     442} GSTCTLDIRFILTER;
     443
     444/** @name GSTCTLDIR_F_XXX - Directory flags for HOST_MSG_DIR_OPEN.
     445 * @{ */
     446/** Don't allow symbolic links as part of the path.
     447 * @remarks this flag is currently not implemented and will be ignored. */
     448#define GSTCTLDIR_F_NO_SYMLINKS     RT_BIT_32(0)
     449/** Deny relative opening of anything above this directory. */
     450#define GSTCTLDIR_F_DENY_ASCENT     RT_BIT_32(1)
     451/** Don't follow symbolic links in the final component. */
     452#define GSTCTLDIR_F_NO_FOLLOW       RT_BIT_32(2)
     453/** Long path hack: Don't apply RTPathAbs to the path. */
     454#define GSTCTLDIR_F_NO_ABS_PATH     RT_BIT_32(3)
     455/** Valid flag mask.   */
     456#define GSTCTLDIR_F_VALID_MASK      UINT32_C(0x0000000f)
     457
     458/**
     459 * Guest filesystem object information structure.
     460 *
     461 * This is returned by
     462 *     - GUEST_FS_NOTIFYTYPE_QUERY_INFO
     463 *     - GUEST_DIR_NOTIFYTYPE_READ
     464 */
     465#pragma pack(1)
     466typedef struct GSTCTLFSOBJINFO
     467{
     468   /** Logical size (st_size).
     469    * For normal files this is the size of the file.
     470    * For symbolic links, this is the length of the path name contained
     471    * in the symbolic link.
     472    * For other objects this fields needs to be specified.
     473    */
     474   RTFOFF           cbObject;
     475
     476   /** Disk allocation size (st_blocks * DEV_BSIZE). */
     477   RTFOFF           cbAllocated;
     478
     479   /** Time of last access (st_atime). */
     480   RTTIMESPEC       AccessTime;
     481
     482   /** Time of last data modification (st_mtime). */
     483   RTTIMESPEC       ModificationTime;
     484
     485   /** Time of last status change (st_ctime).
     486    * If not available this is set to ModificationTime.
     487    */
     488   RTTIMESPEC       ChangeTime;
     489
     490   /** Time of file birth (st_birthtime).
     491    * If not available this is set to ChangeTime.
     492    */
     493   RTTIMESPEC       BirthTime;
     494
     495   /** Attributes. */
     496   GSTCTLFSOBJATTR  Attr;
     497
     498} GSTCTLFSOBJINFO;
     499#pragma pack()
     500/** Pointer to a guest filesystem object information structure. */
     501typedef GSTCTLFSOBJINFO *PGSTCTLFSOBJINFO;
     502/** Pointer to a const guest filesystem object information structure. */
     503typedef const GSTCTLFSOBJINFO *PCGSTCTLFSOBJINFO;
     504
     505/**
     506 * Guest directory entry with extended information.
     507 *
     508 * This is inspired by IPRT + the PC interfaces.
     509 */
     510#pragma pack(1)
     511typedef struct GSTCTLDIRENTRYEX
     512{
     513    /** Full information about the guest object. */
     514    GSTCTLFSOBJINFO  Info;
     515    /** The length of the short field (number of RTUTF16 entries (not chars)).
     516     * It is 16-bit for reasons of alignment. */
     517    uint16_t        cwcShortName;
     518    /** The short name for 8.3 compatibility.
     519     * Empty string if not available.
     520     * Since the length is a bit tricky for a UTF-8 encoded name, and since this
     521     * is practically speaking only a windows thing, it is encoded as UCS-2. */
     522    RTUTF16         wszShortName[14];
     523    /** The length of the filename. */
     524    uint16_t        cbName;
     525    /** The filename. (no path)
     526     * Using the pcbDirEntry parameter of RTDirReadEx makes this field variable in size. */
     527    char            szName[260];
     528} GSTCTLDIRENTRYEX;
     529#pragma pack()
     530/** Pointer to a guest directory entry. */
     531typedef GSTCTLDIRENTRYEX *PGSTCTLDIRENTRYEX;
     532/** Pointer to a const guest directory entry. */
     533typedef GSTCTLDIRENTRYEX const *PCGSTCTLDIRENTRYEX;
    232534
    233535} /* namespace guestControl */

  • 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

  • trunk/include/VBox/VBoxGuestLib.h

    r98472 r98526  
    4040#  include <VBox/GuestHost/DragAndDrop.h>
    4141#  include <VBox/GuestHost/DragAndDropDefs.h>
     42# endif
     43# ifdef VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS
     44#  include <VBox/GuestHost/GuestControl.h>
     45   using namespace guestControl;
    4246# endif
    4347# ifdef VBOX_WITH_SHARED_CLIPBOARD
    … …  
    10791083VBGLR3DECL(int) VbglR3GuestCtrlSessionGetOpen(PVBGLR3GUESTCTRLCMDCTX pCtx, PVBGLR3GUESTCTRLSESSIONSTARTUPINFO *ppStartupInfo);
    10801084VBGLR3DECL(int) VbglR3GuestCtrlSessionGetClose(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t *pfFlags, uint32_t *pidSession);
     1085VBGLR3DECL(int) VbglR3GuestCtrlFileGetClose(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t *puHandle);
     1086VBGLR3DECL(int) VbglR3GuestCtrlFileGetRead(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t *puHandle, uint32_t *puToRead);
    10811087/* Guest path handling. */
    10821088VBGLR3DECL(int) VbglR3GuestCtrlPathGetRename(PVBGLR3GUESTCTRLCMDCTX pCtx, char *pszSource, uint32_t cbSource, char *pszDest,
    … …  
    10841090VBGLR3DECL(int) VbglR3GuestCtrlPathGetUserDocuments(PVBGLR3GUESTCTRLCMDCTX pCtx);
    10851091VBGLR3DECL(int) VbglR3GuestCtrlPathGetUserHome(PVBGLR3GUESTCTRLCMDCTX pCtx);
     1092#  ifdef VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS
     1093/** @name Guest Control file system functions.
     1094 * @{
     1095 */
     1096VBGLR3DECL(int) VbglR3GuestCtrlFsGetQueryInfo(PVBGLR3GUESTCTRLCMDCTX pCtx, char *pszPath, uint32_t cbPath, GSTCTLFSOBJATTRADD *penmAddAttrib, uint32_t *pfFlags);
     1097VBGLR3DECL(int) VbglR3GuestCtrlFsGetCreateTemp(PVBGLR3GUESTCTRLCMDCTX pCtx, char *pszTemplate, uint32_t cbTemplate, char *pszPath, uint32_t cbPath, uint32_t *pfFlags, uint32_t *pfMode);
     1098/** @} */
     1099#  endif
    10861100VBGLR3DECL(int) VbglR3GuestCtrlGetShutdown(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t *pfAction);
    10871101/* Guest process execution. */
    … …  
    10991113                                              uint32_t *puTimeoutMS);
    11001114/* Guest native directory handling. */
     1115#  ifdef VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS
     1116/** @name Guest Control directory functions.
     1117 * @{
     1118 */
     1119VBGLR3DECL(int) VbglR3GuestCtrlDirGetCreate(PVBGLR3GUESTCTRLCMDCTX pCtx, char *pszPath, uint32_t cbPath, uint32_t *pfMode, uint32_t *pfFlags);
     1120VBGLR3DECL(int) VbglR3GuestCtrlDirGetOpen(PVBGLR3GUESTCTRLCMDCTX pCtx, char *pszPath, uint32_t cbPath, uint32_t *pfFlags, GSTCTLDIRFILTER *penmFilter);
     1121VBGLR3DECL(int) VbglR3GuestCtrlDirGetClose(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t *puHandle);
     1122VBGLR3DECL(int) VbglR3GuestCtrlDirGetRead(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t *puHandle, uint32_t *pcbDirEntry, uint32_t *penmAddAttrib, uint32_t *pfFlags);
     1123VBGLR3DECL(int) VbglR3GuestCtrlDirGetRewind(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t *puHandle);
     1124/** @} */
     1125#  endif /* VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS */
    11011126VBGLR3DECL(int) VbglR3GuestCtrlDirGetRemove(PVBGLR3GUESTCTRLCMDCTX pCtx, char *pszPath, uint32_t cbPath, uint32_t *pfFlags);
    11021127/* Guest native file handling. */
    … …  
    11161141VBGLR3DECL(int) VbglR3GuestCtrlFileGetTell(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t *puHandle);
    11171142VBGLR3DECL(int) VbglR3GuestCtrlFileGetSetSize(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t *puHandle, uint64_t *pcbNew);
     1143#  ifdef VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS
     1144VBGLR3DECL(int) VbglR3GuestCtrlFileGetRemove(PVBGLR3GUESTCTRLCMDCTX pCtx, char *pszFileName, uint32_t cbFileName);
     1145#  endif
    11181146
    11191147/* Guest -> Host. */
     1148#  ifdef VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS
     1149/** @name Guest Control directory callbacks.
     1150 * @{
     1151 */
     1152VBGLR3DECL(int) VbglR3GuestCtrlDirCbOpen(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc, uint32_t uFileHandle);
     1153VBGLR3DECL(int) VbglR3GuestCtrlDirCbClose(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc);
     1154VBGLR3DECL(int) VbglR3GuestCtrlDirCbReadEx(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc, PGSTCTLDIRENTRYEX pEntry, uint32_t cbSize, char *pszUser, char *pszGroups, void *pvACL, size_t cbACL);
     1155VBGLR3DECL(int) VbglR3GuestCtrlDirCbRead(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc, PGSTCTLDIRENTRYEX pEntry, uint32_t cbSize);
     1156VBGLR3DECL(int) VbglR3GuestCtrlDirCbRewind(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc);
     1157/** @} */
     1158#  endif /* VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS */
     1159
    11201160VBGLR3DECL(int) VbglR3GuestCtrlFileCbOpen(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc, uint32_t uFileHandle);
    11211161VBGLR3DECL(int) VbglR3GuestCtrlFileCbClose(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc);
    11221162VBGLR3DECL(int) VbglR3GuestCtrlFileCbError(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc);
    11231163VBGLR3DECL(int) VbglR3GuestCtrlFileCbRead(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc, void *pvData, uint32_t cbData);
    1124 VBGLR3DECL(int) VbglR3GuestCtrlFileCbReadOffset(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc,
    1125                                                 void *pvData, uint32_t cbData, int64_t offNew);
     1164VBGLR3DECL(int) VbglR3GuestCtrlFileCbReadOffset(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc, void *pvData, uint32_t cbData, int64_t offNew);
    11261165VBGLR3DECL(int) VbglR3GuestCtrlFileCbWrite(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc, uint32_t cbWritten);
    11271166VBGLR3DECL(int) VbglR3GuestCtrlFileCbWriteOffset(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc, uint32_t cbWritten, int64_t offNew);
    … …  
    11301169VBGLR3DECL(int) VbglR3GuestCtrlFileCbTell(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc, uint64_t offCurrent);
    11311170VBGLR3DECL(int) VbglR3GuestCtrlFileCbSetSize(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc, uint64_t cbNew);
    1132 VBGLR3DECL(int) VbglR3GuestCtrlProcCbStatus(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uPID, uint32_t uStatus, uint32_t fFlags,
    1133                                             void *pvData, uint32_t cbData);
    1134 VBGLR3DECL(int) VbglR3GuestCtrlProcCbOutput(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uPID, uint32_t uHandle, uint32_t fFlags,
    1135                                             void *pvData, uint32_t cbData);
    1136 VBGLR3DECL(int) VbglR3GuestCtrlProcCbStatusInput(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t u32PID, uint32_t uStatus,
    1137                                                  uint32_t fFlags, uint32_t cbWritten);
    1138 
    1139 /** @}  */
     1171
     1172#  ifdef VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS
     1173/** @name Guest Control file system callbacks.
     1174 * @{
     1175 */
     1176VBGLR3DECL(int) VbglR3GuestCtrlFsCbQueryInfoEx(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc, PGSTCTLFSOBJINFO pObjInfo, char *pszUser, char *pszGroups, void *pvACL, uint32_t cbACL);
     1177VBGLR3DECL(int) VbglR3GuestCtrlFsCbQueryInfo(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc, PGSTCTLFSOBJINFO pObjInfo);
     1178VBGLR3DECL(int) VbglR3GuestCtrlFsCbCreateTemp(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc, const char *pszPath);
     1179/** @} */
     1180#  endif /* VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS */
     1181
     1182VBGLR3DECL(int) VbglR3GuestCtrlProcCbStatus(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uPID, uint32_t uStatus, uint32_t fFlags, void *pvData, uint32_t cbData);
     1183VBGLR3DECL(int) VbglR3GuestCtrlProcCbOutput(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uPID, uint32_t uHandle, uint32_t fFlags, void *pvData, uint32_t cbData);
     1184VBGLR3DECL(int) VbglR3GuestCtrlProcCbStatusInput(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t u32PID, uint32_t uStatus, uint32_t fFlags, uint32_t cbWritten);
    11401185# endif /* VBOX_WITH_GUEST_CONTROL defined */
    11411186

  • trunk/include/VBox/log.h

    r98103 r98526  
    491491    /** Main group, IGuestDirectory. */
    492492    LOG_GROUP_MAIN_GUESTDIRECTORY,
     493    /** Main group, IGuestDirectoryEvent. */
     494    LOG_GROUP_MAIN_GUESTDIRECTORYEVENT,
    493495    /** Main group, IGuestDnDSource. */
    494496    LOG_GROUP_MAIN_GUESTDNDSOURCE,
    … …  
    10631065    "MAIN_GUESTDEBUGCONTROL", \
    10641066    "MAIN_GUESTDIRECTORY", \
     1067    "MAIN_GUESTDIRECTORYEVENT", \
    10651068    "MAIN_GUESTDNDSOURCE", \
    10661069    "MAIN_GUESTDNDTARGET", \
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