Changeset 74574 in vbox for trunk/src/VBox/GuestHost/DragAndDrop/DnDURIObject.cpp

Timestamp:

Oct 2, 2018 9:38:42 AM (6 years ago)

Author:

vboxsync

Message:

DnD/DnDObject: Documentation, a bit of cleaning / re-structuring. No functional changes.

File:

• trunk/src/VBox/GuestHost/DragAndDrop/DnDURIObject.cpp (modified) (23 diffs)

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

@@ -38 +38 @@
 DnDURIObject::DnDURIObject(void)
     : m_Type(Type_Unknown)
-    , m_fOpen(false)
-    , m_fMode(0)
-    , m_cbSize(0)
-    , m_cbProcessed(0)
+    , m_fIsOpen(false)
 {
     RT_ZERO(u);
@@ -47 +44 @@
 
 DnDURIObject::DnDURIObject(Type enmType,
-                           const RTCString &strSrcPath /* = 0 */,
-                           const RTCString &strDstPath /* = 0 */,
+                           const RTCString &strSrcPathAbs /* = 0 */,
+                           const RTCString &strDstPathAbs /* = 0 */,
                            uint32_t fMode  /* = 0 */, uint64_t cbSize  /* = 0 */)
     : m_Type(enmType)
-    , m_strSrcPath(strSrcPath)
-    , m_strTgtPath(strDstPath)
-    , m_fOpen(false)
-    , m_fMode(fMode)
-    , m_cbSize(cbSize)
-    , m_cbProcessed(0)
-{
+    , m_strSrcPathAbs(strSrcPathAbs)
+    , m_strTgtPathAbs(strDstPathAbs)
+    , m_fIsOpen(false)
+{
+    RT_ZERO(u);
+
+    switch (m_Type)
+    {
+        case Type_File:
+            u.File.fMode = fMode;
+            u.File.cbSize = cbSize;
+            break;
+
+        default:
+            break;
+    }
 }
 
@@ -65 +71 @@
 }
 
+/**
+ * Closes the object's internal handles (to files / ...).
+ *
+ */
 void DnDURIObject::closeInternal(void)
 {
     LogFlowThisFuncEnter();
 
-    if (!m_fOpen)
+    if (!m_fIsOpen)
         return;
 
@@ -76 +86 @@
         case Type_File:
         {
-            RTFileClose(u.m_hFile);
-            u.m_hFile = NIL_RTFILE;
+            RTFileClose(u.File.hFile);
+            u.File.hFile = NIL_RTFILE;
+            u.File.fMode = 0;
             break;
         }
@@ -88 +99 @@
     }
 
-    m_fOpen = false;
-}
-
+    m_fIsOpen = false;
+}
+
+/**
+ * Closes the object.
+ * This also closes the internal handles associated with the object (to files / ...).
+ */
 void DnDURIObject::Close(void)
 {
@@ -96 +111 @@
 }
 
+/**
+ * Returns whether the processing of the object is complete or not.
+ * For file objects this means that all bytes have been processed.
+ *
+ * @return  True if complete, False if not.
+ */
 bool DnDURIObject::IsComplete(void) const
 {
@@ -103 +124 @@
     {
         case Type_File:
-            Assert(m_cbProcessed <= m_cbSize);
-            fComplete = m_cbProcessed == m_cbSize;
+            Assert(u.File.cbProcessed <= u.File.cbSize);
+            fComplete = u.File.cbProcessed == u.File.cbSize;
             break;
 
@@ -119 +140 @@
 }
 
+/**
+ * Returns whether the object is in an open state or not.
+ */
 bool DnDURIObject::IsOpen(void) const
 {
-    return m_fOpen;
-}
-
+    return m_fIsOpen;
+}
+
+/**
+ * (Re-)Opens the object with a specific view, open and file mode.
+ *
+ * @return  IPRT status code.
+ * @param   enmView             View to use for opening the object.
+ * @param   fOpen               File open flags to use.
+ * @param   fMode
+ *
+ * @remark
+ */
 int DnDURIObject::Open(View enmView, uint64_t fOpen /* = 0 */, uint32_t fMode /* = 0 */)
 {
     return OpenEx(  enmView == View_Source
-                  ? m_strSrcPath : m_strTgtPath
+                  ? m_strSrcPathAbs : m_strTgtPathAbs
                   , m_Type, enmView, fOpen, fMode, 0 /* fFlags */);
 }
 
-int DnDURIObject::OpenEx(const RTCString &strPath, Type enmType, View enmView,
+/**
+ * Open the object with a specific file type, and, depending on the type, specifying additional parameters.
+ *
+ * @return  IPRT status code.
+ * @param   strPathAbs          Absolute path of the object (file / directory / ...).
+ * @param   enmType             Type of the object.
+ * @param   enmView             View of the object.
+ * @param   fOpen               Open mode to use; only valid for file objects.
+ * @param   fMode               File mode to use; only valid for file objects.
+ * @param   fFlags              Additional DnD URI object flags.
+ */
+int DnDURIObject::OpenEx(const RTCString &strPathAbs, Type enmType, View enmView,
                          uint64_t fOpen /* = 0 */, uint32_t fMode /* = 0 */, DNDURIOBJECTFLAGS fFlags /* = DNDURIOBJECT_FLAGS_NONE */)
 {
-    Assert(fFlags == 0); RT_NOREF1(fFlags);
+    AssertReturn(fFlags & DNDURIOBJECT_FLAGS_VALID_MASK, VERR_INVALID_PARAMETER);
+    RT_NOREF1(fFlags);
+
     int rc = VINF_SUCCESS;
 
@@ -140 +187 @@
     {
         case View_Source:
-            m_strSrcPath = strPath;
+            m_strSrcPathAbs = strPathAbs;
             break;
 
         case View_Target:
-            m_strTgtPath = strPath;
+            m_strTgtPathAbs = strPathAbs;
             break;
 
@@ -156 +203 @@
     {
         LogFlowThisFunc(("strPath=%s, enmType=%RU32, enmView=%RU32, fOpen=0x%x, fMode=0x%x, fFlags=0x%x\n",
-                         strPath.c_str(), enmType, enmView, fOpen, fMode, fFlags));
+                         strPathAbs.c_str(), enmType, enmView, fOpen, fMode, fFlags));
         switch (enmType)
         {
             case Type_File:
             {
-                if (!m_fOpen)
+                if (!m_fIsOpen)
                 {
                     /*
@@ -169 +216 @@
                      */
                     LogFlowThisFunc(("Opening ...\n"));
-                    rc = RTFileOpen(&u.m_hFile, strPath.c_str(), fOpen);
+                    rc = RTFileOpen(&u.File.hFile, strPathAbs.c_str(), fOpen);
                     if (RT_SUCCESS(rc))
-                        rc = RTFileGetSize(u.m_hFile, &m_cbSize);
+                        rc = RTFileGetSize(u.File.hFile, &u.File.cbSize);
 
                     if (RT_SUCCESS(rc))
@@ -178 +225 @@
                             &&  fMode                   /* Some file mode to set specified? */)
                         {
-                            rc = RTFileSetMode(u.m_hFile, fMode);
+                            rc = RTFileSetMode(u.File.hFile, fMode);
                             if (RT_SUCCESS(rc))
-                                m_fMode = fMode;
+                                u.File.fMode = fMode;
                         }
                         else if (fOpen & RTFILE_O_READ)
@@ -188 +235 @@
 #else
                             RTFSOBJINFO ObjInfo;
-                            rc = RTFileQueryInfo(u.m_hFile, &ObjInfo, RTFSOBJATTRADD_NOTHING);
+                            rc = RTFileQueryInfo(u.File.hFile, &ObjInfo, RTFSOBJATTRADD_NOTHING);
                             if (RT_SUCCESS(rc))
-                                m_fMode = ObjInfo.Attr.fMode;
+                                u.File.fMode = ObjInfo.Attr.fMode;
 #endif
                         }
@@ -197 +244 @@
                     if (RT_SUCCESS(rc))
                     {
-                        LogFlowThisFunc(("cbSize=%RU64, fMode=0x%x\n", m_cbSize, m_fMode));
-                        m_cbProcessed = 0;
+                        LogFlowThisFunc(("cbSize=%RU64, fMode=0x%x\n", u.File.cbSize, u.File.fMode));
+                        u.File.cbProcessed = 0;
                     }
                 }
@@ -220 +267 @@
     {
         m_Type  = enmType;
-        m_fOpen = true;
+        m_fIsOpen = true;
     }
 
@@ -227 +274 @@
 }
 
+/**
+ * Rebases an absolute URI path from an old path base to a new path base.
+ * This function is needed in order to transform path from the source side to the target side.
+ *
+ * @return  IPRT status code.
+ * @param   strPathAbs          Absolute URI path to rebase.
+ * @param   strBaseOld          Old base path to rebase from.
+ * @param   strBaseNew          New base path to rebase to.
+ *
+ ** @todo Put this into an own class like DnDURIPath : public RTCString?
+ */
 /* static */
-/** @todo Put this into an own class like DnDURIPath : public RTCString? */
-int DnDURIObject::RebaseURIPath(RTCString &strPath,
+int DnDURIObject::RebaseURIPath(RTCString &strPathAbs,
                                 const RTCString &strBaseOld /* = "" */,
                                 const RTCString &strBaseNew /* = "" */)
 {
-    char *pszPath = RTUriFilePath(strPath.c_str());
+    char *pszPath = RTUriFilePath(strPathAbs.c_str());
     if (!pszPath) /* No URI? */
-         pszPath = RTStrDup(strPath.c_str());
+         pszPath = RTStrDup(strPathAbs.c_str());
 
     int rc;
@@ -261 +318 @@
                 if (pszPathURI)
                 {
-                    LogFlowFunc(("Rebasing \"%s\" to \"%s\"\n", strPath.c_str(), pszPathURI));
-
-                    strPath = RTCString(pszPathURI) + "\r\n";
+                    LogFlowFunc(("Rebasing \"%s\" to \"%s\"\n", strPathAbs.c_str(), pszPathURI));
+
+                    strPathAbs = RTCString(pszPathURI) + "\r\n";
                     RTStrFree(pszPathURI);
                 }
@@ -283 +340 @@
 }
 
+/**
+ * Reads data from the object. Only applies to files objects.
+ *
+ * @return  IPRT status code.
+ * @param   pvBuf               Buffer where to store the read data.
+ * @param   cbBuf               Size (in bytes) of the buffer.
+ * @param   pcbRead             Pointer where to store how many bytes were read. Optional.
+ */
 int DnDURIObject::Read(void *pvBuf, size_t cbBuf, uint32_t *pcbRead)
 {
@@ -296 +361 @@
         case Type_File:
         {
-            rc = OpenEx(m_strSrcPath, Type_File, View_Source,
+            rc = OpenEx(m_strSrcPathAbs, Type_File, View_Source,
                         /* Use some sensible defaults. */
                         RTFILE_O_OPEN | RTFILE_O_READ | RTFILE_O_DENY_WRITE, 0 /* fFlags */);
             if (RT_SUCCESS(rc))
             {
-                rc = RTFileRead(u.m_hFile, pvBuf, cbBuf, &cbRead);
+                rc = RTFileRead(u.File.hFile, pvBuf, cbBuf, &cbRead);
                 if (RT_SUCCESS(rc))
                 {
-                    m_cbProcessed += cbRead;
-                    Assert(m_cbProcessed <= m_cbSize);
+                    u.File.cbProcessed += cbRead;
+                    Assert(u.File.cbProcessed <= u.File.cbSize);
 
                     /* End of file reached or error occurred? */
-                    if (   m_cbSize
-                        && m_cbProcessed == m_cbSize)
+                    if (   u.File.cbSize
+                        && u.File.cbProcessed == u.File.cbSize)
                     {
                         rc = VINF_EOF;
@@ -336 +401 @@
     }
 
-    LogFlowFunc(("Returning strSourcePath=%s, cbRead=%zu, rc=%Rrc\n", m_strSrcPath.c_str(), cbRead, rc));
+    LogFlowFunc(("Returning strSourcePath=%s, cbRead=%zu, rc=%Rrc\n", m_strSrcPathAbs.c_str(), cbRead, rc));
     return rc;
 }
 
+/**
+ * Resets the object's state and closes all related handles.
+ */
 void DnDURIObject::Reset(void)
 {
@@ -346 +414 @@
     Close();
 
-    m_Type        = Type_Unknown;
-    m_strSrcPath  = "";
-    m_strTgtPath  = "";
-    m_fMode       = 0;
-    m_cbSize      = 0;
-    m_cbProcessed = 0;
-}
-
+    m_Type          = Type_Unknown;
+    m_strSrcPathAbs = "";
+    m_strTgtPathAbs = "";
+
+    RT_ZERO(u);
+}
+
+/**
+ * Writes data to an object. Only applies to file objects.
+ *
+ * @return  IPRT status code.
+ * @param   pvBuf               Buffer of data to write.
+ * @param   cbBuf               Size (in bytes) of data to write.
+ * @param   pcbWritten          Pointer where to store how many bytes were written. Optional.
+ */
 int DnDURIObject::Write(const void *pvBuf, size_t cbBuf, uint32_t *pcbWritten)
 {
@@ -367 +442 @@
         case Type_File:
         {
-            rc = OpenEx(m_strTgtPath, Type_File, View_Target,
+            rc = OpenEx(m_strTgtPathAbs, Type_File, View_Target,
                         /* Use some sensible defaults. */
                         RTFILE_O_OPEN_CREATE | RTFILE_O_DENY_WRITE | RTFILE_O_WRITE, 0 /* fFlags */);
             if (RT_SUCCESS(rc))
             {
-                rc = RTFileWrite(u.m_hFile, pvBuf, cbBuf, &cbWritten);
+                rc = RTFileWrite(u.File.hFile, pvBuf, cbBuf, &cbWritten);
                 if (RT_SUCCESS(rc))
-                    m_cbProcessed += cbWritten;
+                    u.File.cbProcessed += cbWritten;
             }
             break;
@@ -396 +471 @@
     }
 
-    LogFlowThisFunc(("Returning strSourcePath=%s, cbWritten=%zu, rc=%Rrc\n", m_strSrcPath.c_str(), cbWritten, rc));
+    LogFlowThisFunc(("Returning strSourcePathAbs=%s, cbWritten=%zu, rc=%Rrc\n", m_strSrcPathAbs.c_str(), cbWritten, rc));
     return rc;
 }