Changeset 86702 in vbox for trunk/src/VBox/GuestHost/SharedClipboard

Timestamp:

Oct 26, 2020 9:21:51 AM (4 years ago)

Author:

vboxsync

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

141086

Message:

Shared Clipboard/X11: More cleanup + documentation. Renamed some functions which aren't actually callbacks and unified terminology (acronym CB could mean clipboard *or* callback, confusing). No functional changes. bugref:9848

Location:

trunk/src/VBox/GuestHost/SharedClipboard

Files:

• clipboard-x11.cpp (modified) (29 diffs)
• testcase/tstClipboardGH-X11.cpp (modified) (6 diffs)

trunk/src/VBox/GuestHost/SharedClipboard/clipboard-x11.cpp

@@ -92 +92 @@
 class formats;
 SHCL_X11_DECL(Atom) clipGetAtom(PSHCLX11CTX pCtx, const char *pszName);
-SHCL_X11_DECL(void) clipQueryX11FormatsCallback(PSHCLX11CTX pCtx);
+SHCL_X11_DECL(void) clipQueryX11Formats(PSHCLX11CTX pCtx);
 
 
@@ -470 +470 @@
  * @param  pCtx                 The X11 clipboard context to use.
  */
-SHCL_X11_DECL(void) clipReportEmptyX11CB(PSHCLX11CTX pCtx)
+SHCL_X11_DECL(void) clipReportEmpty(PSHCLX11CTX pCtx)
 {
     clipResetX11Formats(pCtx);
@@ -668 +668 @@
         /* We may already be out of date. */
         pCtx->fXtNeedsUpdate = false;
-        clipQueryX11FormatsCallback(pCtx);
+        clipQueryX11Formats(pCtx);
         return;
     }
@@ -675 +675 @@
     {
         /* No data available */
-        clipReportEmptyX11CB(pCtx);
+        clipReportEmpty(pCtx);
         return;
     }
@@ -766 +766 @@
  * @param   pCtx                The X11 clipboard context to use.
  */
-SHCL_X11_DECL(void) clipQueryX11FormatsCallback(PSHCLX11CTX pCtx)
+SHCL_X11_DECL(void) clipQueryX11Formats(PSHCLX11CTX pCtx)
 {
 #ifndef TESTCASE
@@ -824 +824 @@
             if (   (event.fixes.subtype == 0  /* XFixesSetSelectionOwnerNotify */)
                 && (event.fixes.owner != 0))
-                clipQueryX11FormatsCallback(pCtx);
+                clipQueryX11Formats(pCtx);
             else
-                clipReportEmptyX11CB(pCtx);
+                clipReportEmpty(pCtx);
         }
     }
@@ -836 +836 @@
  * @returns VBox status code.
  * @param   hThreadSelf             Associated thread handle.
- * @param   pvUser                  Pointer to user-provided thread data.
+ * @param   pvUser                  Pointer to the X11 clipboard context to use.
  */
 static DECLCALLBACK(int) clipEventThread(RTTHREAD hThreadSelf, void *pvUser)
 {
     RT_NOREF(hThreadSelf);
+    AssertPtrReturn(pvUser, VERR_INVALID_POINTER);
 
     LogRel(("Shared Clipboard: Starting X11 event thread\n"));
@@ -847 +848 @@
 
     if (pCtx->fGrabClipboardOnStart)
-        clipQueryX11FormatsCallback(pCtx);
+        clipQueryX11Formats(pCtx);
 
     /* We're now ready to run, tell parent. */
@@ -891 +892 @@
 }
 
-/** Worker function for stopping the clipboard which runs on the event
- * thread. */
-static void clipStopEventThreadWorker(void *pUserData, void *)
-{
-
-    PSHCLX11CTX pCtx = (SHCLX11CTX *)pUserData;
+/**
+ * Worker function for stopping the clipboard which runs on the event
+ * thread.
+ *
+ * @param   pvUserData          Pointer to the X11 clipboard context to use.
+ */
+static void clipStopEventThreadWorker(void *pvUserData, void *)
+{
+
+    PSHCLX11CTX pCtx = (PSHCLX11CTX)pvUserData;
 
     /* This might mean that we are getting stopped twice. */
@@ -967 +972 @@
  * This is the callback which is scheduled when data is available on the
  * wakeup pipe.  It simply reads all data from the pipe.
- */
-static void clipDrainWakeupPipe(XtPointer pUserData, int *, XtInputId *)
+ *
+ * @param   pvUserData          Pointer to the X11 clipboard context to use.
+ */
+static void clipDrainWakeupPipe(XtPointer pvUserData, int *, XtInputId *)
 {
     LogFlowFuncEnter();
 
-    PSHCLX11CTX pCtx = (SHCLX11CTX *)pUserData;
+    PSHCLX11CTX pCtx = (PSHCLX11CTX)pvUserData;
     char acBuf[WAKE_UP_STRING_LEN];
 
@@ -1346 +1353 @@
  *                              data we are returning.
  */
-static int clipUtf16CRLFToUtf8LF(Display *pDisplay, PRTUTF16 pwszSrc,
-                                 size_t cbSrc, Atom *atomTarget,
-                                 Atom *atomTypeReturn,
-                                 XtPointer *pValReturn,
-                                 unsigned long *pcLenReturn,
-                                 int *piFormatReturn)
+static int clipConvertUtf16ToX11Data(Display *pDisplay, PRTUTF16 pwszSrc,
+                                     size_t cbSrc, Atom *atomTarget,
+                                     Atom *atomTypeReturn,
+                                     XtPointer *pValReturn,
+                                     unsigned long *pcLenReturn,
+                                     int *piFormatReturn)
 {
     RT_NOREF(pDisplay);
@@ -1406 +1413 @@
  *                              data we are returning.
  */
-static int clipWinHTMLToUtf8ForX11CB(Display *pDisplay, const char *pszSrc,
+static int clipConvertHtmlToX11Data(Display *pDisplay, const char *pszSrc,
                                     size_t cbSrc, Atom *atomTarget,
                                     Atom *atomTypeReturn,
@@ -1464 +1471 @@
 }
 
-static int clipConvertVBoxCBForX11(PSHCLX11CTX pCtx, Atom *atomTarget,
-                                   Atom *atomTypeReturn,
-                                   XtPointer *pValReturn,
-                                   unsigned long *pcLenReturn,
-                                   int *piFormatReturn)
+static int clipConvertToX11Data(PSHCLX11CTX pCtx, Atom *atomTarget,
+                                Atom *atomTypeReturn,
+                                XtPointer *pValReturn,
+                                unsigned long *pcLenReturn,
+                                int *piFormatReturn)
 {
     int rc = VINF_SUCCESS;
@@ -1494 +1501 @@
                 || (fmtX11 == SHCLX11FMT_TEXT)))
         {
-            rc = clipUtf16CRLFToUtf8LF(XtDisplay(pCtx->pWidget),
-                                       (PRTUTF16)pv, cb, atomTarget,
-                                       atomTypeReturn, pValReturn,
-                                       pcLenReturn, piFormatReturn);
+            rc = clipConvertUtf16ToX11Data(XtDisplay(pCtx->pWidget),
+                                           (PRTUTF16)pv, cb, atomTarget,
+                                           atomTypeReturn, pValReturn,
+                                           pcLenReturn, piFormatReturn);
         }
 
@@ -1540 +1547 @@
         if (RT_SUCCESS(rc))
         {
-            /*
-             * The common VBox HTML encoding will be - Utf8
-             * because it more general for HTML formats then UTF16
-             * X11 clipboard returns UTF-16, so before sending it we should
-             * convert it to UTF8.
-             * It's very strange but here we get UTF-16 from x11 clipboard
-             * in same time we send UTF-8 to x11 clipboard and it's work.
+            /**
+             * The common VBox HTML encoding will be UTF-8.
+             * Before sending it to the X11 clipboard we have to convert it to UTF-8 first.
+             *
+             * Strange that we get UTF-16 from the X11 clipboard, but
+             * in same time we send UTF-8 to X11 clipboard and it works.
+             ** @todo r=andy Verify this.
              */
-            rc = clipWinHTMLToUtf8ForX11CB(XtDisplay(pCtx->pWidget),
-                                           (const char*)pv, cb, atomTarget,
-                                           atomTypeReturn, pValReturn,
-                                           pcLenReturn, piFormatReturn);
+            rc = clipConvertHtmlToX11Data(XtDisplay(pCtx->pWidget),
+                                          (const char*)pv, cb, atomTarget,
+                                          atomTypeReturn, pValReturn,
+                                          pcLenReturn, piFormatReturn);
             if (RT_SUCCESS(rc))
                 clipTrimTrailingNul(*(XtPointer *)pValReturn, pcLenReturn, fmtX11);
@@ -1623 +1630 @@
                                   pcLenReturn, piFormatReturn);
     else
-        rc = clipConvertVBoxCBForX11(pCtx, atomTarget, atomTypeReturn,
-                                     pValReturn, pcLenReturn, piFormatReturn);
+        rc = clipConvertToX11Data(pCtx, atomTarget, atomTypeReturn,
+                                  pValReturn, pcLenReturn, piFormatReturn);
 
     LogFlowFunc(("returning %RTbool, rc=%Rrc\n", RT_SUCCESS(rc), rc));
@@ -1641 +1648 @@
 } CLIPNEWVBOXFORMATS, *PCLIPNEWVBOXFORMATS;
 
-/** Invalidates the local cache of the data in the VBox clipboard. */
-static void clipInvalidateVBoxCBCache(PSHCLX11CTX pCtx)
+
+
+/**
+ * Invalidates the local cache of the data in the VBox clipboard.
+ *
+ * @param   pCtx                The X11 clipboard context to use.
+ */
+static void clipInvalidateClipboardCache(PSHCLX11CTX pCtx)
 {
     if (pCtx->pvUnicodeCache != NULL)
@@ -1653 +1666 @@
 /**
  * Takes possession of the X11 clipboard (and middle-button selection).
- */
-static void clipGrabX11CB(PSHCLX11CTX pCtx, SHCLFORMATS Formats)
+ *
+ * @param   pCtx                The X11 clipboard context to use.
+ * @param   uFormats            Clipboard formats to set.
+ */
+static void clipGrabX11Clipboard(PSHCLX11CTX pCtx, SHCLFORMATS uFormats)
 {
     LogFlowFuncEnter();
@@ -1661 +1677 @@
                        CurrentTime, clipXtConvertSelectionProc, NULL, 0))
     {
-        pCtx->vboxFormats = Formats;
+        pCtx->vboxFormats = uFormats;
+
         /* Grab the middle-button paste selection too. */
         XtOwnSelection(pCtx->pWidget, clipGetAtom(pCtx, "PRIMARY"),
@@ -1682 +1699 @@
  * event thread.
  *
- * @param pUserData             Pointer to a CLIPNEWVBOXFORMATS structure containing
+ * @param pvUserData            Pointer to a CLIPNEWVBOXFORMATS structure containing
  *                              information about the VBox formats available and the
  *                              clipboard context data.  Must be freed by the worker.
  */
-static void ShClX11ReportFormatsToX11Worker(void *pUserData, void * /* interval */)
-{
-    CLIPNEWVBOXFORMATS *pFormats = (CLIPNEWVBOXFORMATS *)pUserData;
-    PSHCLX11CTX pCtx = pFormats->pCtx;
-
-    uint32_t fFormats = pFormats->Formats;
+static void ShClX11ReportFormatsToX11Worker(void *pvUserData, void * /* interval */)
+{
+    AssertPtrReturnVoid(pvUserData);
+
+    CLIPNEWVBOXFORMATS *pFormats = (CLIPNEWVBOXFORMATS *)pvUserData;
+
+    PSHCLX11CTX pCtx     = pFormats->pCtx;
+    SHCLFORMATS fFormats = pFormats->Formats;
 
     RTMemFree(pFormats);
@@ -1697 +1716 @@
     LogFlowFunc (("fFormats=0x%x\n", fFormats));
 
-    clipInvalidateVBoxCBCache(pCtx);
-    clipGrabX11CB(pCtx, fFormats);
+    clipInvalidateClipboardCache(pCtx);
+    clipGrabX11Clipboard(pCtx, fFormats);
     clipResetX11Formats(pCtx);
 
@@ -1705 +1724 @@
 
 /**
- * Announces new clipboard formats to the host.
+ * Announces new clipboard formats to the X11 clipboard.
  *
  * @returns VBox status code.
- * @param   Formats             Clipboard formats offered.
- */
-int ShClX11ReportFormatsToX11(PSHCLX11CTX pCtx, uint32_t Formats)
+ * @param   pCtx                Context data for the clipboard backend.
+ * @param   uFormats            Clipboard formats offered.
+ */
+int ShClX11ReportFormatsToX11(PSHCLX11CTX pCtx, SHCLFORMATS uFormats)
 {
     /*
@@ -1725 +1745 @@
     {
         pFormats->pCtx    = pCtx;
-        pFormats->Formats = Formats;
+        pFormats->Formats = uFormats;
 
         rc = clipQueueToEventThread(pCtx, ShClX11ReportFormatsToX11Worker,
-                                    (XtPointer) pFormats);
+                                    (XtPointer)pFormats);
     }
     else
@@ -1743 +1763 @@
  * Converts the text obtained UTF-16LE with Windows EOLs.
  * Converts full BMP data to DIB format.
- *
- * @note  Callback for XtGetSelectionValue, for use when
- *        the X11 clipboard contains a format we understand.
- */
-SHCL_X11_DECL(void) clipConvertDataFromX11CallbackWorker(void *pClient, void *pvSrc, unsigned cbSrc)
+ */
+SHCL_X11_DECL(void) clipConvertDataFromX11Worker(void *pClient, void *pvSrc, unsigned cbSrc)
 {
     CLIPREADX11CBREQ *pReq = (CLIPREADX11CBREQ *)pClient;
@@ -1770 +1787 @@
     pCtx->fXtBusy = false;
     if (pCtx->fXtNeedsUpdate)
-        clipQueryX11FormatsCallback(pCtx);
+        clipQueryX11Formats(pCtx);
 
     if (pvSrc == NULL)
@@ -1974 +1991 @@
  * Converts the text obtained UTF-16LE with Windows EOLs.
  * Converts full BMP data to DIB format.
- *
- * @note  Callback for XtGetSelectionValue(), for use when
- *        the X11 clipboard contains a format we understand.
- */
-SHCL_X11_DECL(void) clipConvertDataFromX11Callback(Widget widget, XtPointer pClient,
-                                                   Atom * /* selection */, Atom *atomType,
-                                                   XtPointer pvSrc, long unsigned int *pcLen,
-                                                   int *piFormat)
+ */
+SHCL_X11_DECL(void) clipConvertDataFromX11(Widget widget, XtPointer pClient,
+                                           Atom * /* selection */, Atom *atomType,
+                                           XtPointer pvSrc, long unsigned int *pcLen,
+                                           int *piFormat)
 {
     RT_NOREF(widget);
     if (*atomType == XT_CONVERT_FAIL) /* Xt timeout */
-        clipConvertDataFromX11CallbackWorker(pClient, NULL, 0);
+        clipConvertDataFromX11Worker(pClient, NULL, 0);
     else
-        clipConvertDataFromX11CallbackWorker(pClient, pvSrc, (*pcLen) * (*piFormat) / 8);
+        clipConvertDataFromX11Worker(pClient, pvSrc, (*pcLen) * (*piFormat) / 8);
 
     XtFree((char *)pvSrc);
@@ -1998 +2012 @@
     XtGetSelectionValue(pCtx->pWidget, clipGetAtom(pCtx, "CLIPBOARD"),
                         clipAtomForX11Format(pCtx, idxFmt),
-                        clipConvertDataFromX11Callback,
+                        clipConvertDataFromX11,
                         reinterpret_cast<XtPointer>(pReq),
                         CurrentTime);
@@ -2010 +2024 @@
 /**
  * Worker function for ShClX11ReadDataFromX11 which runs on the event thread.
+ *
+ * @param pvUserData            Pointer to a CLIPREADX11CBREQ structure containing
+ *                              information about the clipboard read request.
+ *                              Must be free'd by the worker.
  */
 static void ShClX11ReadDataFromX11Worker(void *pvUserData, void * /* interval */)
@@ -2101 +2119 @@
 int ShClX11ReadDataFromX11(PSHCLX11CTX pCtx, SHCLFORMAT Format, CLIPREADCBREQ *pReq)
 {
+    AssertPtrReturn(pReq, VERR_INVALID_POINTER);
+
     /*
      * Immediately return if we are not connected to the X server.

trunk/src/VBox/GuestHost/SharedClipboard/testcase/tstClipboardGH-X11.cpp

@@ -36 +36 @@
 
 extern void clipUpdateX11Targets(PSHCLX11CTX pCtx, SHCLX11FMTIDX *pTargets, size_t cTargets);
-extern void clipReportEmptyX11CB(PSHCLX11CTX pCtx);
-extern void clipConvertDataFromX11CallbackWorker(void *pClient, void *pvSrc, unsigned cbSrc);
+extern void clipReportEmpty(PSHCLX11CTX pCtx);
+extern void clipConvertDataFromX11Worker(void *pClient, void *pvSrc, unsigned cbSrc);
 extern SHCLX11FMTIDX clipGetTextFormatFromTargets(PSHCLX11CTX pCtx, SHCLX11FMTIDX *pTargets, size_t cTargets);
 extern SHCLX11FMT clipRealFormatForX11Format(SHCLX11FMTIDX uFmtIdx);
 extern Atom clipGetAtom(PSHCLX11CTX pCtx, const char *pcszName);
+extern void clipQueryX11Formats(PSHCLX11CTX pCtx);
 extern size_t clipReportMaxX11Formats(void);
 
@@ -61 +62 @@
 *   Own callback implementations                                                                                                 *
 *********************************************************************************************************************************/
-extern DECLCALLBACK(void) clipQueryX11FormatsCallback(PSHCLX11CTX pCtx);
 extern DECLCALLBACK(void) clipConvertX11TargetsCallback(Widget widget, XtPointer pClient,
                                                         Atom * /* selection */, Atom *atomType,
@@ -224 +224 @@
     if (target != g_tst_aSelTargetsIdx[0])
     {
-        clipConvertDataFromX11CallbackWorker(closure, NULL, 0); /* Could not convert to target. */
+        clipConvertDataFromX11Worker(closure, NULL, 0); /* Could not convert to target. */
         return;
     }
@@ -236 +236 @@
         format = 0;
     }
-    clipConvertDataFromX11CallbackWorker(closure, pValue, count * format / 8);
+    clipConvertDataFromX11Worker(closure, pValue, count * format / 8);
     if (pValue)
         RTMemFree(pValue);
@@ -339 +339 @@
 static void tstClipSendTargetUpdate(PSHCLX11CTX pCtx)
 {
-    clipQueryX11FormatsCallback(pCtx);
+    clipQueryX11Formats(pCtx);
 }
 
@@ -772 +772 @@
     RTTestSub(hTest, "notification of switch to X11 clipboard");
     tstClipInvalidateFormats();
-    clipReportEmptyX11CB(&X11Ctx);
+    clipReportEmpty(&X11Ctx);
     RTTEST_CHECK_MSG(hTest, tstClipQueryFormats() == 0,
                      (hTest, "Failed to send a format update (release) notification\n"));