Changeset 15883 in vbox for trunk/src/VBox

Timestamp:

Jan 8, 2009 8:10:33 PM (16 years ago)

Author:

vboxsync

Message:

HostServices/SharedClipboard/X11: documentation and function renaming

File:

• trunk/src/VBox/HostServices/SharedClipboard/x11.cpp (modified) (62 diffs)

trunk/src/VBox/HostServices/SharedClipboard/x11.cpp

@@ -182 +182 @@
 
 /**
- * Send a request to the guest to transfer the contents of its clipboard to the host.
- *
- * @param pCtx      Pointer to the host clipboard structure
- * @param u32Format The format in which the data should be transfered
- */
-static int vboxClipboardReadDataFromClient (VBOXCLIPBOARDCONTEXT *pCtx, uint32_t u32Format)
+ * Send a request to VBox to transfer the contents of its clipboard to X11.
+ *
+ * @param  pCtx      Pointer to the host clipboard structure
+ * @param  u32Format The format in which the data should be transfered
+ * @thread clipboard X11 event thread
+ * @note   called by vboxClipboardConvert*
+ */
+static int vboxClipboardReadDataFromVBox (VBOXCLIPBOARDCONTEXT *pCtx, uint32_t u32Format)
 {
     VBOXCLIPBOARDCLIENTDATA *pClient = pCtx->pClient;
@@ -194 +196 @@
     if (pClient == 0)
     {
-        Log(("vboxClipboardReadDataFromClient: host requested guest clipboard data after guest had disconnected.\n"));
+        LogFunc(("host requested guest clipboard data after guest had disconnected.\n"));
         pCtx->guestFormats = 0;
         pCtx->waiter = 0;
@@ -276 +278 @@
 /**
  * Convert the UTF-8 text returned from the X11 clipboard to UTF-16LE with Windows EOLS.
- * We are reading the host clipboard to make it available to the guest.
+ * We are reading the X11 clipboard to make it available to VBox.
  *
  * @param pValue      Source UTF-8 text
@@ -284 +286 @@
  * @param pcbActual   Where to store the size of the converted data
  * @param pClient     Pointer to the client context structure
- */
-static void vboxClipboardGetUtf8(XtPointer pValue, unsigned cbSrcLen, void *pv, unsigned cb,
-                                 uint32_t *pcbActual)
+ * @thread clipboard X11 event thread
+ * @note   called by vboxClipboardGetDataFromX11
+ */
+static void vboxClipboardGetUtf8FromX11(XtPointer pValue, unsigned cbSrcLen,
+                                        void *pv, unsigned cb,
+                                        uint32_t *pcbActual)
 {
     size_t cwSrcLen, cwDestLen;
@@ -325 +330 @@
 /**
  * Convert the COMPOUND_TEXT text returned from the X11 clipboard to UTF-16LE with Windows
- * EOLS.  We are reading the host clipboard to make it available to the guest.
+ * EOLS.  We are reading the X11 clipboard to make it available to VBox.
  *
  * @param pValue      Source COMPOUND_TEXT text
@@ -333 +338 @@
  * @param pcbActual   Where to store the size of the converted data
  * @param pClient     Pointer to the client context structure
- */
-static void vboxClipboardGetCText(XtPointer pValue, unsigned cbSrcLen, void *pv, unsigned cb,
-                                  uint32_t *pcbActual)
+ * @thread clipboard X11 event thread
+ * @note   called by vboxClipboardGetDataFromX11
+ */
+static void vboxClipboardGetCTextFromX11(XtPointer pValue, unsigned cbSrcLen,
+                                         void *pv, unsigned cb,
+                                         uint32_t *pcbActual)
 {
     size_t cwSrcLen, cwDestLen;
@@ -403 +411 @@
 /**
  * Convert the Latin1 text returned from the X11 clipboard to UTF-16LE with Windows EOLS
- * and place it in the global g_pcClipboardText variable.  We are reading the host clipboard to
- * make it available to the guest.
+ * and place it in the global g_pcClipboardText variable.  We are reading the X11 clipboard to
+ * make it available to VBox.
  *
  * @param pValue      Source Latin1 text
@@ -412 +420 @@
  * @param pcbActual   Where to store the size of the converted data
  * @param pClient     Pointer to the client context structure
- */
-static void vboxClipboardGetLatin1(XtPointer pValue, unsigned cbSourceLen, void *pv, unsigned cb,
+ * @thread clipboard X11 event thread
+ * @note   called by vboxClipboardGetDataFromX11
+ */
+static void vboxClipboardGetLatin1FromX11(XtPointer pValue, unsigned cbSourceLen, void *pv, unsigned cb,
                                    uint32_t *pcbActual)
 {
@@ -421 +431 @@
     int rc = VINF_SUCCESS;
 
-    LogFlow (("vboxClipboardGetLatin1: converting Latin1 to Utf-16LE.  Original is %.*s\n",
-              cbSourceLen, pu8SourceText));
+    LogFlowFunc (("converting Latin1 to Utf-16LE.  Original is %.*s\n",
+                  cbSourceLen, pu8SourceText));
     *pcbActual = 0;  /* Only set this to the right value on success. */
     for (unsigned i = 0; i < cbSourceLen; i++)
@@ -454 +464 @@
 }
 
-/** Convert the clipboard text from the current format to Utf-16 with Windows line breaks.
-    We are reading the host clipboard to make it available to the guest. */
-static void vboxClipboardGetProc(Widget, XtPointer pClientData, Atom * /* selection */,
-                                 Atom *atomType, XtPointer pValue, long unsigned int *pcLen,
-                                 int *piFormat)
+/**
+ * Convert the clipboard text from the current format to Utf-16 with Windows line breaks.
+ * We are reading the X11 clipboard to make it available to VBox.
+ * @thread  clipboard X11 event thread
+ * @note    Callback for XtGetSelectionValue, called from vboxClipboardReadData
+ */
+static void vboxClipboardGetDataFromX11(Widget, XtPointer pClientData,
+                                        Atom * /* selection */, Atom *atomType,
+                                        XtPointer pValue,
+                                        long unsigned int *pcLen,
+                                        int *piFormat)
 {
     LogFlowFunc(("pClientData=%p, *pcLen=%lu, *piFormat=%d\n", pClientData, *pcLen, *piFormat));
@@ -490 +506 @@
         break;
     case CTEXT:
-        vboxClipboardGetCText(pValue, cTextLen, g_ctx.requestBuffer, g_ctx.requestBufferSize,
+        vboxClipboardGetCTextFromX11(pValue, cTextLen, g_ctx.requestBuffer, g_ctx.requestBufferSize,
                               g_ctx.requestActualSize);
         break;
@@ -502 +518 @@
             && (RTStrUniLenEx(pu8SourceText, *pcLen, &cStringLen) == VINF_SUCCESS))
         {
-            vboxClipboardGetUtf8(pValue, cTextLen, g_ctx.requestBuffer, g_ctx.requestBufferSize,
+            vboxClipboardGetUtf8FromX11(pValue, cTextLen, g_ctx.requestBuffer, g_ctx.requestBufferSize,
                                  g_ctx.requestActualSize);
             break;
@@ -508 +524 @@
         else
         {
-            vboxClipboardGetLatin1(pValue, cTextLen, g_ctx.requestBuffer, g_ctx.requestBufferSize,
+            vboxClipboardGetLatin1FromX11(pValue, cTextLen, g_ctx.requestBuffer, g_ctx.requestBufferSize,
                                    g_ctx.requestActualSize);
             break;
@@ -514 +530 @@
     }
     default:
-        Log (("vboxClipboardGetProc: bad target format\n"));
+        LogFunc (("bad target format\n"));
         XtFree(reinterpret_cast<char *>(pValue));
         RTSemMutexRelease(g_ctx.asyncMutex);
@@ -523 +539 @@
 }
 
-/** Callback to handle a reply to a request for the targets the current clipboard holder can
-    handle.  We are reading the host clipboard to make it available to the guest. */
-static void vboxClipboardTargetsProc(Widget, XtPointer pClientData, Atom * /* selection */,
-                                     Atom *atomType, XtPointer pValue, long unsigned int *pcLen,
-                                     int *piFormat)
+/**
+ * Find out what targets the current X11 clipboard holder can handle.  We are
+ * reading the X11 clipboard to make it available to VBox.
+ * @thread  clipboard X11 event thread
+ * @note    Callback for XtGetSelectionValue, called from vboxClipboardPollX11ForTargets
+ */
+static void vboxClipboardGetTargetsFromX11(Widget, XtPointer pClientData,
+                                           Atom * /* selection */,
+                                           Atom *atomType,
+                                           XtPointer pValue,
+                                           long unsigned int *pcLen,
+                                           int *piFormat)
 {
     Atom *atomTargets = reinterpret_cast<Atom *>(pValue);
@@ -534 +557 @@
     Atom atomBestTarget = None;
 
-    Log3 (("vboxClipboardTargetsProc called\n"));
+    Log3 (("%s: called\n", __PRETTY_FUNCTION__));
     if (*atomType == XT_CONVERT_FAIL)
     {
-        Log (("vboxClipboardTargetsProc: reading clipboard from host, X toolkit failed to convert the selection\n"));
+        LogFunc (("reading clipboard from host, X toolkit failed to convert the selection\n"));
         return;
     }
@@ -568 +591 @@
             if (szAtomName != 0)
             {
-                Log2 (("vboxClipboardTargetsProc: the host offers target %s\n", szAtomName));
+                Log2 (("%s: the host offers target %s\n", __PRETTY_FUNCTION__,
+                       szAtomName));
                 XFree(szAtomName);
             }
@@ -582 +606 @@
             {
                 char *szAtomName = XGetAtomName(XtDisplay(g_ctx.widget), atomBestTarget);
-                Log2 (("vboxClipboardTargetsProc: switching to host text target %s.  Available targets are:\n",
-                       szAtomName));
+                Log2 (("%s: switching to host text target %s.  Available targets are:\n",
+                       __PRETTY_FUNCTION__, szAtomName));
                 XFree(szAtomName);
             }
             else
-            {
-                Log2(("vboxClipboardTargetsProc: no supported host text target found.  Available targets are:\n"));
-            }
+                Log2(("%s: no supported host text target found.  Available targets are:\n",
+                      __PRETTY_FUNCTION__));
             for (unsigned i = 0; i < cAtoms; ++i)
             {
@@ -595 +618 @@
                 if (szAtomName != 0)
                 {
-                    Log2 (("vboxClipboardTargetsProc:     %s\n", szAtomName));
+                    Log2 (("%s:     %s\n", __PRETTY_FUNCTION__, szAtomName));
                     XFree(szAtomName);
                 }
@@ -612 +635 @@
 
 /**
- * This callback is called every 200ms to check the contents of the host clipboard.
- */
-static void vboxClipboardTimerProc(XtPointer /* pUserData */, XtIntervalId * /* hTimerId */)
-{
-    Log3 (("vboxClipboardTimerProc called\n"));
+ * This callback is called every 200ms to check the contents of the X11 clipboard.
+ * @thread  clipboard X11 event thread
+ * @note    Callback for XtAppAddTimeOut, called from vboxClipboardThread and
+ *          recursively retriggered
+ */
+static void vboxClipboardPollX11ForTargets(XtPointer /* pUserData */, XtIntervalId * /* hTimerId */)
+{
+    Log3 (("%s: called\n", __PRETTY_FUNCTION__));
     /* Get the current clipboard contents */
     if (g_ctx.eOwner == HOST && g_ctx.pClient != 0)
     {
-        Log3 (("vboxClipboardTimerProc: requesting the targets that the host clipboard offers\n"));
+        Log3 (("%s: requesting the targets that the host clipboard offers\n",
+               __PRETTY_FUNCTION__));
         XtGetSelectionValue(g_ctx.widget, g_ctx.atomClipboard, g_ctx.atomTargets,
-                            vboxClipboardTargetsProc, reinterpret_cast<XtPointer>(g_ctx.pClient),
+                            vboxClipboardGetTargetsFromX11, reinterpret_cast<XtPointer>(g_ctx.pClient),
                             CurrentTime);
     }
     /* Re-arm our timer */
-    XtAppAddTimeOut(g_ctx.appContext, 200 /* ms */, vboxClipboardTimerProc, 0);
+    XtAppAddTimeOut(g_ctx.appContext, 200 /* ms */, vboxClipboardPollX11ForTargets, 0);
 }
 
@@ -646 +673 @@
 /**
  * The main loop of our clipboard reader.
+ * @thread  clipboard X11 event thread
  */
 static int vboxClipboardThread(RTTHREAD self, void * /* pvUser */)
@@ -652 +680 @@
 
     /* Set up a timer to poll the host clipboard */
-    XtAppAddTimeOut(g_ctx.appContext, 200 /* ms */, vboxClipboardTimerProc, 0);
+    XtAppAddTimeOut(g_ctx.appContext, 200 /* ms */, vboxClipboardPollX11ForTargets, 0);
 
     XtAppMainLoop(g_ctx.appContext);
@@ -662 +690 @@
 }
 
+/** X11 specific initialisation for the shared clipboard. */
 int vboxClipboardInitX11 (void)
 {
@@ -737 +766 @@
 }
 
-/** Initialise the host side of the shared clipboard - called by the hgcm layer. */
+/**
+ * Initialise the host side of the shared clipboard.
+ * @note    Called by the HGCM clipboard service
+ * @thread  HGCM clipboard service thread
+ */
 int vboxClipboardInit (void)
 {
@@ -796 +829 @@
 }
 
-/** Terminate the host side of the shared clipboard - called by the hgcm layer. */
+/**
+ * Terminate the host side of the shared clipboard.
+ * @note    Called by the HGCM clipboard service
+ * @thread  HGCM clipboard service thread
+ */
 void vboxClipboardDestroy (void)
 {
@@ -804 +841 @@
 
     /*
-     * Immetiately return if we are not connected to the host X server.
+     * Immediately return if we are not connected to the host X server.
      */
     if (!g_fHaveX11)
@@ -834 +871 @@
 
 /**
-  * Enable the shared clipboard - called by the hgcm clipboard subsystem.
-  *
-  * @param   pClient Structure containing context information about the guest system
-  * @returns RT status code
-  */
+ * Connect a guest the shared clipboard.
+ *
+ * @param   pClient Structure containing context information about the guest system
+ * @returns RT status code
+ * @note    Called by the HGCM clipboard service
+ * @thread  HGCM clipboard service thread
+ */
 int vboxClipboardConnect (VBOXCLIPBOARDCLIENTDATA *pClient)
 {
     /*
-     * Immetiately return if we are not connected to the host X server.
+     * Immediately return if we are not connected to the host X server.
      */
     if (!g_fHaveX11)
@@ -864 +903 @@
 
 /**
- * Synchronise the contents of the host clipboard with the guest, called by the HGCM layer
+ * Synchronise the contents of the host clipboard with the guest, called
  * after a save and restore of the guest.
+ * @note    Called by the HGCM clipboard service
+ * @thread  HGCM clipboard service thread
  */
 int vboxClipboardSync (VBOXCLIPBOARDCLIENTDATA *pClient)
 {
     /*
-     * Immetiately return if we are not connected to the host X server.
+     * Immediately return if we are not connected to the host X server.
      */
     if (!g_fHaveX11)
@@ -886 +927 @@
 
 /**
- * Shut down the shared clipboard subsystem and "disconnect" the guest.
- */
-void vboxClipboardDisconnect (VBOXCLIPBOARDCLIENTDATA *pClient)
+ * Shut down the shared clipboard service and "disconnect" the guest.
+ * @note    Called by the HGCM clipboard service
+ * @thread  HGCM clipboard service thread
+ */
+void vboxClipboardDisconnect (VBOXCLIPBOARDCLIENTDATA *)
 {
     /*
-     * Immetiately return if we are not connected to the host X server.
+     * Immediately return if we are not connected to the host X server.
      */
     if (!g_fHaveX11)
@@ -907 +950 @@
 
 /**
- * Satisfy a request from the host for available clipboard targets.
+ * Satisfy a request from X11 for clipboard targets supported by VBox.
  *
  * @returns true if we successfully convert the data to the format requested, false otherwise.
  *
- * @param atomTypeReturn The type of the data we are returning
- * @param pValReturn     A pointer to the data we are returning.  This should be to memory
- *                       allocated by XtMalloc, which will be freed by the toolkit later
- * @param pcLenReturn    The length of the data we are returning
- * @param piFormatReturn The format (8bit, 16bit, 32bit) of the data we are returning
- */
-static Boolean vboxClipboardConvertTargets(Atom *atomTypeReturn, XtPointer *pValReturn,
-                                           unsigned long *pcLenReturn, int *piFormatReturn)
+ * @param  atomTypeReturn The type of the data we are returning
+ * @param  pValReturn     A pointer to the data we are returning.  This should be to memory
+ *                        allocated by XtMalloc, which will be freed by the toolkit later
+ * @param  pcLenReturn    The length of the data we are returning
+ * @param  piFormatReturn The format (8bit, 16bit, 32bit) of the data we are returning
+ * @thread  clipboard X11 event thread
+ * @note    called by vboxClipboardConvertForX11
+ */
+static Boolean vboxClipboardConvertTargetsForX11(Atom *atomTypeReturn, XtPointer *pValReturn,
+                                                 unsigned long *pcLenReturn, int *piFormatReturn)
 {
     unsigned uListSize = g_ctx.formatList.size();
@@ -924 +969 @@
     unsigned cTargets = 0;
 
-    LogFlow (("vboxClipboardConvertTargets called\n"));
+    LogFlowFunc (("called\n"));
     for (unsigned i = 0; i < uListSize; ++i)
     {
@@ -944 +989 @@
             if (szAtomName != 0)
             {
-                Log2 (("vboxClipboardConvertTargets: returning target %s\n", szAtomName));
+                Log2 (("%s: returning target %s\n", __PRETTY_FUNCTION__,
+                       szAtomName));
                 XFree(szAtomName);
             }
             else
             {
-                Log(("vboxClipboardConvertTargets: invalid atom %d in the list!\n", atomTargets[i]));
+                Log(("%s: invalid atom %d in the list!\n", __PRETTY_FUNCTION__,
+                     atomTargets[i]));
             }
         }
@@ -961 +1008 @@
 
 /**
- * Reset the contents of the buffer used to pass clipboard data from the guest to the host.
+ * Reset the contents of the buffer used to pass clipboard data from VBox to X11.
  * This must be done after every clipboard transfer.
  */
@@ -993 +1040 @@
 
     LogFlowFunc (("called\n"));
-    rc = vboxClipboardReadDataFromClient(&g_ctx, VBOX_SHARED_CLIPBOARD_FMT_UNICODETEXT);
+    rc = vboxClipboardReadDataFromVBox(&g_ctx, VBOX_SHARED_CLIPBOARD_FMT_UNICODETEXT);
     if ((RT_FAILURE(rc)) || (g_ctx.pClient->data.cb == 0))
     {
-        /* If vboxClipboardReadDataFromClient fails then pClient may be invalid */
-        LogRelFunc (("vboxClipboardReadDataFromClient returned %Rrc%s\n", rc,
+        /* If vboxClipboardReadDataFromVBox fails then pClient may be invalid */
+        LogRelFunc (("vboxClipboardReadDataFromVBox returned %Rrc%s\n", rc,
                      RT_SUCCESS(rc) ? ", g_ctx.pClient->data.cb == 0" :  ""));
         vboxClipboardEmptyGuestBuffer();
@@ -1048 +1095 @@
  * @returns true if we successfully convert the data to the format requested, false otherwise.
  *
- * @param atomTypeReturn The type of the data we are returning
- * @param pValReturn     A pointer to the data we are returning.  This should be to memory
- *                       allocated by XtMalloc, which will be freed by the toolkit later
- * @param pcLenReturn    The length of the data we are returning
- * @param piFormatReturn The format (8bit, 16bit, 32bit) of the data we are returning
- */
-static Boolean vboxClipboardConvertUtf8(Atom *atomTypeReturn, XtPointer *pValReturn,
-                                        unsigned long *pcLenReturn, int *piFormatReturn)
+ * @param  atomTypeReturn The type of the data we are returning
+ * @param  pValReturn     A pointer to the data we are returning.  This should be to memory
+ *                        allocated by XtMalloc, which will be freed by the toolkit later
+ * @param  pcLenReturn    The length of the data we are returning
+ * @param  piFormatReturn The format (8bit, 16bit, 32bit) of the data we are returning
+ * @thread  clipboard X11 event thread
+ * @note    called by vboxClipboardConvertForX11
+ */
+static Boolean vboxClipboardConvertToUtf8ForX11(Atom *atomTypeReturn,
+                                                XtPointer *pValReturn,
+                                                unsigned long *pcLenReturn,
+                                                int *piFormatReturn)
 {
     PRTUTF16 pu16SrcText, pu16DestText;
@@ -1064 +1115 @@
     LogFlowFunc (("called\n"));
     /* Read the clipboard data from the guest. */
-    rc = vboxClipboardReadDataFromClient(&g_ctx, VBOX_SHARED_CLIPBOARD_FMT_UNICODETEXT);
+    rc = vboxClipboardReadDataFromVBox(&g_ctx, VBOX_SHARED_CLIPBOARD_FMT_UNICODETEXT);
     if ((rc != VINF_SUCCESS) || (g_ctx.pClient->data.cb == 0))
     {
-        /* If vboxClipboardReadDataFromClient fails then pClient may be invalid */
-        LogRelFunc (("vboxClipboardReadDataFromClient returned %Rrc%s\n", rc,
-                     RT_SUCCESS(rc) ? ", g_ctx.pClient->data.cb == 0" :  ""));
+        /* If vboxClipboardReadDataFromVBox fails then pClient may be invalid */
+        LogRelFunc (("vboxClipboardReadDataFromVBox returned %Rrc%s\n", rc,
+                      RT_SUCCESS(rc) ? ", g_ctx.pClient->data.cb == 0" :  ""));
         vboxClipboardEmptyGuestBuffer();
         return false;
@@ -1079 +1130 @@
     if (RT_FAILURE(rc))
     {
-        LogRel(("vboxClipboardConvertUtf8: clipboard conversion failed.  vboxClipboardUtf16GetLinSize returned %Rrc.  Abandoning.\n", rc));
+        LogRelFunc (("clipboard conversion failed.  vboxClipboardUtf16GetLinSize returned %Rrc.  Abandoning.\n", rc));
         vboxClipboardEmptyGuestBuffer();
         AssertRCReturn(rc, false);
@@ -1092 +1143 @@
     if (pu16DestText == 0)
     {
-        LogRel(("vboxClipboardConvertUtf8: failed to allocate %d bytes\n", cwDestLen * 2));
+        LogRelFunc (("failed to allocate %d bytes\n", cwDestLen * 2));
         vboxClipboardEmptyGuestBuffer();
         return false;
@@ -1100 +1151 @@
     if (RT_FAILURE(rc))
     {
-        LogRel(("vboxClipboardConvertUtf8: clipboard conversion failed.  vboxClipboardUtf16WinToLin() returned %Rrc.  Abandoning.\n", rc));
+        LogRelFunc (("clipboard conversion failed.  vboxClipboardUtf16WinToLin() returned %Rrc.  Abandoning.\n", rc));
         RTMemFree(reinterpret_cast<void *>(pu16DestText));
         vboxClipboardEmptyGuestBuffer();
@@ -1110 +1161 @@
     if (pu8DestText == 0)
     {
-        LogRel(("vboxClipboardConvertUtf8: failed to allocate %d bytes\n", cwDestLen * 4));
+        LogRelFunc (("failed to allocate %d bytes\n", cwDestLen * 4));
         RTMemFree(reinterpret_cast<void *>(pu16DestText));
         vboxClipboardEmptyGuestBuffer();
@@ -1121 +1172 @@
     if (RT_FAILURE(rc))
     {
-        LogRel(("vboxClipboardConvertUtf8: clipboard conversion failed.  RTUtf16ToUtf8Ex() returned %Rrc.  Abandoning.\n", rc));
+        LogRelFunc (("clipboard conversion failed.  RTUtf16ToUtf8Ex() returned %Rrc.  Abandoning.\n", rc));
         XtFree(pu8DestText);
         vboxClipboardEmptyGuestBuffer();
@@ -1140 +1191 @@
  * @returns true if we successfully convert the data to the format requested, false otherwise.
  *
- * @param atomTypeReturn The type of the data we are returning
- * @param pValReturn     A pointer to the data we are returning.  This should be to memory
- *                       allocated by XtMalloc, which will be freed by the toolkit later
- * @param pcLenReturn    The length of the data we are returning
- * @param piFormatReturn The format (8bit, 16bit, 32bit) of the data we are returning
- */
-static Boolean vboxClipboardConvertCText(Atom *atomTypeReturn, XtPointer *pValReturn,
-                                         unsigned long *pcLenReturn, int *piFormatReturn)
+ * @param  atomTypeReturn The type of the data we are returning
+ * @param  pValReturn     A pointer to the data we are returning.  This should be to memory
+ *                        allocated by XtMalloc, which will be freed by the toolkit later
+ * @param  pcLenReturn    The length of the data we are returning
+ * @param  piFormatReturn The format (8bit, 16bit, 32bit) of the data we are returning
+ * @thread  clipboard X11 event thread
+ * @note    called by vboxClipboardConvertForX11
+ */
+static Boolean vboxClipboardConvertToCTextForX11(Atom *atomTypeReturn,
+                                                 XtPointer *pValReturn,
+                                                 unsigned long *pcLenReturn,
+                                                 int *piFormatReturn)
 {
     PRTUTF16 pu16SrcText, pu16DestText;
@@ -1157 +1212 @@
     LogFlowFunc (("called\n"));
     /* Read the clipboard data from the guest. */
-    rc = vboxClipboardReadDataFromClient(&g_ctx, VBOX_SHARED_CLIPBOARD_FMT_UNICODETEXT);
+    rc = vboxClipboardReadDataFromVBox(&g_ctx, VBOX_SHARED_CLIPBOARD_FMT_UNICODETEXT);
     if ((rc != VINF_SUCCESS) || (g_ctx.pClient->data.cb == 0))
     {
-        /* If vboxClipboardReadDataFromClient fails then pClient may be invalid */
-        LogRelFunc (("vboxClipboardReadDataFromClient returned %Rrc%s\n", rc,
-                     RT_SUCCESS(rc) ? ", g_ctx.pClient->data.cb == 0" :  ""));
+        /* If vboxClipboardReadDataFromVBox fails then pClient may be invalid */
+        LogRelFunc (("vboxClipboardReadDataFromVBox returned %Rrc%s\n", rc,
+                      RT_SUCCESS(rc) ? ", g_ctx.pClient->data.cb == 0" :  ""));
         vboxClipboardEmptyGuestBuffer();
         return false;
@@ -1172 +1227 @@
     if (RT_FAILURE(rc))
     {
-        LogRel(("vboxClipboardConvertCText: clipboard conversion failed.  vboxClipboardUtf16GetLinSize returned %Rrc.  Abandoning.\n", rc));
+        LogRelFunc (("clipboard conversion failed.  vboxClipboardUtf16GetLinSize returned %Rrc.  Abandoning.\n", rc));
         vboxClipboardEmptyGuestBuffer();
         AssertRCReturn(rc, false);
@@ -1185 +1240 @@
     if (pu16DestText == 0)
     {
-        LogRel(("vboxClipboardConvertCText: failed to allocate %d bytes\n", cwDestLen * 2));
+        LogRelFunc (("failed to allocate %d bytes\n", cwDestLen * 2));
         vboxClipboardEmptyGuestBuffer();
         return false;
@@ -1193 +1248 @@
     if (RT_FAILURE(rc))
     {
-        LogRel(("vboxClipboardConvertCText: clipboard conversion failed.  vboxClipboardUtf16WinToLin() returned %Rrc.  Abandoning.\n", rc));
+        LogRelFunc (("clipboard conversion failed.  vboxClipboardUtf16WinToLin() returned %Rrc.  Abandoning.\n", rc));
         RTMemFree(reinterpret_cast<void *>(pu16DestText));
         vboxClipboardEmptyGuestBuffer();
@@ -1203 +1258 @@
     if (RT_FAILURE(rc))
     {
-        LogRel(("vboxClipboardConvertCText: clipboard conversion failed.  RTUtf16ToUtf8Ex() returned %Rrc.  Abandoning.\n", rc));
+        LogRelFunc (("clipboard conversion failed.  RTUtf16ToUtf8Ex() returned %Rrc.  Abandoning.\n", rc));
         vboxClipboardEmptyGuestBuffer();
         return false;
@@ -1233 +1288 @@
             pcReason = "unknown error";
         }
-        LogRel(("vboxClipboardConvertCText: Xutf8TextListToTextProperty failed.  Reason: %s\n",
+        LogRelFunc (("Xutf8TextListToTextProperty failed.  Reason: %s\n",
                 pcReason));
         XFree(property.value);
@@ -1249 +1304 @@
 
 /**
- * Callback to convert the guests clipboard data for an application on the host.  Called by the
+ * Callback to request VBox's clipboard data for an X11 client.  Called by the
  * X Toolkit.
- * @returns true if we successfully convert the data to the format requested, false otherwise.
- *
- * @param atomSelection  The selection which is being requested.  We only handle the clipboard.
- * @param atomTarget     The format we should convert the data to
- * @param atomTypeReturn The type of the data we are returning
- * @param pValReturn     A pointer to the data we are returning.  This should be to memory
- *                       allocated by XtMalloc, which will be freed by the toolkit later
- * @param pcLenReturn    The length of the data we are returning
- * @param piFormatReturn The format (8bit, 16bit, 32bit) of the data we are returning
- */
-static Boolean vboxClipboardConvertProc(Widget, Atom *atomSelection, Atom *atomTarget,
-                                        Atom *atomTypeReturn, XtPointer *pValReturn,
-                                        unsigned long *pcLenReturn, int *piFormatReturn)
+ * @thread  clipboard X11 event thread
+ * @note    callback for XtOwnSelection, called by vboxClipboardFormatAnnounce
+ */
+static Boolean vboxClipboardConvertForX11(Widget, Atom *atomSelection,
+                                          Atom *atomTarget,
+                                          Atom *atomTypeReturn,
+                                          XtPointer *pValReturn,
+                                          unsigned long *pcLenReturn,
+                                          int *piFormatReturn)
 {
     g_eClipboardFormats eFormat = INVALID;
@@ -1280 +1331 @@
         if (szAtomName != 0)
         {
-            Log2 (("vboxClipboardConvertProc: request for format %s\n", szAtomName));
+            Log2 (("%s: request for format %s\n", __PRETTY_FUNCTION__, szAtomName));
             XFree(szAtomName);
         }
         else
         {
-            Log(("vboxClipboardConvertProc: request for invalid target atom %d!\n", *atomTarget));
+            LogFunc (("request for invalid target atom %d!\n", *atomTarget));
         }
     }
@@ -1306 +1357 @@
     {
     case TARGETS:
-        return vboxClipboardConvertTargets(atomTypeReturn, pValReturn, pcLenReturn,
-                                           piFormatReturn);
+        return vboxClipboardConvertTargetsForX11(atomTypeReturn, pValReturn,
+                                                 pcLenReturn, piFormatReturn);
     case UTF16:
         return vboxClipboardConvertUtf16(atomTypeReturn, pValReturn, pcLenReturn,
                                          piFormatReturn);
     case UTF8:
-        return vboxClipboardConvertUtf8(atomTypeReturn, pValReturn, pcLenReturn,
-                                        piFormatReturn);
+        return vboxClipboardConvertToUtf8ForX11(atomTypeReturn, pValReturn,
+                                                pcLenReturn, piFormatReturn);
     case CTEXT:
-        return vboxClipboardConvertCText(atomTypeReturn, pValReturn, pcLenReturn,
-                                         piFormatReturn);
+        return vboxClipboardConvertToCTextForX11(atomTypeReturn, pValReturn,
+                                                 pcLenReturn, piFormatReturn);
     default:
-        Log(("vboxClipboardConvertProc: bad format\n"));
-        return false;
-    }
-}
-
-static void vboxClipboardLoseProc(Widget, Atom *)
-{
-    LogFlow (("vboxClipboardLoseProc: called, giving the host clipboard ownership\n"));
+        LogFunc (("bad format\n"));
+        return false;
+    }
+}
+
+/**
+ * This is called by the X toolkit intrinsics to let us know that another
+ * X11 client has taken the clipboard.
+ * @note    callback for XtOwnSelection, called from vboxClipboardFormatAnnounce
+ * @thread  clipboard X11 event thread
+ */
+static void vboxClipboardReturnToX11(Widget, Atom *)
+{
+    LogFlowFunc (("called, giving VBox clipboard ownership\n"));
     g_ctx.eOwner = HOST;
     g_ctx.notifyGuest = true;
@@ -1331 +1388 @@
 
 /**
- * The guest is taking possession of the shared clipboard.  Called by the HGCM clipboard
- * subsystem.
+ * VBox is taking possession of the shared clipboard.
  *
  * @param pClient    Context data for the guest system
  * @param u32Formats Clipboard formats the guest is offering
+ * @note    Called by the HGCM clipboard service
+ * @thread  HGCM clipboard service thread
  */
 void vboxClipboardFormatAnnounce (VBOXCLIPBOARDCLIENTDATA *pClient, uint32_t u32Formats)
 {
     /*
-     * Immetiately return if we are not connected to the host X server.
+     * Immediately return if we are not connected to the host X server.
      */
     if (!g_fHaveX11)
@@ -1361 +1419 @@
         return;
     }
-    Log2 (("vboxClipboardFormatAnnounce: giving the guest clipboard ownership\n"));
+    Log2 (("%s: giving the guest clipboard ownership\n", __PRETTY_FUNCTION__));
     g_ctx.eOwner = GUEST;
     g_ctx.hostTextFormat = INVALID;
     g_ctx.hostBitmapFormat = INVALID;
-    if (XtOwnSelection(g_ctx.widget, g_ctx.atomClipboard, CurrentTime, vboxClipboardConvertProc,
-                       vboxClipboardLoseProc, 0) != True)
-    {
-        Log2 (("vboxClipboardFormatAnnounce: returning clipboard ownership to the host\n"));
+    if (XtOwnSelection(g_ctx.widget, g_ctx.atomClipboard, CurrentTime, vboxClipboardConvertForX11,
+                       vboxClipboardReturnToX11, 0) != True)
+    {
+        Log2 (("%s: returning clipboard ownership to the host\n", __PRETTY_FUNCTION__));
         /* We set this so that the guest gets notified when we take the clipboard, even if no
           guest formats are found which we understand. */
@@ -1374 +1432 @@
         g_ctx.eOwner = HOST;
     }
-    XtOwnSelection(g_ctx.widget, g_ctx.atomPrimary, CurrentTime, vboxClipboardConvertProc,
+    XtOwnSelection(g_ctx.widget, g_ctx.atomPrimary, CurrentTime, vboxClipboardConvertForX11,
                    NULL, 0);
     LogFlowFunc(("returning\n"));
@@ -1381 +1439 @@
 
 /**
- * Called by the HGCM clipboard subsystem when the guest wants to read the host clipboard.
+ * Called when VBox wants to read the X11 clipboard.
  *
  * @param pClient   Context information about the guest VM
@@ -1388 +1446 @@
  * @param cb        The size of the buffer to write the data to
  * @param pcbActual Where to write the actual size of the written data
+ * @note    Called by the HGCM clipboard service
+ * @thread  HGCM clipboard service thread
  */
 int vboxClipboardReadData (VBOXCLIPBOARDCLIENTDATA *pClient, uint32_t u32Format, void *pv,
@@ -1393 +1453 @@
 {
     /*
-     * Immetiately return if we are not connected to the host X server.
+     * Immediately return if we are not connected to the host X server.
      */
     if (!g_fHaveX11)
@@ -1402 +1462 @@
     }
 
-    LogFlow(("vboxClipboardReadData: u32Format = %d, cb = %d\n", u32Format, cb));
+    LogFlowFunc (("u32Format = %d, cb = %d\n", u32Format, cb));
 
     /*
@@ -1430 +1490 @@
         /* Send out a request for the data to the current clipboard owner */
         XtGetSelectionValue(g_ctx.widget, g_ctx.atomClipboard, g_ctx.atomHostTextFormat,
-                            vboxClipboardGetProc, reinterpret_cast<XtPointer>(g_ctx.pClient),
+                            vboxClipboardGetDataFromX11, reinterpret_cast<XtPointer>(g_ctx.pClient),
                             CurrentTime);
         /* When the data arrives, the vboxClipboardGetProc callback will be called.  The
@@ -1466 +1526 @@
 
 /**
- * Called by the HGCM clipboard subsystem when we have requested data and that data arrives.
+ * Called when we have requested data from VBox and that data has arrived.
  *
  * @param pClient   Context information about the guest VM
@@ -1472 +1532 @@
  * @param cb        The size of the data written
  * @param u32Format The format of the data written
+ * @note    Called by the HGCM clipboard service
+ * @thread  HGCM clipboard service thread
  */
 void vboxClipboardWriteData (VBOXCLIPBOARDCLIENTDATA *pClient, void *pv, uint32_t cb, uint32_t u32Format)
@@ -1478 +1540 @@
         return;
 
-    LogFlow(("vboxClipboardWriteData\n"));
+    LogFlowFunc (("called\n"));
 
     /*