Changeset 81174 in vbox

Timestamp:

Oct 9, 2019 9:06:38 AM (5 years ago)

Author:

vboxsync

Message:

Shared Clipboard: Docs.

Location:

trunk/src/VBox/HostServices/SharedClipboard

Files:

• VBoxSharedClipboardSvc-darwin.cpp (modified) (3 diffs)
• VBoxSharedClipboardSvc-internal.h (modified) (1 diff)
• VBoxSharedClipboardSvc-x11.cpp (modified) (7 diffs)

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

@@ -119 +119 @@
 int ShClSvcImplInit(void)
 {
-    Log(("vboxClipboardInit\n"));
-
     g_ctx.fTerminate = false;
 
@@ -228 +226 @@
 }
 
-/**
- * Called by the HGCM clipboard subsystem when the guest wants to read the host clipboard.
- *
- * @param pClient               Context information about the guest VM.
- * @param pCmdCtx               Command context to use for reading the data. Currently unused.
- * @param pData                 Data block to put read data into.
- * @param pcbActual             Where to write the actual size of the written data.
- */
 int ShClSvcImplReadData(PSHCLCLIENT pClient, PSHCLCLIENTCMDCTX pCmdCtx,
                         PSHCLDATABLOCK pData, uint32_t *pcbActual)
@@ -254 +244 @@
 }
 
-/**
- * Called by the HGCM clipboard subsystem when we have requested data and that data arrives.
- *
- *
- * @param pClient               Context information about the guest VM.
- * @param pCmdCtx               Command context to use for writing the data. Currently unused.
- * @param pData                 Data block to write to clipboard.
- */
 int ShClSvcImplWriteData(PSHCLCLIENT pClient,
                          PSHCLCLIENTCMDCTX pCmdCtx, PSHCLDATABLOCK pData)

trunk/src/VBox/HostServices/SharedClipboard/VBoxSharedClipboardSvc-internal.h

@@ -197 +197 @@
 
 # ifdef VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS
-int shclSvcTransferStart(PSHCLCLIENT pClient,
-                         SHCLTRANSFERDIR enmDir, SHCLSOURCE enmSource,
-                         PSHCLTRANSFER *ppTransfer);
+int shclSvcTransferStart(PSHCLCLIENT pClient, SHCLTRANSFERDIR enmDir, SHCLSOURCE enmSource, PSHCLTRANSFER *ppTransfer);
 int shclSvcTransferStop(PSHCLCLIENT pClient, PSHCLTRANSFER pTransfer);
 bool shclSvcTransferMsgIsAllowed(uint32_t uMode, uint32_t uMsg);
-# endif /* VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS */
+#endif /* VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS */
 
 /*
  * Platform-dependent implementations.
  */
+/**
+ * Called on initialization.
+ */
 int ShClSvcImplInit(void);
+/**
+ * Called on destruction.
+ */
 void ShClSvcImplDestroy(void);
-
+/**
+ * Called when a new HGCM client connects.
+ *
+ * @returns VBox status code.
+ * @param   pClient             Shared Clipboard client context.
+ * @param   fHeadless           Whether this is a headless connection or not.
+ */
 int ShClSvcImplConnect(PSHCLCLIENT pClient, bool fHeadless);
+/**
+ * Called when a HGCM client disconnects.
+ *
+ * @returns VBox status code.
+ * @param   pClient             Shared Clipboard client context.
+ */
 int ShClSvcImplDisconnect(PSHCLCLIENT pClient);
+/**
+ * Called when the guest reported available clipboard formats to the host OS.
+ *
+ * @returns VBox status code.
+ * @param   pClient             Shared Clipboard client context.
+ * @param   pCmdCtx             Shared Clipboard command context.
+ * @param   pFormats            Announced formats from the guest.
+ */
 int ShClSvcImplFormatAnnounce(PSHCLCLIENT pClient, PSHCLCLIENTCMDCTX pCmdCtx, PSHCLFORMATDATA pFormats);
 /** @todo Document: Can return VINF_HGCM_ASYNC_EXECUTE to defer returning read data.*/
+/**
+ * Called when the guest wants to read host clipboard data.
+ *
+ * @returns VBox status code.
+ * @param   pClient             Shared Clipboard client context.
+ * @param   pCmdCtx             Shared Clipboard command context.
+ * @param   pData               Where to return the read clipboard data.
+ * @param   pcbActual           Where to return the amount of bytes read.
+ */
 int ShClSvcImplReadData(PSHCLCLIENT pClient, PSHCLCLIENTCMDCTX pCmdCtx, PSHCLDATABLOCK pData, uint32_t *pcbActual);
+/**
+ * Called when the guest writes clipboard data to the host.
+ *
+ * @returns VBox status code.
+ * @param   pClient             Shared Clipboard client context.
+ * @param   pCmdCtx             Shared Clipboard command context.
+ * @param   pData               Clipboard data from the guest.
+ */
 int ShClSvcImplWriteData(PSHCLCLIENT pClient, PSHCLCLIENTCMDCTX pCmdCtx, PSHCLDATABLOCK pData);
 /**
  * Synchronise the contents of the host clipboard with the guest, called by the HGCM layer
  * after a save and restore of the guest.
+ *
+ * @returns VBox status code.
+ * @param   pClient             Shared Clipboard client context.
  */
 int ShClSvcImplSync(PSHCLCLIENT pClient);

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

@@ -78 +78 @@
 }
 
-/**
- * Initialise the host side of the shared clipboard.
- * @note  Host glue code
- */
 int ShClSvcImplInit(void)
 {
@@ -88 +84 @@
 }
 
-/**
- * Terminate the host side of the shared clipboard.
- * @note  host glue code
- */
 void ShClSvcImplDestroy(void)
 {
@@ -98 +90 @@
 
 /**
- * Connect a guest to the shared clipboard.
- * @note  on the host, we assume that some other application already owns
+ * @note  On the host, we assume that some other application already owns
  *        the clipboard and leave ownership to X11.
  */
@@ -139 +130 @@
 }
 
-/**
- * Synchronise the contents of the host clipboard with the guest, called
- * after a save and restore of the guest.
- * @note  Host glue code
- */
 int ShClSvcImplSync(PSHCLCLIENT pClient)
 {
@@ -191 +177 @@
 }
 
-/**
- * VBox is taking possession of the shared clipboard.
- *
- * @param pClient               Context data for the guest system.
- * @param pCmdCtx               Command context to use.
- * @param pFormats              Clipboard formats the guest is offering.
- */
 int ShClSvcImplFormatAnnounce(PSHCLCLIENT pClient, PSHCLCLIENTCMDCTX pCmdCtx,
                               PSHCLFORMATDATA pFormats)
@@ -227 +206 @@
 
 /**
- * Called when the host service wants to read the X11 clipboard.
- *
- * @returns VINF_SUCCESS on successful completion.
- * @returns VINF_HGCM_ASYNC_EXECUTE if the operation will complete asynchronously.
- * @returns IPRT status code on failure.
- *
- * @param pClient               Context information about the guest VM.
- * @param pCmdCtx               Command context to use.
- * @param pData                 Data block to put read data into.
- * @param pcbActual             Where to write the actual size of the written data.
- *
  * @note   We always fail or complete asynchronously.
  * @note   On success allocates a CLIPREADCBREQ structure which must be
  *         freed in ClipCompleteDataRequestFromX11 when it is called back from
  *         the backend code.
- *
  */
 int ShClSvcImplReadData(PSHCLCLIENT pClient,
@@ -291 +258 @@
 }
 
-/**
- * Called when writing guest clipboard data to the host service.
- *
- * @param  pClient              Context information about the guest VM.
- * @param  pCmdCtx              Pointer to the clipboard command context.
- * @param  pData                Data block to write to clipboard.
- */
 int ShClSvcImplWriteData(PSHCLCLIENT pClient,
                          PSHCLCLIENTCMDCTX pCmdCtx, PSHCLDATABLOCK pData)