Changeset 85681 in vbox for trunk/src/VBox/Main/src-client/GuestDnDTargetImpl.cpp

Timestamp:

Aug 11, 2020 9:36:37 AM (4 years ago)

Author:

vboxsync

Message:

DnD: Lots of documentation.

File:

• trunk/src/VBox/Main/src-client/GuestDnDTargetImpl.cpp (modified) (8 diffs)

trunk/src/VBox/Main/src-client/GuestDnDTargetImpl.cpp

@@ -60 +60 @@
     virtual ~GuestDnDTargetTask(void) { }
 
+    /** Returns the overall result of the task. */
     int getRC(void) const { return mRC; }
+    /** Returns if the overall result of the task is ok (succeeded) or not. */
     bool isOk(void) const { return RT_SUCCESS(mRC); }
 
 protected:
 
+    /** COM object pointer to the parent (source). */
     const ComObjPtr<GuestDnDTarget>     mTarget;
+    /** Overall result of the task. */
     int                                 mRC;
 };
@@ -670 +674 @@
 }
 
+/**
+ * Returns an error string from a guest DnD error.
+ *
+ * @returns Error string.
+ * @param   guestRc             Guest error to return error string for.
+ */
 /* static */
 Utf8Str GuestDnDTarget::i_guestErrorToString(int guestRc)
@@ -708 +718 @@
 }
 
+/**
+ * Returns an error string from a host DnD error.
+ *
+ * @returns Error string.
+ * @param   hostRc              Host error to return error string for.
+ */
 /* static */
 Utf8Str GuestDnDTarget::i_hostErrorToString(int hostRc)
@@ -742 +758 @@
 }
 
+/**
+ * Resets all internal data and state.
+ */
 void GuestDnDTarget::i_reset(void)
 {
@@ -919 +938 @@
 }
 
+/**
+ * Sends a directory entry to the guest.
+ *
+ * @returns VBox status code.
+ * @param   pCtx                Send context to use.
+ * @param   pObj                Transfer object to send. Must be a directory.
+ * @param   pMsg                Where to store the message to send.
+ */
 int GuestDnDTarget::i_sendDirectory(GuestDnDSendCtx *pCtx, PDNDTRANSFEROBJECT pObj, GuestDnDMsg *pMsg)
 {
@@ -942 +969 @@
 
 /**
- * Sends a transfer file to the guest.
+ * Sends a file to the guest.
  *
  * @returns VBox status code.
- * @param   pCtx
- * @param   pObj
- * @param   pMsg
+ * @param   pCtx                Send context to use.
+ * @param   pObj                Transfer object to send. Must be a file.
+ * @param   pMsg                Where to store the message to send.
  */
 int GuestDnDTarget::i_sendFile(GuestDnDSendCtx *pCtx,
@@ -1034 +1061 @@
 }
 
+/**
+ * Helper function to send actual file data to the guest.
+ *
+ * @returns VBox status code.
+ * @param   pCtx                Send context to use.
+ * @param   pObj                Transfer object to send. Must be a file.
+ * @param   pMsg                Where to store the message to send.
+ */
 int GuestDnDTarget::i_sendFileData(GuestDnDSendCtx *pCtx,
                                    PDNDTRANSFEROBJECT pObj, GuestDnDMsg *pMsg)
@@ -1113 +1148 @@
 }
 
+/**
+ * Static HGCM service callback which handles sending transfer data to the guest.
+ *
+ * @returns VBox status code. Will get sent back to the host service.
+ * @param   uMsg                HGCM message ID (function number).
+ * @param   pvParms             Pointer to additional message data. Optional and can be NULL.
+ * @param   cbParms             Size (in bytes) additional message data. Optional and can be 0.
+ * @param   pvUser              User-supplied pointer on callback registration.
+ */
 /* static */
 DECLCALLBACK(int) GuestDnDTarget::i_sendTransferDataCallback(uint32_t uMsg, void *pvParms, size_t cbParms, void *pvUser)