Changeset 85712 in vbox for trunk/include

Timestamp:

Aug 12, 2020 12:24:30 PM (4 years ago)

Author:

vboxsync

Message:

DnD: Added wire protocol support for querying and reporting guest / host features in host service and VbglR3. Untested.

Location:

trunk/include/VBox

Files:

• HostServices/DragAndDropSvc.h (modified) (7 diffs)
• VBoxGuestLib.h (modified) (2 diffs)

trunk/include/VBox/HostServices/DragAndDropSvc.h

@@ -44 +44 @@
  *           The guest itself uses VBOXDNDCONNECTMSG to report its supported protocol version to the DnD service.
  *
- *     Protocol v3 (VBox 5.0.10 and up, current):
+ *     Protocol v3 (VBox 5.0.10 and up, deprecated):
  *         + Added VBOXDNDDISCONNECTMSG for being able to track client disconnects on host side (Main).
  *         + Added context IDs for every HGCM message. Not used yet and must be 0.
@@ -56 +56 @@
  *         - Removed unused HOST_DND_GH_RECV_DIR, HOST_DND_GH_RECV_FILE_DATA and HOST_DND_GH_RECV_FILE_HDR commands.
  *
- * Protocol TODO:
- *
- *     - Split up messages which use VBOXDNDHGACTIONMSG into own functions and remove parameters which
- *       are not actually needed / used by a function. Why does HOST_DND_HG_EVT_MOVE need all the format stuff, for example?
+ *     VBox 6.1.x and up, current:
+ *         + Added GUEST_DND_QUERY_FEATURES + GUEST_DND_REPORT_FEATURES.
+ *         - Protocol versioning support in VBOXDNDCONNECTMSG is now marked as being deprecated.
+ *
+ ** @todo:
+ * - Split up messages which use VBOXDNDHGACTIONMSG into own functions and remove parameters which
+ *   are not actually needed / used by a function. Why does HOST_DND_HG_EVT_MOVE need all the format stuff, for example?
  */
 
@@ -170 +173 @@
     GUEST_DND_DISCONNECT               = 11,
 
+    /** Report guest side feature flags and retrieve the host ones.
+     *
+     * Two 64-bit parameters are passed in from the guest with the guest features
+     * (VBOX_DND_GF_XXX), the host replies by replacing the parameter values with
+     * the host ones (VBOX_DND_HF_XXX).
+     *
+     * @retval  VINF_SUCCESS on success.
+     * @retval  VERR_INVALID_CLIENT_ID
+     * @retval  VERR_WRONG_PARAMETER_COUNT
+     * @retval  VERR_WRONG_PARAMETER_TYPE
+     * @since   6.1.x
+     */
+    GUEST_DND_REPORT_FEATURES          = 12,
+
+    /** Query the host ones feature masks.
+     *
+     * That way the guest (client) can get hold of the features from the host.
+     * Again, it is prudent to set the 127 bit and observe it being cleared on
+     * success, as older hosts might return success without doing anything.
+     *
+     * @retval  VINF_SUCCESS on success.
+     * @retval  VERR_INVALID_CLIENT_ID
+     * @retval  VERR_WRONG_PARAMETER_COUNT
+     * @retval  VERR_WRONG_PARAMETER_TYPE
+     * @since   6.1.x
+     */
+    GUEST_DND_QUERY_FEATURES           = 13,
+
     /**
      * The guest waits for a new message the host wants to process
@@ -223 +254 @@
 };
 
+/** @name VBOX_DND_GF_XXX - Guest features.
+ * @sa GUEST_DND_REPORT_FEATURES
+ * @{ */
+/** No flags set. */
+#define VBOX_DND_GF_NONE                          0
+/** Bit that must be set in the 2nd parameter, will be cleared if the host reponds
+ * correctly (old hosts might not). */
+#define VBOX_DND_GF_1_MUST_BE_ONE                 RT_BIT_64(63)
+/** @} */
+
+/** @name VBOX_DND_HF_XXX - Host features.
+ * @sa DND_GUEST_REPORT_FEATURES
+ * @{ */
+/** No flags set. */
+#define VBOX_DND_HF_NONE                          0
+/** @} */
+
 /**
  * DnD operation progress states.
@@ -642 +690 @@
         struct
         {
-            /** Protocol version to use. */
+            /** Protocol version to use.
+             *  Deprecated since VBox 6.1.x. Do not use / rely on it anymore. */
             HGCMFunctionParameter uProtocol;     /* OUT uint32_t */
             /** Connection flags. Optional. */
@@ -651 +700 @@
             /** Context ID. Unused at the moment. */
             HGCMFunctionParameter uContext;     /* OUT uint32_t */
-            /** Protocol version to use. */
+            /** Protocol version to use.
+             *  Deprecated since VBox 6.1.x. Do not use / rely on it anymore. */
             HGCMFunctionParameter uProtocol;     /* OUT uint32_t */
             /** Connection flags. Optional. */
@@ -900 +950 @@
     /** Callback data header. */
     VBOXDNDCBHEADERDATA         hdr;
+    /** Protocol version to use.
+     *  Deprecated since VBox 6.1.x. Do not use / rely on it anymore. */
     uint32_t                    uProtocol;
     uint32_t                    uFlags;

trunk/include/VBox/VBoxGuestLib.h

@@ -1154 +1154 @@
     /** The VM's current session ID. */
     uint64_t uSessionID;
-    /** Protocol version to use. */
-    uint32_t uProtocol;
+    /** Protocol version to use.
+     *  Deprecated; do not used / rely on it anymore. */
+    uint32_t uProtocolDeprecated;
+    /** Host feature flags (VBOX_DND_HF_XXX).
+     * This is set by VbglR3DnDConnect(). */
+    uint64_t fHostFeatures;
+    /** The guest feature flags reported to the host (VBOX_DND_GF_XXX).
+     * This is set by VbglR3DnDConnect().  */
+    uint64_t fGuestFeatures;
     /** Number of parameters retrieved for the current command. */
     uint32_t uNumParms;
@@ -1298 +1305 @@
 VBGLR3DECL(int)     VbglR3DnDDisconnect(PVBGLR3GUESTDNDCMDCTX pCtx);
 
+VBGLR3DECL(int)     VbglR3DnDReportFeatures(uint32_t idClient, uint64_t fGuestFeatures, uint64_t *pfHostFeatures);
+
 VBGLR3DECL(int)     VbglR3DnDEventGetNext(PVBGLR3GUESTDNDCMDCTX pCtx, PVBGLR3DNDEVENT *ppEvent);
 VBGLR3DECL(void)    VbglR3DnDEventFree(PVBGLR3DNDEVENT pEvent);