Changeset 82525 in vbox for trunk/include

Timestamp:

Dec 9, 2019 7:48:38 PM (5 years ago)

Author:

vboxsync

Message:

SharedClipboardSvc,Vbgl: Looked at the connect and feature exchange stuff. Decided to make the connect one always fail, that way the beta and rc additions should not try make use of any of the new features and we should be free to do whatever we like. Need to circle back and drop the _61B parameter count variants later. bugref:9437

Location:

trunk/include/VBox

Files:

• HostServices/VBoxClipboardSvc.h (modified) (4 diffs)
• VBoxGuestLib.h (modified) (2 diffs)

trunk/include/VBox/HostServices/VBoxClipboardSvc.h

@@ -343 +343 @@
 #define VBOX_SHCL_GUEST_FN_DATA_WRITE             4
 
-/** Does the actual protocol handshake.
- *
- * If this message is not being sent by the guest, the host handles that
- * particular client with the legacy protocol (v0).
- *
- * @retval  VINF_SUCCESS on success.
- * @retval  VERR_INVALID_CLIENT_ID
- * @retval  VERR_WRONG_PARAMETER_COUNT
- * @retval  VERR_WRONG_PARAMETER_TYPE
+/** This is a left-over from the 6.1 dev cycle and will always fail.
+ *
+ * It used to take three 32-bit parameters, only one of which was actually used.
+ *
+ * It was replaced by VBOX_SHCL_GUEST_FN_REPORT_FEATURES and
+ * VBOX_SHCL_GUEST_FN_NEGOTIATE_CHUNK_SIZE.
+ *
+ * @retval  VERR_NOT_IMPLEMENTED
  * @since   6.1
  */
@@ -564 +563 @@
 #define VBOX_SHCL_GUEST_FN_ERROR                  27
 
+/** For negotiating a chunk size between the guest and host.
+ *
+ * Takes two 32-bit parameters both being byte counts, the first one gives the
+ * maximum chunk size the guest can handle and the second the preferred choice
+ * of the guest.  Upon return, the host will have updated both of them to
+ * reflect the maximum and default chunk sizes this client connect.  The guest
+ * may set the 2nd value to zero and let the host choose.
+ *
+ * @retval  VINF_SUCCESS on success.
+ * @retval  VERR_INVALID_CLIENT_ID
+ * @retval  VERR_WRONG_PARAMETER_COUNT
+ * @retval  VERR_WRONG_PARAMETER_TYPE
+ * @retval  VERR_INVALID_PARAMETER if the 2nd parameter is larger than the
+ *          first one
+ * @since   6.1
+ */
+#define VBOX_SHCL_GUEST_FN_NEGOTIATE_CHUNK_SIZE     28
+
 /** The last function number (used for validation/sanity).   */
-#define VBOX_SHCL_GUEST_FN_LAST                   VBOX_SHCL_GUEST_FN_ERROR
+#define VBOX_SHCL_GUEST_FN_LAST                   VBOX_SHCL_GUEST_FN_NEGOTIATE_CHUNK_SIZE
 /** @} */
 
@@ -579 +596 @@
 /** No flags set. */
 #define VBOX_SHCL_GF_NONE                         0
-/** Guest can handle context IDs (uint64_t, in paParam[0]).
- *  This is true for Guest Additions < 6.1. */
+/** The guest can handle context IDs where applicable. */
 #define VBOX_SHCL_GF_0_CONTEXT_ID                 RT_BIT_64(0)
 /** Bit that must be set in the 2nd parameter, will be cleared if the host reponds
@@ -592 +608 @@
 /** No flags set. */
 #define VBOX_SHCL_HF_NONE                         0
+/** The host can handle context IDs where applicable as well as the new
+ *  message handling functions. */
+#define VBOX_SHCL_HF_0_CONTEXT_ID                 RT_BIT_64(0)
 /** @} */
 

trunk/include/VBox/VBoxGuestLib.h

@@ -576 +576 @@
  * @{ */
 
-#  ifdef VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS
-/**
- * Structure containing context parameters for Shared Clipboard transfers.
- */
-typedef struct VBGLR3SHCLTRANSFERCMDCTX
-{
-    /** Callback table to use for all transfers. */
-    SHCLTRANSFERCALLBACKS Callbacks;
-} VBGLR3SHCLTRANSFERCMDCTX, *PVBGLR3SHCLTRANSFERCMDCTX;
-#  endif /* VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS */
-
 /**
  * The context required for either retrieving or sending a HGCM shared clipboard
  * commands from or to the host.
+ *
+ * @todo This struct could be handy if we want to implement a second
+ *       communication channel, e.g. via TCP/IP. Use a union for the HGCM stuff then.
  */
 typedef struct VBGLR3SHCLCMDCTX
 {
-    /** @todo This struct could be handy if we want to implement
-     *        a second communication channel, e.g. via TCP/IP.
-     *        Use a union for the HGCM stuff then. */
-
-    /** IN/OUT: Context ID to retrieve or to use. */
-    uint64_t                  uContextID;
-    /** IN: HGCM client ID to use for communication. */
-    uint32_t                  uClientID;
-    /** IN: Maximum chunk size (in bytes). */
-    uint32_t                  cbChunkSize;
-    /** IN: Host feature flags (of type VBOX_SHCL_HF_XXX). */
-    uint64_t                  fHostFeatures;
-    /** Flag indicating whether to use the legacy protocol (<= VBox 6.1) or not.
-     *  This is determined in VbglR3ClipboardConnectEx(). */
-    bool                      fUseLegacyProtocol;
+    /** HGCM client ID to use for communication.
+     * This is set by VbglR3ClipboardConnectEx(). */
+    uint32_t                    idClient;
+    /** This is @c false if both VBOX_SHCL_HF_0_CONTEXT_ID and
+     * VBOX_SHCL_GF_0_CONTEXT_ID are set, otherwise @c true and only the old
+     * protocol (< 6.1) should be used.
+     * This is set by VbglR3ClipboardConnectEx(). */
+    bool                        fUseLegacyProtocol;
+    /** Host feature flags (VBOX_SHCL_HF_XXX).
+     * This is set by VbglR3ClipboardConnectEx(). */
+    uint64_t                    fHostFeatures;
+    /** The guest feature flags reported to the host (VBOX_SHCL_GF_XXX).
+     * This is set by VbglR3ClipboardConnectEx().  */
+    uint64_t                    fGuestFeatures;
+#  ifdef VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS
+    /** Default chunk size (in bytes).
+     * This is set by VbglR3ClipboardConnectEx(). */
+    uint32_t                    cbChunkSize;
+    /** Max chunk size (in bytes).
+     * This is set by VbglR3ClipboardConnectEx(). */
+    uint32_t                    cbMaxChunkSize;
+#  endif
+
+    /** The context ID - input or/and output depending on the operation. */
+    uint64_t                    idContext;
     /** OUT: Number of parameters retrieved.
-     * @todo r=bird: s/uNumParms/cParms/ !! */
-    uint32_t                  uNumParms;
+     * This is set by ??. */
+    uint32_t                    cParmsRecived;
+
 #  ifdef VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS
-    VBGLR3SHCLTRANSFERCMDCTX  Transfers;
+    /** Callback table to use for all transfers. */
+    SHCLTRANSFERCALLBACKS       Callbacks;
 #  endif
-} VBGLR3SHCLCMDCTX, *PVBGLR3SHCLCMDCTX;
+} VBGLR3SHCLCMDCTX;
+/** Pointer to a shared clipboard context for Vbgl. */
+typedef VBGLR3SHCLCMDCTX *PVBGLR3SHCLCMDCTX;
 
 /**
@@ -680 +686 @@
 VBGLR3DECL(int)     VbglR3ClipboardReportFormats(HGCMCLIENTID idClient, uint32_t fFormats);
 
-VBGLR3DECL(int)     VbglR3ClipboardConnectEx(PVBGLR3SHCLCMDCTX pCtx);
+VBGLR3DECL(int)     VbglR3ClipboardConnectEx(PVBGLR3SHCLCMDCTX pCtx, uint64_t fGuestFeatures);
 VBGLR3DECL(int)     VbglR3ClipboardDisconnectEx(PVBGLR3SHCLCMDCTX pCtx);