Changeset 33859 in vbox for trunk/include

Timestamp:

Nov 8, 2010 4:15:07 PM (15 years ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

67505

Message:

iprt/vfs: more code.

Location:

trunk/include/iprt

Files:

• vfs.h (modified) (2 diffs)
• vfslowlevel.h (modified) (9 diffs)

trunk/include/iprt/vfs.h

@@ -120 +120 @@
                                        char *pszMountPoint, size_t cbMountPoint);
 
+
 /** @defgroup grp_vfs_dir           VFS Directory API
  * @{
  */
+
+/**
+ * Retains a reference to the VFS directory handle.
+ *
+ * @returns New reference count on success, UINT32_MAX on failure.
+ * @param   hVfsDir         The VFS directory handle.
+ */
+RTDECL(uint32_t)    RTVfsDirRetain(RTVFSDIR hVfsDir);
+
+/**
+ * Releases a reference to the VFS directory handle.
+ *
+ * @returns New reference count on success (0 if closed), UINT32_MAX on failure.
+ * @param   hVfsIos         The VFS directory handle.
+ */
+RTDECL(uint32_t)    RTVfsDirRelease(RTVFSDIR hVfsDir);
+
 /** @}  */
 
 
-/** @defgroup grp_vfs_iostream      VFS I/O Stream
+/** @defgroup grp_vfs_iostream      VFS Symbolic Link API
+ * @{
+ */
+
+/**
+ * Read the symbolic link target.
+ *
+ * @returns IPRT status code.
+ * @param   hVfsSym         The VFS symbolic link handle.
+ * @param   pszTarget       The target buffer.
+ * @param   cbTarget        The size of the target buffer.
+ * @sa      RTSymlinkRead
+ */
+RTDECL(int)         RTVfsSymlinkRead(RTVFSSYMLINK hVfsSym, char *pszTarget, size_t cbTarget);
+
+/** @}  */
+
+
+
+/** @defgroup grp_vfs_iostream      VFS I/O Stream API
  * @{
  */
@@ -264 +301 @@
  */
 RTDECL(RTFOFF)      RTVfsIoStrmTell(RTVFSIOSTREAM hVfsIos);
+
+/**
+ * Skips @a cb ahead in the stream.
+ *
+ * @returns IPRT status code.
+ * @param   hVfsIos         The VFS I/O stream handle.
+ * @param   cb              The number bytes to skip.
+ */
+RTDECL(int)         RTVfsIoStrmSkip(RTVFSIOSTREAM hVfsIos, RTFOFF cb);
+
+/**
+ * Fills the stream with @a cb zeros.
+ *
+ * @returns IPRT status code.
+ * @param   hVfsIos         The VFS I/O stream handle.
+ * @param   cb              The number of zero bytes to insert.
+ */
+RTDECL(int)         RTVfsIoStrmZeroFill(RTVFSIOSTREAM hVfsIos, RTFOFF cb);
 /** @} */
 

trunk/include/iprt/vfslowlevel.h

@@ -28 +28 @@
 
 #include <iprt/vfs.h>
+#include <iprt/param.h>
 
 
@@ -87 +88 @@
 } RTVFSOPS;
 /** Pointer to constant VFS operations. */
-typedef RTVFSOPS const PCRTVFSOPS;
+typedef RTVFSOPS const *PCRTVFSOPS;
 
 /** The RTVFSOPS structure version. */
@@ -112 +113 @@
     /** File. */
     RTVFSOBJTYPE_FILE,
+    /** Symbolic link. */
+    RTVFSOBJTYPE_SYMLINK,
     /** End of valid object types. */
     RTVFSOBJTYPE_END,
@@ -242 +245 @@
 
     /**
+     * Opens a directory entry for traversal purposes.
+     *
+     * Method which sole purpose is helping the path traversal.  Only one of
+     * the three output variables will be set, the others will left untouched
+     * (caller sets them to NIL).
+     *
+     * @returns IPRT status code.
+     * @retval  VERR_PATH_NOT_FOUND if @a pszEntry was not found.
+     * @param   pvThis          The implementation specific directory data.
+     * @param   pszEntry        The name of the directory entry to remove.
+     * @param   phVfsDir        If not NULL and it is a directory, open it and
+     *                          return the handle here.
+     * @param   phVfsSymlink    If not NULL and it is a symbolic link, open it
+     *                          and return the handle here.
+     * @param   phVfsMounted    If not NULL and it is a mounted VFS directory,
+     *                          reference it and return the handle here.
+     * @todo    Should com dir, symlinks and mount points using some common
+     *          ancestor "class".
+     */
+    DECLCALLBACKMEMBER(int, pfnTraversalOpen)(void *pvThis, const char *pszEntry, PRTVFSDIR phVfsDir,
+                                              PRTVFSSYMLINK phVfsSymlink, PRTVFS phVfsMounted);
+
+    /**
      * Open or create a file.
      *
@@ -347 +373 @@
 /** The RTVFSDIROPS structure version. */
 #define RTVFSDIROPS_VERSION         RT_MAKE_U32_FROM_U8(0xff,0x3f,1,0)
+
+
+/**
+ * The symbolic link operations.
+ *
+ * @extends RTVFSOBJOPS
+ * @extends RTVFSOBJSETOPS
+ */
+typedef struct RTVFSSYMLINKOPS
+{
+    /** The basic object operation.  */
+    RTVFSOBJOPS             Obj;
+    /** The structure version (RTVFSSYMLINKOPS_VERSION). */
+    uint32_t                uVersion;
+    /** Reserved field, MBZ. */
+    uint32_t                fReserved;
+    /** The object setter operations. */
+    RTVFSOBJSETOPS          ObjSet;
+
+    /**
+     * Read the symbolic link target.
+     *
+     * @returns IPRT status code.
+     * @param   pvThis      The implementation specific symbolic link data.
+     * @param   pszTarget   The target buffer.
+     * @param   cbTarget    The size of the target buffer.
+     * @sa      RTSymlinkRead
+     */
+    DECLCALLBACKMEMBER(int, pfnRead)(void *pvThis, char *pszTarget, size_t cbTarget);
+
+    /** Marks the end of the structure (RTVFSSYMLINKOPS_VERSION). */
+    uintptr_t               uEndMarker;
+} RTVFSSYMLINKOPS;
+/** Pointer to const symbolic link operations. */
+typedef RTVFSSYMLINKOPS const *PCRTVFSSYMLINKOPS;
+/** The RTVFSSYMLINKOPS structure version. */
+#define RTVFSSYMLINKOPS_VERSION     RT_MAKE_U32_FROM_U8(0xff,0x4f,1,0)
 
 
@@ -432 +495 @@
     DECLCALLBACKMEMBER(int, pfnTell)(void *pvThis, PRTFOFF poffActual);
 
+    /**
+     * Skips @a cb ahead in the stream.
+     *
+     * @returns IPRT status code.
+     * @param   pvThis      The implementation specific file data.
+     * @param   cb          The number bytes to skip.
+     * @remarks This is optional and can be NULL.
+     */
+    DECLCALLBACKMEMBER(int, pfnSkip)(void *pvThis, RTFOFF cb);
+
+    /**
+     * Fills the stream with @a cb zeros.
+     *
+     * @returns IPRT status code.
+     * @param   pvThis      The implementation specific file data.
+     * @param   cb          The number of zero bytes to insert.
+     * @remarks This is optional and can be NULL.
+     */
+    DECLCALLBACKMEMBER(int, pfnZeroFill)(void *pvThis, RTFOFF cb);
+
     /** Marks the end of the structure (RTVFSIOSTREAMOPS_VERSION). */
     uintptr_t               uEndMarker;
@@ -439 +522 @@
 
 /** The RTVFSIOSTREAMOPS structure version. */
-#define RTVFSIOSTREAMOPS_VERSION    RT_MAKE_U32_FROM_U8(0xff,0x4f,1,0)
+#define RTVFSIOSTREAMOPS_VERSION    RT_MAKE_U32_FROM_U8(0xff,0x5f,1,0)
 
 
@@ -490 +573 @@
 
 /** The RTVFSFILEOPS structure version. */
-#define RTVFSFILEOPS_VERSION        RT_MAKE_U32_FROM_U8(0xff,0x5f,1,0)
+#define RTVFSFILEOPS_VERSION        RT_MAKE_U32_FROM_U8(0xff,0x6f,1,0)
 
 /**
@@ -509 +592 @@
 
 
+/** @defgroup grp_rt_vfs_ll_util        VFS Utility APIs
+ * @{ */
+
+/**
+ * Parsed path.
+ */
+typedef struct RTVFSPARSEDPATH
+{
+    /** The length of the path in szCopy. */
+    uint16_t        cch;
+    /** The number of path components. */
+    uint16_t        cComponents;
+    /** Set if the path ends with slash, indicating that it's a directory
+     * reference and not a file reference.  The slash has been removed from
+     * the copy. */
+    bool            fDirSlash;
+    /** The offset where each path component starts, i.e. the char after the
+     * slash.  The array has cComponents + 1 entries, where the final one is
+     * cch + 1 so that one can always terminate the current component by
+     * szPath[aoffComponent[i] - 1] = '\0'. */
+    uint16_t        aoffComponents[RTPATH_MAX / 2 + 1];
+    /** A normalized copy of the path.
+     * Reserve some extra space so we can be more relaxed about overflow
+     * checks and terminator paddings, especially when recursing. */
+    char            szPath[RTPATH_MAX];
+} RTVFSPARSEDPATH;
+/** Pointer to a parsed path. */
+typedef RTVFSPARSEDPATH *PRTVFSPARSEDPATH;
+
+/** The max accepted path length.
+ * This must be a few chars shorter than RTVFSPARSEDPATH::szPath because we
+ * use two terminators and wish be a little bit lazy with checking. */
+#define RTVFSPARSEDPATH_MAX     (RTPATH_MAX - 4U)
+
+/**
+ * Appends @a pszPath (relative) to the already parsed path @a pPath.
+ *
+ * @retval  VINF_SUCCESS
+ * @retval  VERR_FILENAME_TOO_LONG
+ * @retval  VERR_INTERNAL_ERROR_4
+ * @param   pPath               The parsed path to append @a pszPath onto.
+ *                              This is both input and output.
+ * @param   pszPath             The path to append.  This must be relative.
+ * @param   piRestartComp       The component to restart parsing at.  This is
+ *                              input/output.  The input does not have to be
+ *                              within the valid range.  Optional.
+ */
+RTDECL(int) RTVfsParsePathAppend(PRTVFSPARSEDPATH pPath, const char *pszPath, uint16_t *piRestartComp);
+
+/**
+ * Parses a path.
+ *
+ * @retval  VINF_SUCCESS
+ * @retval  VERR_FILENAME_TOO_LONG
+ * @param   pPath               Where to store the parsed path.
+ * @param   pszPath             The path to parse.  Absolute or relative to @a
+ *                              pszCwd.
+ * @param   pszCwd              The current working directory.  Must be
+ *                              absolute.
+ */
+RTDECL(int) RTVfsParsePath(PRTVFSPARSEDPATH pPath, const char *pszPath, const char *pszCwd);
+
+/**
+ * Same as RTVfsParsePath except that it allocates a temporary buffer.
+ *
+ * @retval  VINF_SUCCESS
+ * @retval  VERR_NO_TMP_MEMORY
+ * @retval  VERR_FILENAME_TOO_LONG
+ * @param   pszPath             The path to parse.  Absolute or relative to @a
+ *                              pszCwd.
+ * @param   pszCwd              The current working directory.  Must be
+ *                              absolute.
+ * @param   ppPath              Where to store the pointer to the allocated
+ *                              buffer containing the parsed path.  This must
+ *                              be freed by calling RTVfsParsePathFree.  NULL
+ *                              will be stored on failured.
+ */
+RTDECL(int) RTVfsParsePathA(const char *pszPath, const char *pszCwd, PRTVFSPARSEDPATH *ppPath);
+
+/**
+ * Frees a buffer returned by RTVfsParsePathA.
+ *
+ * @param   pPath               The parsed path buffer to free.  NULL is fine.
+ */
+RTDECL(void) RTVfsParsePathFree(PRTVFSPARSEDPATH pPath);
+
+/** @}  */
+
 /** @} */