Changeset 33453 in vbox for trunk/src

Timestamp:

Oct 26, 2010 9:48:58 AM (14 years ago)

Author:

vboxsync

Message:

IPRT/isofs.cpp: Documentation, cleaning up a bit.

File:

• trunk/src/VBox/Runtime/r3/isofs.cpp (modified) (15 diffs)

trunk/src/VBox/Runtime/r3/isofs.cpp

@@ -36 +36 @@
  * Destroys the patch cache.
  *
- * @param   pFile
+ * @param   pFile           ISO handle.
  */
 RTR3DECL(void) rtIsoFsDestroyPathCache(PRTISOFSFILE pFile)
@@ -62 +62 @@
 
 /**
- *
- *
- * @return  int
- *
- * @param   pList
- * @param   pszPath
- * @param   pHeader
+ * Adds a path entry to the path table list.
+ *
+ * @return  IPRT status code.
+ * @param   pList       Path table list to add the path entry to.
+ * @param   pszPath     Path to add.
+ * @param   pHeader     Path header information to add.
  */
 RTR3DECL(int) rtIsoFsAddToPathCache(PRTLISTNODE pList, const char *pszPath,
@@ -98 +97 @@
 
 /**
- *
- *
- * @return  int
- *
- * @param   pList
- * @param   pNode
- * @param   pszPathNode
- * @param   ppszPath
+ * Retrieves the parent path of a given node, assuming that the path table
+ * (still) is in sync with the node's index.
+ *
+ * @return  IPRT status code.
+ * @param   pList           Path table list to use.
+ * @param   pNode           Node of path table entry to lookup the full path for.
+ * @param   pszPathNode     Current (partial) parent path; needed for recursion.
+ * @param   ppszPath        Pointer to a pointer to store the retrieved full path to.
  */
 RTR3DECL(int) rtIsoFsGetParentPathSub(PRTLISTNODE pList, PRTISOFSPATHTABLEENTRY pNode,
@@ -111 +110 @@
 {
     int rc = VINF_SUCCESS;
+    /* Do we have a parent? */
     if (pNode->header.parent_index > 1)
     {
         uint16_t idx = 1;
+        /* Get the parent of our current node (pNode) */
         PRTISOFSPATHTABLEENTRY pNodeParent = RTListNodeGetFirst(pList, RTISOFSPATHTABLEENTRY, Node);
         while (idx++ < pNode->header.parent_index)
             pNodeParent =  RTListNodeGetNext(&pNodeParent->Node, RTISOFSPATHTABLEENTRY, Node);
+        /* Construct intermediate path (parent + current path). */
         char *pszPath;
         if (RTStrAPrintf(&pszPath, "%s/%s", pNodeParent->path, pszPathNode))
         {
+            /* ... and do the same with the parent's parent until we reached the root. */
             rc = rtIsoFsGetParentPathSub(pList, pNodeParent, pszPath, ppszPath);
             RTStrFree(pszPath);
@@ -126 +129 @@
             rc = VERR_NO_MEMORY;
     }
-    else
+    else /* No parent (left), this must be the root path then. */
     {
         char *pszPath = RTStrDup(pszPathNode);
@@ -136 +139 @@
 
 /**
- *
- *
- * @return  int
- *
- * @param   pFile
+ * Updates the path table cache of an ISO file.
+ *
+ * @return  IPRT status code.
+ * @param   pFile                   ISO handle.
  */
 RTR3DECL(int) rtIsoFsUpdatePathCache(PRTISOFSFILE pFile)
@@ -204 +206 @@
     {
         rc = rtIsoFsGetParentPathSub(&pFile->listPaths, pNode,
-                                       pNode->path, &pNode->path_full);
+                                     pNode->path, &pNode->path_full);
         if (RT_SUCCESS(rc))
             pNode = RTListNodeGetPrev(&pNode->Node, RTISOFSPATHTABLEENTRY, Node);
@@ -213 +215 @@
 
 
-/**
- *
- *
- * @return  int
- *
- * @param   pszFileName
- * @param   pFile
- */
 RTR3DECL(int) RTIsoFsOpen(PRTISOFSFILE pFile, const char *pszFileName)
 {
@@ -285 +279 @@
 
 
-/**
- *
- *
- *
- * @param   pFile
- */
 RTR3DECL(void) RTIsoFsClose(PRTISOFSFILE pFile)
 {
@@ -303 +291 @@
 /**
  * Parses an extent given at the specified sector + size and
- * returns a directory record.
- *
- * @return  int
- *
- * @param   pFile
- * @param   pszFileName
- * @param   uExtentSector
- * @param   cbExtent
- * @param   ppRec
+ * searches for a file name to return an allocated directory record.
+ *
+ * @return  IPRT status code.
+ * @param   pFile                   ISO handle.
+ * @param   pszFileName             Absolute file name to search for.
+ * @param   uExtentSector           Sector of extent.
+ * @param   cbExtent                Size (in bytes) of extent.
+ * @param   ppRec                   Pointer to a pointer to return the
+ *                                  directory record. Must be free'd with
+ *                                  rtIsoFsFreeDirectoryRecord().
  */
 RTR3DECL(int) rtIsoFsFindEntry(PRTISOFSFILE pFile, const char *pszFileName,
@@ -401 +390 @@
 
 /**
- *
- *
- * @return  int
- *
- * @param   pFile
- * @param   pszPath
- * @param   puSector
+ * Retrieves the sector of a file extent given by the
+ * full file path within the ISO.
+ *
+ * @return  IPRT status code.
+ * @param   pFile               ISO handle.
+ * @param   pszPath             File path to resolve.
+ * @param   puSector            Pointer where to store the found sector to.
  */
 RTR3DECL(int) rtIsoFsResolvePath(PRTISOFSFILE pFile, const char *pszPath, uint32_t *puSector)
@@ -454 +443 @@
 
 /**
- *
- *
- * @return  int
- *
- * @param   pFile
- * @param   pszPath
- * @param   ppRecord
+ * Allocates a new directory record.
+ *
+ * @return  Pointer to the newly allocated directory record.
+ */
+RTR3DECL(PRTISOFSDIRRECORD) rtIsoFsCreateDirectoryRecord(void)
+{
+    PRTISOFSDIRRECORD pRecord = (PRTISOFSDIRRECORD)RTMemAlloc(sizeof(RTISOFSDIRRECORD));
+    return pRecord;
+}
+
+
+/**
+ * Frees a previously allocated directory record.
+ *
+ * @return  IPRT status code.
+ */
+RTR3DECL(void) rtIsoFsFreeDirectoryRecord(PRTISOFSDIRRECORD pRecord)
+{
+    RTMemFree(pRecord);
+}
+
+
+/**
+ * Returns an allocated directory record for a given file.
+ *
+ * @return  IPRT status code.
+ * @param   pFile                   ISO handle.
+ * @param   pszPath                 File path to resolve.
+ * @param   ppRecord                Pointer to a pointer to return the
+ *                                  directory record. Must be free'd with
+ *                                  rtIsoFsFreeDirectoryRecord().
  */
 RTR3DECL(int) rtIsoFsGetDirectoryRecord(PRTISOFSFILE pFile, const char *pszPath,
@@ -479 +492 @@
         {
             size_t cbRead;
-            PRTISOFSDIRRECORD pRecord = (PRTISOFSDIRRECORD)RTMemAlloc(sizeof(RTISOFSDIRRECORD));
+            PRTISOFSDIRRECORD pRecord = rtIsoFsCreateDirectoryRecord();
             if (pRecord)
             {
@@ -489 +502 @@
                 }
                 if (RT_FAILURE(rc))
-                    RTMemFree(pRecord);
+                    rtIsoFsFreeDirectoryRecord(pRecord);
             }
             else
@@ -521 +534 @@
             *pcbOffset = pFileRecord->extent_location * RTISOFS_SECTOR_SIZE;
             *pcbLength = pFileRecord->extent_data_length;
-            RTMemFree(pFileRecord);
-        }
-        RTMemFree(pDirRecord);
+            rtIsoFsFreeDirectoryRecord(pFileRecord);
+        }
+        rtIsoFsFreeDirectoryRecord(pDirRecord);
     }
     return rc;