Changeset 7241 in vbox for trunk/src/VBox/HostServices

Timestamp:

Mar 3, 2008 2:24:56 PM (17 years ago)

Author:

vboxsync

Message:

Mac OS X: Added some documentation to the pasteboard methods. Removed the outstanding todo issues.

Location:

trunk/src/VBox/HostServices/SharedClipboard

Files:

• darwin-pasteboard.cpp (modified) (12 diffs)
• darwin-pasteboard.h (modified) (1 diff)
• darwin.cpp (modified) (3 diffs)

trunk/src/VBox/HostServices/SharedClipboard/darwin-pasteboard.cpp

@@ -16 +16 @@
  */
 
-/// @todo: same as defined in VBoxClipboardSvc.h
-/// @todo r-bird: why don't you include it?
-#define VBOX_SHARED_CLIPBOARD_FMT_UNICODETEXT 0x01
-#define VBOX_SHARED_CLIPBOARD_FMT_BITMAP      0x02
-#define VBOX_SHARED_CLIPBOARD_FMT_HTML        0x04
-
 #include <Carbon/Carbon.h>
 
@@ -30 +24 @@
 #define LOG_GROUP LOG_GROUP_HGCM
 #include "VBox/log.h"
+#include "VBox/HostServices/VBoxClipboardSvc.h"
 #include "clipboard-helper.h"
 
+/* For debugging */
 //#define SHOW_CLIPBOARD_CONTENT
 
-/** @todo r=bird: document these functions */
-
+/**
+ * Initialize the global pasteboard and return a reference to it.
+ * 
+ * @param pPasteboardRef Reference to the global pasteboard.
+ *
+ * @returns IPRT status code.
+ */
 int initPasteboard (PasteboardRef *pPasteboardRef)
 {
@@ -46 +47 @@
 }
 
+/**
+ * Release the reference to the global pasteboard.
+ * 
+ * @param pPasteboardRef Reference to the global pasteboard.
+ */
 void destroyPasteboard (PasteboardRef *pPasteboardRef)
 {
@@ -52 +58 @@
 }
 
-int queryPasteboardFormats (PasteboardRef pPasteboard, uint32_t *pfFormats)
-{
-    Log (("queryPasteboardFormats\n"));
+/**
+ * Inspect the global pasteboard for new content. Check if there is some type
+ * that is supported by vbox and return it.
+ * 
+ * @param   pPasteboardRef Reference to the global pasteboard.
+ * @param   pfFormats      Pointer for the bit combination of the
+ *                         supported types.
+ *
+ * @returns IPRT status code.
+ */
+int queryNewPasteboardFormats (PasteboardRef pPasteboard, uint32_t *pfFormats)
+{
+    Log (("queryNewPasteboardFormats\n"));
 
     OSStatus err = noErr;
@@ -71 +87 @@
         return VINF_SUCCESS;
 
-    /* The id of the first element in the pastboard */
+    /* The id of the first element in the pasteboard */
     int rc = VERR_NOT_SUPPORTED;
     PasteboardItemID itemID;
@@ -101 +117 @@
     }
 
-    Log (("queryPasteboardFormats: rc = %02X\n", rc));
+    Log (("queryNewPasteboardFormats: rc = %02X\n", rc));
     return rc;
 }
 
+/**
+ * Read content from the host clipboard and write it to the internal clipboard
+ * structure for further processing.
+ * 
+ * @param   pPasteboardRef Reference to the global pasteboard.
+ * @param   fFormats       The format type which should be read.
+ * @param   pv             The destination buffer.
+ * @param   cb             The size of the destination buffer.
+ * @param   pcbActual      The size which is needed to transfer the content.
+ *
+ * @returns IPRT status code.
+ */
 int readFromPasteboard (PasteboardRef pPasteboard, uint32_t fFormat, void *pv, uint32_t cb, uint32_t *pcbActual)
 {
-    Log (("readFromPastboard: fFormat = %02X\n", fFormat));
+    Log (("readFromPasteboard: fFormat = %02X\n", fFormat));
 
     OSStatus err = noErr;
@@ -120 +148 @@
         return VINF_SUCCESS;
 
-    /* The id of the first element in the pastboard */
+    /* The id of the first element in the pasteboard */
     int rc = VERR_NOT_SUPPORTED;
     PasteboardItemID itemID;
@@ -144 +172 @@
                 if (!(err = PasteboardCopyItemFlavorData (pPasteboard, itemID, CFSTR ("public.utf8-plain-text"), &outData)))
                 {
-                    Log (("readFromPastboard: clipboard content is utf-8\n"));
+                    Log (("readFromPasteboard: clipboard content is utf-8\n"));
                     rc = RTStrToUtf16 ((const char*)CFDataGetBytePtr (outData), &pwszTmp);
                 }
@@ -156 +184 @@
                 {
                     RTUtf16Free (pwszTmp);
-                    Log (("readFromPastboard: clipboard conversion failed.  vboxClipboardUtf16GetWinSize returned %Vrc.  Abandoning.\n", rc));
+                    Log (("readFromPasteboard: clipboard conversion failed.  vboxClipboardUtf16GetWinSize returned %Vrc.  Abandoning.\n", rc));
                     AssertRCReturn (rc, rc);
                 }
@@ -170 +198 @@
                     {
                         RTUtf16Free (pwszTmp);
-                        Log (("readFromPastboard: clipboard conversion failed.  vboxClipboardUtf16LinToWin() returned %Vrc.  Abandoning.\n", rc));
+                        Log (("readFromPasteboard: clipboard conversion failed.  vboxClipboardUtf16LinToWin() returned %Vrc.  Abandoning.\n", rc));
                         AssertRCReturn (rc, rc);
                     }
 #ifdef SHOW_CLIPBOARD_CONTENT
-                    Log (("readFromPastboard: clipboard content: %ls\n", static_cast <PRTUTF16> (pv)));
+                    Log (("readFromPasteboard: clipboard content: %ls\n", static_cast <PRTUTF16> (pv)));
 #endif
                 }
@@ -183 +211 @@
     }
 
-    Log (("readFromPastboard: rc = %02X\n", rc));
+    Log (("readFromPasteboard: rc = %02X\n", rc));
     return rc;
 }
 
+/**
+ * Write clipboard content to the host clipboard from the internal clipboard
+ * structure.
+ * 
+ * @param   pPasteboardRef Reference to the global pasteboard.
+ * @param   pv             The source buffer.
+ * @param   cb             The size of the source buffer.
+ * @param   fFormats       The format type which should be written.
+ *
+ * @returns IPRT status code.
+ */
 int writeToPasteboard (PasteboardRef pPasteboard, void *pv, uint32_t cb, uint32_t fFormat)
 {
     Log (("writeToPasteboard: fFormat = %02X\n", fFormat));
 
-    /* Clear the pastboard */
+    /* Clear the pasteboard */
     if (PasteboardClear (pPasteboard))
         return VERR_NOT_SUPPORTED;
@@ -253 +292 @@
             /* Create a CData object which we could pass to the pasteboard */
             if ((textData = CFDataCreate (kCFAllocatorDefault,
-                                          reinterpret_cast<UInt8*> (pszDestText), RTUtf16CalcUtf8Len (pwszDestText)))) /** @todo r=bird: why not strlen(pszDestText)? */
+                                          reinterpret_cast<UInt8*> (pszDestText), strlen(pszDestText))))
             {
                 /* Put the Utf-8 version to the pasteboard */

trunk/src/VBox/HostServices/SharedClipboard/darwin-pasteboard.h

@@ -25 +25 @@
 void destroyPasteboard (PasteboardRef *pPasteboardRef);
 
-int queryPasteboardFormats (PasteboardRef pPasteboard, uint32_t *pfFormats);
+int queryNewPasteboardFormats (PasteboardRef pPasteboard, uint32_t *pfFormats);
 int readFromPasteboard (PasteboardRef pPasteboard, uint32_t fFormat, void *pv, uint32_t cb, uint32_t *pcbActual);
 int writeToPasteboard (PasteboardRef pPasteboard, void *pv, uint32_t cb, uint32_t fFormat);

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

@@ -23 +23 @@
 
 #include "VBoxClipboard.h"
-/* We do the work in a separate cpp file because
- * of the conflicting typedef "OSType". This is
- * defined in Carbon and in VBox/ostypes.h also. */
 #include "darwin-pasteboard.h"
 
@@ -50 +47 @@
  * @returns IPRT status code (ignored).
  * @param   pCtx    The context.
- * 
- * @todo r=bird: This function does not check if something has _changed_ like indicated by 
- *               the name. It will instead notify the client every 200ms as long as something
- *               is on the clipboard. When the clipboard is cleared it will do nothing.
- *               I somehow cannot think that this intentional behavior...
  */
 static int vboxClipboardChanged (VBOXCLIPBOARDCONTEXT *pCtx)
@@ -63 +55 @@
     uint32_t fFormats = 0;
     /* Retrieve the formats currently in the clipboard and supported by vbox */
-    int rc = queryPasteboardFormats (pCtx->pasteboard, &fFormats);
+    int rc = queryNewPasteboardFormats (pCtx->pasteboard, &fFormats);
 
     if (fFormats > 0)