Changeset 85681 in vbox for trunk/src/VBox/GuestHost/DragAndDrop

Timestamp:

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

Author:

vboxsync

Message:

DnD: Lots of documentation.

Location:

trunk/src/VBox/GuestHost/DragAndDrop

Files:

• DnDDroppedFiles.cpp (modified) (17 diffs)
• DnDMIME.cpp (modified) (2 diffs)

trunk/src/VBox/GuestHost/DragAndDrop/DnDDroppedFiles.cpp

@@ -40 +40 @@
 
 
+/**
+ * Initializes a DnD Dropped Files struct, internal version.
+ *
+ * @returns VBox status code.
+ * @param   pDF                 DnD Dropped Files to initialize.
+ */
 static int dndDroppedFilesInitInternal(PDNDDROPPEDFILES pDF)
 {
@@ -52 +58 @@
 }
 
+/**
+ * Initializes a DnD Dropped Files struct, extended version.
+ *
+ * @returns VBox status code.
+ * @param   pDF                 DnD Dropped Files to initialize.
+ * @param   fFlags              Dropped Files flags to use for initialization.
+ */
 int DnDDroppedFilesInitEx(PDNDDROPPEDFILES pDF,
                           const char *pszPath, DNDURIDROPPEDFILEFLAGS fFlags /* = DNDURIDROPPEDFILE_FLAGS_NONE */)
@@ -62 +75 @@
 }
 
+/**
+ * Initializes a DnD Dropped Files struct.
+ *
+ * @returns VBox status code.
+ * @param   pDF                 DnD Dropped Files to initialize.
+ */
 int DnDDroppedFilesInit(PDNDDROPPEDFILES pDF)
 {
@@ -67 +86 @@
 }
 
+/**
+ * Destroys a DnD Dropped Files struct.
+ *
+ * Note: This does *not* (physically) delete any added content.
+ *       Make sure to call DnDDroppedFilesReset() then.
+ *
+ * @param   pDF                 DnD Dropped Files to destroy.
+ */
 void DnDDroppedFilesDestroy(PDNDDROPPEDFILES pDF)
 {
@@ -78 +105 @@
 
 /**
- * Adds a file reference to a dropped files directory.
- *
- * @returns VBox status code.
+ * Adds a file reference to a Dropped Files directory.
+ *
+ * @returns VBox status code.
+ * @param   pDF                 DnD Dropped Files to add file to.
  * @param   pszFile             Path of file entry to add.
  */
@@ -103 +131 @@
 
 /**
- * Adds a directory reference to a dropped files directory.
+ * Adds a directory reference to a Dropped Files directory.
+ *
  * Note: This does *not* (recursively) add sub entries.
  *
  * @returns VBox status code.
+ * @param   pDF                 DnD Dropped Files to add directory to.
  * @param   pszDir              Path of directory entry to add.
  */
@@ -132 +162 @@
  *
  * @returns VBox status code.
+ * @param   pDF                 DnD Dropped Files to close.
  */
 static int dndDroppedFilesCloseInternal(PDNDDROPPEDFILES pDF)
@@ -153 +184 @@
  *
  * @returns VBox status code.
+ * @param   pDF                 DnD Dropped Files to close.
  */
 int DnDDroppedFilesClose(PDNDDROPPEDFILES pDF)
@@ -163 +195 @@
  *
  * @returns Pointer to absolute path of the dropped files directory.
+ * @param   pDF                 DnD Dropped Files return absolute path of the dropped files directory for.
  */
 const char *DnDDroppedFilesGetDirAbs(PDNDDROPPEDFILES pDF)
@@ -173 +206 @@
  *
  * @returns \c true if open, \c false if not.
+ * @param   pDF                 DnD Dropped Files to return open status for.
  */
 bool DnDDroppedFilesIsOpen(PDNDDROPPEDFILES pDF)
@@ -183 +217 @@
  *
  * @returns VBox status code.
+ * @param   pDF                 DnD Dropped Files to open.
  * @param   pszPath             Absolute path where to create the dropped files directory.
  * @param   fFlags              Dropped files flags to use for this directory.
@@ -259 +294 @@
  *
  * @returns VBox status code.
+ * @param   pDF                 DnD Dropped Files to open.
  * @param   fFlags              Dropped files flags to use for this directory.
  */
@@ -278 +314 @@
 }
 
+/**
+ * Free's an internal DnD Dropped Files entry.
+ *
+ * @param   pEntry              Pointer to entry to free. The pointer will be invalid after calling.
+ */
 static void dndDroppedFilesEntryFree(PDNDDROPPEDFILESENTRY pEntry)
 {
@@ -287 +328 @@
 }
 
+/**
+ * Resets an internal DnD Dropped Files list.
+ *
+ * @param   pListAnchor         Pointer to list (anchor) to reset.
+ */
 static void dndDroppedFilesResetList(PRTLISTANCHOR pListAnchor)
 {
@@ -299 +345 @@
  *
  * @returns VBox status code.
+ * @param   pDF                 DnD Dropped Files to reset.
  * @param   fDelete             Whether to physically delete the directory and its content
  *                              or just clear the internal references.
@@ -326 +373 @@
  *
  * @returns VBox status code, or VERR_NOT_FOUND if the dropped files directory has not been opened before.
+ * @param   pDF                 DnD Dropped Files to re-open.
  */
 int DnDDroppedFilesReopen(PDNDDROPPEDFILES pDF)
@@ -340 +388 @@
  *
  * @returns VBox status code.
+ * @param   pDF                 DnD Dropped Files to roll back.
  */
 int DnDDroppedFilesRollback(PDNDDROPPEDFILES pDF)

trunk/src/VBox/GuestHost/DragAndDrop/DnDMIME.cpp

@@ -26 +26 @@
 
 
+/**
+ * Returns whether a given MIME format contains file URLs we can work with or not.
+ *
+ * @returns \c true if the format contains file URLs, \c false if not.
+ * @param   pcszFormat          MIME format to check.
+ * @param   cchFormatMax        Maximum characters of MIME format to check.
+ */
 bool DnDMIMEHasFileURLs(const char *pcszFormat, size_t cchFormatMax)
 {
@@ -33 +40 @@
 }
 
+/**
+ * Returns whether a given MIME format needs an own "Dropped Files" directory or not.
+ *
+ * @returns \c true if the format needs an own "Dropped Files" directory, \c false if not.
+ * @param   pcszFormat          MIME format to check.
+ * @param   cchFormatMax        Maximum characters of MIME format to check.
+ */
 bool DnDMIMENeedsDropDir(const char *pcszFormat, size_t cchFormatMax)
 {