Changeset 99085 in vbox for trunk/include

Timestamp:

Mar 21, 2023 12:15:00 PM (21 months ago)

Author:

vboxsync

Message:

Guest Control: Added directory listing support via IDirectory::list(). Added (randomized) testcase support for it. bugref:9783

Location:

trunk/include/VBox

Files:

• GuestHost/GuestControl.h (modified) (2 diffs)
• HostServices/GuestControlSvc.h (modified) (8 diffs)
• VBoxGuestLib.h (modified) (2 diffs)

trunk/include/VBox/GuestHost/GuestControl.h

@@ -432 +432 @@
 /** GSTCTL_PATH_F_XXX flag valid mask. */
 #define GSTCTL_PATH_F_VALID_MASK         UINT32_C(0x00000007)
+/** @} */
+
+/** @name GSTCTL_DIRLIST_F_XXX - Flags for guest directory listings.
+ * @{ */
+/** No guest listing flags specified. */
+#define GSTCTL_DIRLIST_F_NONE               UINT32_C(0)
+/** GSTCTL_DIRLIST_F_XXX valid mask. */
+#define GSTCTL_DIRLIST_F_VALID_MASK         UINT32_C(0x00000000)
 /** @} */
 
@@ -553 +561 @@
 
 /** The maximum size (in bytes) of an entry file name (at least RT_UOFFSETOF(GSTCTLDIRENTRYEX, szName[2]). */
-#define GSTCTL_DIRENTRY_MAX_SIZE    4096
-
+#define GSTCTL_DIRENTRY_MAX_SIZE                4096
+/** Maximum characters of the resolved user name. Including terminator. */
+#define GSTCTL_DIRENTRY_MAX_USER_NAME           255
+/** Maximum characters of the resolved user groups list. Including terminator. */
+#define GSTCTL_DIRENTRY_MAX_USER_GROUPS         _1K
+/** The resolved user groups delimiter as a string. */
+#define GSTCTL_DIRENTRY_GROUPS_DELIMITER_STR    "\r\n"
+
+/**
+ * Guest directory entry header.
+ *
+ * This is needed for (un-)packing multiple directory entries with its resolved user name + groups
+ * with the HOST_MSG_DIR_LIST command.
+ *
+ * The order of the attributes also mark their packed order, so be careful when changing this!
+ *
+ * @since 7.1.
+ */
+#pragma pack(1)
+typedef struct GSTCTLDIRENTRYLISTHDR
+{
+    /** Size (in bytes) of the directory header). */
+    uint32_t          cbDirEntryEx;
+    /** Size (in bytes) of the resolved user name as a string
+     *  Includes terminator. */
+    uint32_t          cbUser;
+    /** Size (in bytes) of the resolved user groups as a string.
+     *  Delimited by GSTCTL_DIRENTRY_GROUPS_DELIMITER_STR. Includes terminator. */
+    uint32_t          cbGroups;
+} GSTCTLDIRENTRYBLOCK;
+/** Pointer to a guest directory header entry. */
+typedef GSTCTLDIRENTRYLISTHDR *PGSTCTLDIRENTRYLISTHDR;
+#pragma pack()
 } /* namespace guestControl */
 

trunk/include/VBox/HostServices/GuestControlSvc.h

@@ -232 +232 @@
      */
     HOST_MSG_DIR_CREATE = 314,
+    /**
+     * Lists one or multiple directory entries at once.
+     *
+     * @since   7.1
+     */
+    HOST_MSG_DIR_LIST = 315,
 #endif /* VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS */
     /**
@@ -302 +308 @@
         RT_CASE_RET_STR(HOST_MSG_DIR_REWIND);
         RT_CASE_RET_STR(HOST_MSG_DIR_CREATE);
+        RT_CASE_RET_STR(HOST_MSG_DIR_LIST);
 #endif /* VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS */
         RT_CASE_RET_STR(HOST_MSG_DIR_REMOVE);
@@ -729 +736 @@
     /** Guest directory was rewind. */
     GUEST_DIR_NOTIFYTYPE_REWIND = 22,
+    /** Guest directory listing. */
+    GUEST_DIR_NOTIFYTYPE_LIST = 23,
 #endif
     /** Information about an open guest directory. */
@@ -1092 +1101 @@
     HGCMFunctionParameter flags;
 } HGCMMsgDirCreate;
+
+/**
+ * Lists the entries of a directory on the guest.
+ */
+typedef struct HGCMMsgDirList
+{
+    VBGLIOCHGCMCALL hdr;
+    /** Context ID. */
+    HGCMFunctionParameter context;
+    /** Handle of directory listing to list. */
+    HGCMFunctionParameter handle;
+    /** Number of entries to read at once.
+     *  Specify UINT32_MAX to read as much as possible. 0 is not allowed. */
+    HGCMFunctionParameter num_entries;
+    /** Listing flags (GSTCTL_DIRLIST_F_XXX). */
+    HGCMFunctionParameter flags;
+} HGCMMsgDirList;
 #endif /* VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS */
 
@@ -1528 +1554 @@
     {
         /**
-         * Parameters used for \a type GUEST_DIR_NOTIFYTYPE_OPEN.
+         * Parameters used for \a reply_hdr.type GUEST_DIR_NOTIFYTYPE_OPEN.
          *
          * @since 7.1
@@ -1538 +1564 @@
         } open;
         /**
-         * Parameters used for \a type GUEST_DIR_NOTIFYTYPE_READ.
+         * Parameters used for \a reply_hdr.type GUEST_DIR_NOTIFYTYPE_READ.
          *
          * @since 7.1
@@ -1550 +1576 @@
             /** Resolved group IDs as a string.
              *
-             *  Multiple groups are delimited by "\r\n", whereas
+             *  Multiple groups are delimited by GSTCTL_DIRENTRY_GROUPS_DELIMITER_STR, whereas
              *  the first group always is the primary group. */
             HGCMFunctionParameter groups;
         } read;
+        /**
+         * Parameters used for \a reply_hdr.type GUEST_DIR_NOTIFYTYPE_LIST.
+         *
+         * @since 7.1
+         */
+        struct
+        {
+            /** Number of entries in \a buffer. */
+            HGCMFunctionParameter num_entries;
+            /** Buffer containing the GSTCTLDIRENTRYEX entries, immediately followed
+             *  by resolved user + groups as a string (empty strings if not resolved).
+             *
+             *  Only will be sent if \a num_entries > 0. */
+            HGCMFunctionParameter buffer;
+        } list;
     } u;
 } HGCMReplyDirNotify;
@@ -1582 +1623 @@
             /** Resolved group IDs as a string.
              *
-             *  Multiple groups are delimited by "\r\n", whereas
+             *  Multiple groups are delimited by GSTCTL_DIRENTRY_GROUPS_DELIMITER_STR, whereas
              *  the first group always is the primary group. */
             HGCMFunctionParameter groups;

trunk/include/VBox/VBoxGuestLib.h

@@ -1122 +1122 @@
 VBGLR3DECL(int) VbglR3GuestCtrlDirGetRead(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t *puHandle);
 VBGLR3DECL(int) VbglR3GuestCtrlDirGetRewind(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t *puHandle);
+VBGLR3DECL(int) VbglR3GuestCtrlDirGetList(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t *puHandle, uint32_t *pcEntries, uint32_t *pfFlags);
 /** @} */
 #  endif /* VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS */
@@ -1155 +1156 @@
 VBGLR3DECL(int) VbglR3GuestCtrlDirCbRead(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc, PGSTCTLDIRENTRYEX pEntry, uint32_t cbSize);
 VBGLR3DECL(int) VbglR3GuestCtrlDirCbRewind(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc);
+VBGLR3DECL(int) VbglR3GuestCtrlDirCbList(PVBGLR3GUESTCTRLCMDCTX pCtx, uint32_t uRc, uint32_t cEntries, void *pvBuf, uint32_t cbBuf);
 /** @} */
 #  endif /* VBOX_WITH_GSTCTL_TOOLBOX_AS_CMDS */