Changeset 93495 in vbox for trunk/include/VBox

Timestamp:

Jan 31, 2022 1:08:33 PM (3 years ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

149618

Message:

Shared Clipboard: Implemented backend callbacks and a dedicated backend context, together with a new testcase which mocks HGCM to also test the guest-side clipboard code (disabled by default for now). Work in progress, only tested on Linux so far.

Location:

trunk/include/VBox/GuestHost

Files:

• SharedClipboard-x11.h (modified) (1 diff)
• SharedClipboard.h (modified) (1 diff)

trunk/include/VBox/GuestHost/SharedClipboard-x11.h

@@ -92 +92 @@
 {
     /** Opaque data structure describing the front-end. */
-    PSHCLCONTEXT pFrontend;
+    PSHCLCONTEXT     pFrontend;
+    /** Our callback table to use. */
+    SHCLCALLBACKS    Callbacks;
     /** Is an X server actually available? */
-    bool fHaveX11;
+    bool             fHaveX11;
     /** The X Toolkit application context structure. */
-    XtAppContext pAppContext;
-
+    XtAppContext     pAppContext;
     /** We have a separate thread to wait for window and clipboard events. */
-    RTTHREAD Thread;
+    RTTHREAD         Thread;
     /** Flag indicating that the thread is in a started state. */
-    bool fThreadStarted;
-
+    bool             fThreadStarted;
     /** The X Toolkit widget which we use as our clipboard client.  It is never made visible. */
-    Widget pWidget;
-
+    Widget           pWidget;
     /** Should we try to grab the clipboard on startup? */
-    bool fGrabClipboardOnStart;
-
+    bool             fGrabClipboardOnStart;
     /** The best text format X11 has to offer, as an index into the formats table. */
-    SHCLX11FMTIDX idxFmtText;
+    SHCLX11FMTIDX    idxFmtText;
     /** The best bitmap format X11 has to offer, as an index into the formats table. */
-    SHCLX11FMTIDX idxFmtBmp;
+    SHCLX11FMTIDX    idxFmtBmp;
     /** The best HTML format X11 has to offer, as an index into the formats table. */
-    SHCLX11FMTIDX idxFmtHTML;
+    SHCLX11FMTIDX    idxFmtHTML;
 #ifdef VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS
     /** The best HTML format X11 has to offer, as an index into the formats table. */
-    SHCLX11FMTIDX   idxFmtURI;
+    SHCLX11FMTIDX    idxFmtURI;
 # ifdef VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS_HTTP
     /** HTTP transfer context data. */
-    SHCLHTTPCONTEXT HttpCtx;
+    SHCLHTTPCONTEXT  HttpCtx;
 # endif
 #endif
     /** What kind of formats does VBox have to offer? */
-    SHCLFORMATS vboxFormats;
+    SHCLFORMATS      vboxFormats;
     /** Cache of the last unicode data that we received. */
-    void *pvUnicodeCache;
+    void            *pvUnicodeCache;
     /** Size of the unicode data in the cache. */
-    uint32_t cbUnicodeCache;
+    uint32_t         cbUnicodeCache;
     /** When we wish the clipboard to exit, we have to wake up the event
      * loop.  We do this by writing into a pipe.  This end of the pipe is
      * the end that another thread can write to. */
-    int wakeupPipeWrite;
+    int              wakeupPipeWrite;
     /** The reader end of the pipe. */
-    int wakeupPipeRead;
+    int              wakeupPipeRead;
     /** A pointer to the XFixesSelectSelectionInput function. */
     void (*fixesSelectInput)(Display *, Window, Atom, unsigned long);
     /** The first XFixes event number. */
-    int fixesEventBase;
+    int              fixesEventBase;
 #ifdef VBOX_WITH_SHARED_CLIPBOARD_XT_BUSY
     /** XtGetSelectionValue on some versions of libXt isn't re-entrant
      * so block overlapping requests on this flag. */
-    bool fXtBusy;
+    bool             fXtBusy;
     /** If a request is blocked on the previous flag, set this flag to request
      * an update later - the first callback should check and clear this flag
      * before processing the callback event. */
-    bool fXtNeedsUpdate;
+    bool             fXtNeedsUpdate;
 #endif
 } SHCLX11CTX, *PSHCLX11CTX;
+
+/**
+ * Structure for keeping a X11 read data request.
+ */
+typedef struct _SHCLX11READDATAREQ
+{
+    /** Actual read request to handle. */
+    CLIPREADCBREQ *pReq;
+    /** Result code of the operation on completion. */
+    int            rcCompletion;
+} SHCLX11READDATAREQ;
+/** Pointer to a send data request. */
+typedef SHCLX11READDATAREQ *PSHCLX11READDATAREQ;
 
 /** @name Shared Clipboard APIs for X11.
  * @{
  */
-int ShClX11Init(PSHCLX11CTX pCtx, PSHCLCONTEXT pParent, bool fHeadless);
+int ShClX11Init(PSHCLX11CTX pCtx, PSHCLCALLBACKS pCallbacks, PSHCLCONTEXT pParent, bool fHeadless);
 void ShClX11Destroy(PSHCLX11CTX pCtx);
 int ShClX11ThreadStart(PSHCLX11CTX pCtx, bool grab);
+int ShClX11ThreadStartEx(PSHCLX11CTX pCtx, const char *pszName, bool fGrab);
 int ShClX11ThreadStop(PSHCLX11CTX pCtx);
 int ShClX11ReportFormatsToX11(PSHCLX11CTX pCtx, SHCLFORMATS vboxFormats);
 int ShClX11ReadDataFromX11(PSHCLX11CTX pCtx, SHCLFORMATS vboxFormat, CLIPREADCBREQ *pReq);
-/** @} */
-
-/** @name Shared Clipboard callbacks which have to be implemented by tools using the X11
- *        clipboard, e.g. VBoxClient (on guest side) or the X11 host service backend.
- * @{
- */
-/**
- * Callback for reporting supported formats of current clipboard data from X11 to VBox.
- *
- * @note   Runs in Xt event thread.
- *
- * @param  pCtx                 Opaque context pointer for the glue code.
- * @param  fFormats             The formats available.
- */
-DECLCALLBACK(void) ShClX11ReportFormatsCallback(PSHCLCONTEXT pCtx, SHCLFORMATS fFormats);
-
-/**
- * Callback for requesting clipboard data for X11.
- * The function will be invoked for every single target the clipboard requests.
- *
- * @note Runs in Xt event thread.
- *
- * @returns VBox status code. VERR_NO_DATA if no data available.
- * @param   pCtx                Pointer to the host clipboard structure.
- * @param   uFmt                The format in which the data should be transferred
- *                              (VBOX_SHCL_FMT_XXX).
- * @param   ppv                 Returns an allocated buffer with data read from the guest on success.
- *                              Needs to be free'd with RTMemFree() by the caller.
- * @param   pcb                 Returns the amount of data read (in bytes) on success.
- */
-DECLCALLBACK(int) ShClX11RequestDataCallback(PSHCLCONTEXT pCtx, SHCLFORMAT uFmt, void **ppv, uint32_t *pcb);
-
-/**
- * Callback for reporting that clipboard data from X11 is available.
- *
- * @param  pCtx                 Our context information.
- * @param  rcCompletion         The completion status of the request.
- * @param  pReq                 The request structure that we passed in when we started
- *                              the request.  We RTMemFree() this in this function.
- * @param  pv                   The clipboard data returned from X11 if the request succeeded (see @a rcCompletion).
- * @param  cb                   The size of the data in @a pv.
- */
-DECLCALLBACK(void) ShClX11ReportDataCallback(PSHCLCONTEXT pCtx, int rcCompletion,
-                                             CLIPREADCBREQ *pReq, void *pv, uint32_t cb);
+void ShClX11SetCallbacks(PSHCLX11CTX pCtx, PSHCLCALLBACKS pCallbacks);
 /** @} */
 

trunk/include/VBox/GuestHost/SharedClipboard.h

@@ -232 +232 @@
 typedef SHCLCONTEXT *PSHCLCONTEXT;
 
+/**
+ * @name Shared Clipboard callback table.
+ *
+ * This table gets used by
+ *   - the backends on the host (where required)
+ *   - guest side implementations (e.g. VBoxClient)
+ *   - by the underlying core code (e.g. X11 backend -> X11 common code -> callback)
+ *
+ * Some clipboard mechanisms (e.g. X11) require asynchronous and/or event-driven handling
+ * of clipboard data, making it hard to control our program flow when testing stuff.
+ *
+ * So overriding required callbacks on runtime for testing purposes makes this approach much
+ * more flexible without implementing separate code paths for production code and test units.
+ *
+ * @{
+ */
+typedef struct _SHCLCALLBACKS
+{
+    /**
+     * Callback for reporting supported clipoard formats of current clipboard data.
+     *
+     * @note On X11:
+     *         Runs in Xt event thread for the X11 code.
+     *
+     * @returns VBox status code.
+     * @param   pCtx            Opaque context pointer for the glue code.
+     * @param   fFormats        The formats available.
+     */
+    DECLCALLBACKMEMBER(int, pfnReportFormats, (PSHCLCONTEXT pCtx, SHCLFORMATS fFormats, void *pvUser));
+
+    /**
+     * Callback for reading data from the clipboard.
+     * Optional and can be NULL.
+     *
+     * @note Used for testing X11 clipboard code.
+     *
+     * @returns VBox status code.
+     * @param   pCtx            Opaque context pointer for the glue code.
+     * @param   uFmt            The format in which the data should be read
+     *                          (VBOX_SHCL_FMT_XXX).
+     * @param   ppv             Returns an allocated buffer with data from on success.
+     *                          Needs to be free'd with RTMemFree() by the caller.
+     * @param   pcb             Returns the amount of data read (in bytes) on success.
+     * @param   pvUser          Implementation-dependent pointer to data for fullfilling the request.
+     *                          Optional and can be NULL.
+     */
+    DECLCALLBACKMEMBER(int, pfnOnClipboardRead, (PSHCLCONTEXT pCtx, SHCLFORMAT uFmt, void **ppv, size_t *pcb, void *pvUser));
+
+    /**
+     * Callback for writing data to the clipboard.
+     * Optional and can be NULL.
+     *
+     * @note Used for testing X11 clipboard code.
+     *
+     * @returns VBox status code.
+     * @param   pCtx            Opaque context pointer for the glue code.
+     * @param   uFmt            The format in which the data should be written as
+     *                          (VBOX_SHCL_FMT_XXX).
+     * @param   pv              The clipboard data to write.
+     * @param   cb              The size of the data in @a pv.
+     * @param   pvUser          Implementation-dependent pointer to data for fullfilling the request.
+     *                          Optional and can be NULL.
+     */
+    DECLCALLBACKMEMBER(int, pfnOnClipboardWrite, (PSHCLCONTEXT pCtx, SHCLFORMAT uFmt, void *pv, size_t cb, void *pvUser));
+
+    /**
+     * Callback for requesting clipboard data from the source.
+     *
+     * @note On X11:
+     *         The function will be invoked for every single target the clipboard requests.
+     *         Runs in Xt event thread for the X11 code.
+     *
+     * @returns VBox status code. VERR_NO_DATA if no data available.
+     * @param   pCtx            Opaque context pointer for the glue code.
+     * @param   uFmt            The format in which the data should be transferred
+     *                          (VBOX_SHCL_FMT_XXX).
+     * @param   ppv             Returns an allocated buffer with data read from the guest on success.
+     *                          Needs to be free'd with RTMemFree() by the caller.
+     * @param   pcb             Returns the amount of data read (in bytes) on success.
+     * @param   pvUser          Implementation-dependent pointer to data for fullfilling the request.
+     *                          Optional and can be NULL.
+     *                          On X11: Of type PSHCLX11READDATAREQ; We RTMemFree() this in this function.
+     */
+    DECLCALLBACKMEMBER(int, pfnOnRequestDataFromSource, (PSHCLCONTEXT pCtx, SHCLFORMAT uFmt, void **ppv, uint32_t *pcb, void *pvUser));
+
+    /**
+     * Callback for sending clipboard data to the destination.
+     *
+     * @note On X11:
+     *         (see @a rcCompletion)
+     *
+     * @returns VBox status code.
+     * @param   pCtx            Opaque context pointer for the glue code.
+     * @param   pv              The clipboard data returned if the request succeeded.
+     * @param   cb              The size of the data in @a pv.
+     * @param   pvUser          Implementation-dependent pointer to data for fullfilling the request.
+     *                          Optional and can be NULL.
+     */
+    DECLCALLBACKMEMBER(int, pfnOnSendDataToDest, (PSHCLCONTEXT pCtx, void *pv, uint32_t cb, void *pvUser));
+} SHCLCALLBACKS;
+typedef SHCLCALLBACKS *PSHCLCALLBACKS;
+/** @} */
+
 /** Opaque request structure for X11 clipboard data.
  * @{ */