Changeset 33822 in vbox

Timestamp:

Nov 7, 2010 8:25:30 PM (15 years ago)

Author:

vboxsync

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

67467

Message:

iprt/vfs: I/O stream code.

Location:

trunk

Files:

• include/iprt/vfs.h (modified) (3 diffs)
• include/iprt/vfslowlevel.h (modified) (1 diff)
• src/VBox/Runtime/common/vfs/vfsbase.cpp (modified) (1 diff)

trunk/include/iprt/vfs.h

@@ -40 +40 @@
 /** @defgroup grp_rt_fs    RTVfs - Virtual Filesystem
  * @ingroup grp_rt
+ *
+ * The virtual filesystem APIs are intended to make it possible to work on
+ * container files, file system sub-trees, file system overlays and other custom
+ * filesystem configurations.  It also makes it possible to create filters, like
+ * automatically gunzipping a tar.gz file before feeding it to the RTTar API for
+ * unpacking - or wise versa.
+ *
+ * The virtual filesystem APIs are intended to mirror the RTDir, RTFile, RTPath
+ * and RTFs APIs pretty closely so that rewriting a piece of code to work with
+ * it should be easy.  However there are some differences to the way the APIs
+ * works and the user should heed the documentation.  The differences are
+ * usually motivated by simplification and in some case to make the VFS more
+ * flexible.
+ *
  * @{
  */
@@ -115 +129 @@
  * @{
  */
+
+/**
+ * Retains a reference to the VFS I/O stream handle.
+ *
+ * @returns New reference count on success, UINT32_MAX on failure.
+ * @param   hVfsIos         The VFS I/O stream handle.
+ */
 RTDECL(uint32_t)    RTVfsIoStrmRetain(RTVFSIOSTREAM hVfsIos);
+
+/**
+ * Releases a reference to the VFS I/O stream handle.
+ *
+ * @returns New reference count on success (0 if closed), UINT32_MAX on failure.
+ * @param   hVfsIos         The VFS I/O stream handle.
+ */
 RTDECL(uint32_t)    RTVfsIoStrmRelease(RTVFSIOSTREAM hVfsIos);
+
+/**
+ * Convert the VFS I/O stream handle to a VFS file handle.
+ *
+ * @returns The VFS file handle on success, this must be released.
+ *          NIL_RTVFSFILE if the I/O stream handle is invalid.
+ * @param   hVfsIos         The VFS I/O stream handle.
+ * @sa      RTVfsFileToIoStream
+ */
 RTDECL(RTVFSFILE)   RTVfsIoStrmToFile(RTVFSIOSTREAM hVfsIos);
+
+/**
+ * Query information about the I/O stream.
+ *
+ * @returns IPRT status code.
+ * @param   hVfsIos         The VFS I/O stream handle.
+ * @param   pObjInfo        Where to return the info.
+ * @param   enmAddAttr      Which additional attributes should be retrieved.
+ * @sa      RTFileQueryInfo
+ */
 RTDECL(int)         RTVfsIoStrmQueryInfo(RTVFSIOSTREAM hVfsIos, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
+
+/**
+ * Read bytes from the I/O stream.
+ *
+ * @returns IPRT status code.
+ * @param   hVfsIos         The VFS I/O stream handle.
+ * @param   pvBuf           Where to store the read bytes.
+ * @param   cbToRead        The number of bytes to read.
+ * @param   pcbRead         Where to store the number of bytes actually read.
+ *                          If this is NULL, the call will block until @a
+ *                          cbToRead bytes are available.  If this is non-NULL,
+ *                          the call will not block and return what is currently
+ *                          avaiable.
+ * @sa      RTFileRead, RTPipeRead, RTPipeReadBlocking, RTSocketRead
+ */
 RTDECL(int)         RTVfsIoStrmRead(RTVFSIOSTREAM hVfsIos, void *pvBuf, size_t cbToRead, size_t *pcbRead);
+
+/**
+ * Write bytes to the I/O stream.
+ *
+ * @returns IPRT status code.
+ * @param   hVfsIos         The VFS I/O stream handle.
+ * @param   pvBuf           The bytes to write.
+ * @param   cbToWrite       The number of bytes to write.
+ * @param   pcbWritten      Where to store the number of bytes actually written.
+ *                          If this is NULL, the call will block until @a
+ *                          cbToWrite bytes are available.  If this is non-NULL,
+ *                          the call will not block and return after writing
+ *                          what is possible.
+ * @sa      RTFileWrite, RTPipeWrite, RTPipeWriteBlocking, RTSocketWrite
+ */
 RTDECL(int)         RTVfsIoStrmWrite(RTVFSIOSTREAM hVfsIos, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
-RTDECL(int)         RTVfsIoStrmSgRead(RTVFSIOSTREAM hVfsIos, PCRTSGBUF pSgBuf, size_t *pcbRead);
-RTDECL(int)         RTVfsIoStrmSgWrite(RTVFSIOSTREAM hVfsIos, PCRTSGBUF pSgBuf, size_t *pcbWritten);
+
+/**
+ * Reads bytes from the I/O stream into a scatter buffer.
+ *
+ * @returns IPRT status code.
+ * @param   hVfsIos         The VFS I/O stream handle.
+ * @param   pSgBuf          Pointer to a scatter buffer descriptor.  The number
+ *                          of bytes described by the segments is what will be
+ *                          attemted read.
+ * @param   fBlocking       Whether the call is blocking (@c true) or not.  If
+ *                          not, the @a pcbRead parameter must not be NULL.
+ * @param   pcbRead         Where to store the number of bytes actually read.
+ *                          This can be NULL if @a fBlocking is true.
+ * @sa      RTFileSgRead, RTSocketSgRead
+ */
+RTDECL(int)         RTVfsIoStrmSgRead(RTVFSIOSTREAM hVfsIos, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbRead);
+
+/**
+ * Write bytes to the I/O stream from a gather buffer.
+ *
+ * @returns IPRT status code.
+ * @param   hVfsIos         The VFS I/O stream handle.
+ * @param   pSgBuf          Pointer to a gather buffer descriptor.  The number
+ *                          of bytes described by the segments is what will be
+ *                          attemted written.
+ * @param   fBlocking       Whether the call is blocking (@c true) or not.  If
+ *                          not, the @a pcbWritten parameter must not be NULL.
+ * @param   pcbRead         Where to store the number of bytes actually written.
+ *                          This can be NULL if @a fBlocking is true.
+ * @sa      RTFileSgWrite, RTSocketSgWrite
+ */
+RTDECL(int)         RTVfsIoStrmSgWrite(RTVFSIOSTREAM hVfsIos, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbWritten);
+
+/**
+ * Flush any buffered data to the I/O stream.
+ *
+ * @returns IPRT status code.
+ * @param   hVfsIos         The VFS I/O stream handle.
+ * @sa      RTFileFlush, RTPipeFlush
+ */
 RTDECL(int)         RTVfsIoStrmFlush(RTVFSIOSTREAM hVfsIos);
+
+/**
+ * Poll for events.
+ *
+ * @returns IPRT status code.
+ * @param   hVfsIos         The VFS I/O stream handle.
+ * @param   fEvents         The events to poll for (RTPOLL_EVT_XXX).
+ * @param   cMillies        How long to wait for event to eventuate.
+ * @param   fIntr           Whether the wait is interruptible and can return
+ *                          VERR_INTERRUPTED (@c true) or if this condition
+ *                          should be hidden from the caller (@c false).
+ * @param   pfRetEvents     Where to return the event mask.
+ * @sa      RTPollSetAdd, RTPoll, RTPollNoResume.
+ */
 RTDECL(RTFOFF)      RTVfsIoStrmPoll(RTVFSIOSTREAM hVfsIos, uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr,
                                     uint32_t *pfRetEvents);
+/**
+ * Tells the current I/O stream position.
+ *
+ * @returns Zero or higher - where to return the I/O stream offset.  Values
+ *          below zero are IPRT status codes (VERR_XXX).
+ * @param   hVfsIos         The VFS I/O stream handle.
+ * @sa      RTFileTell
+ */
 RTDECL(RTFOFF)      RTVfsIoStrmTell(RTVFSIOSTREAM hVfsIos);
 /** @} */
@@ -155 +292 @@
  *          NIL_RTVFSIOSTREAM if the file handle is invalid.
  * @param   hVfsFile        The VFS file handle.
+ * @sa      RTVfsIoStrmToFile
  */
 RTDECL(RTVFSIOSTREAM) RTVfsFileToIoStream(RTVFSFILE hVfsFile);

trunk/include/iprt/vfslowlevel.h

@@ -428 +428 @@
      * @param   pvThis      The implementation specific file data.
      * @param   poffActual  Where to return the actual offset.
-     * @sa      RTFileSeek
+     * @sa      RTFileTell
      */
     DECLCALLBACKMEMBER(int, pfnTell)(void *pvThis, PRTFOFF poffActual);

trunk/src/VBox/Runtime/common/vfs/vfsbase.cpp

@@ -184 +184 @@
 
 
+RTDECL(uint32_t)    RTVfsIoStrmRetain(RTVFSIOSTREAM hVfsIos)
+{
+    RTVFSIOSTREAMINTERNAL *pThis = hVfsIos;
+    AssertPtrReturn(pThis, UINT32_MAX);
+    AssertReturn(pThis->uMagic == RTVFSIOSTREAM_MAGIC, UINT32_MAX);
+    return rtVfsRetain(&pThis->cRefs);
+}
+
+
+RTDECL(uint32_t)    RTVfsIoStrmRelease(RTVFSIOSTREAM hVfsIos)
+{
+    RTVFSIOSTREAMINTERNAL *pThis = hVfsIos;
+    AssertPtrReturn(pThis, UINT32_MAX);
+    AssertReturn(pThis->uMagic == RTVFSIOSTREAM_MAGIC, UINT32_MAX);
+
+    uint32_t cRefs = rtVfsRelease(&pThis->cRefs);
+    if (!cRefs)
+    {
+        /*
+         * That was the last reference, close the stream.
+         *
+         * This is a little bit more complicated than when releasing a file or
+         * directory handle because the I/O stream can be a sub-object and we
+         * need to get to the real one before handing it to RTMemFree.
+         */
+        ASMAtomicWriteU32(&pThis->uMagic, RTVFSIOSTREAM_MAGIC_DEAD);
+        pThis->pOps->Obj.pfnClose(pThis->pvThis);
+
+        switch (pThis->pOps->Obj.enmType)
+        {
+            case RTVFSOBJTYPE_IOSTREAM:
+                RTMemFree(pThis);
+                break;
+
+            case RTVFSOBJTYPE_FILE:
+            {
+                RTVFSFILEINTERNAL *pThisFile = RT_FROM_MEMBER(pThis, RTVFSFILEINTERNAL, Stream);
+                ASMAtomicWriteU32(&pThisFile->uMagic, RTVFSIOSTREAM_MAGIC_DEAD);
+                RTMemFree(pThisFile);
+                break;
+            }
+
+            /* Add new I/O stream compatible handle types here. */
+
+            default:
+                AssertMsgFailed(("%d\n", pThis->pOps->Obj.enmType));
+                break;
+        }
+    }
+
+    return cRefs;
+
+}
+
+
+RTDECL(RTVFSFILE)   RTVfsIoStrmToFile(RTVFSIOSTREAM hVfsIos)
+{
+    RTVFSIOSTREAMINTERNAL *pThis = hVfsIos;
+    AssertPtrReturn(pThis, NIL_RTVFSFILE);
+    AssertReturn(pThis->uMagic == RTVFSIOSTREAM_MAGIC, NIL_RTVFSFILE);
+
+    if (pThis->pOps->Obj.enmType == RTVFSOBJTYPE_FILE)
+    {
+        rtVfsRetainVoid(&pThis->cRefs);
+        return RT_FROM_MEMBER(pThis, RTVFSFILEINTERNAL, Stream);
+    }
+
+    /* this is no crime, so don't assert. */
+    return NIL_RTVFSFILE;
+}
+
+
+RTDECL(int)         RTVfsIoStrmQueryInfo(RTVFSIOSTREAM hVfsIos, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr)
+{
+    RTVFSIOSTREAMINTERNAL *pThis = hVfsIos;
+    AssertPtrReturn(pThis, VERR_INVALID_HANDLE);
+    AssertReturn(pThis->uMagic == RTVFSIOSTREAM_MAGIC, VERR_INVALID_HANDLE);
+
+    return pThis->pOps->Obj.pfnQueryInfo(pThis->pvThis, pObjInfo, enmAddAttr);
+}
+
+
+RTDECL(int)         RTVfsIoStrmRead(RTVFSIOSTREAM hVfsIos, void *pvBuf, size_t cbToRead, size_t *pcbRead)
+{
+    RTVFSIOSTREAMINTERNAL *pThis = hVfsIos;
+    AssertPtrReturn(pThis, VERR_INVALID_HANDLE);
+    AssertReturn(pThis->uMagic == RTVFSIOSTREAM_MAGIC, VERR_INVALID_HANDLE);
+
+    RTSGSEG Seg = { pvBuf, cbToRead };
+    RTSGBUF SgBuf;
+    RTSgBufInit(&SgBuf, &Seg, 1);
+    return pThis->pOps->pfnRead(pThis->pvThis, -1 /*off*/, &SgBuf, pcbRead == NULL /*fBlocking*/, pcbRead);
+}
+
+
+RTDECL(int)         RTVfsIoStrmWrite(RTVFSIOSTREAM hVfsIos, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten)
+{
+    RTVFSIOSTREAMINTERNAL *pThis = hVfsIos;
+    AssertPtrReturn(pThis, VERR_INVALID_HANDLE);
+    AssertReturn(pThis->uMagic == RTVFSIOSTREAM_MAGIC, VERR_INVALID_HANDLE);
+
+    RTSGSEG Seg = { (void *)pvBuf, cbToWrite };
+    RTSGBUF SgBuf;
+    RTSgBufInit(&SgBuf, &Seg, 1);
+    return pThis->pOps->pfnWrite(pThis->pvThis, -1 /*off*/, &SgBuf, pcbWritten == NULL /*fBlocking*/, pcbWritten);
+}
+
+
+RTDECL(int)         RTVfsIoStrmSgRead(RTVFSIOSTREAM hVfsIos, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbRead)
+{
+    RTVFSIOSTREAMINTERNAL *pThis = hVfsIos;
+    AssertPtrReturn(pThis, VERR_INVALID_HANDLE);
+    AssertReturn(pThis->uMagic == RTVFSIOSTREAM_MAGIC, VERR_INVALID_HANDLE);
+    AssertPtr(pSgBuf);
+    AssertReturn(fBlocking || VALID_PTR(pcbRead), VERR_INVALID_PARAMETER);
+
+    return pThis->pOps->pfnRead(pThis->pvThis, -1 /*off*/, pSgBuf, fBlocking, pcbRead);
+}
+
+
+RTDECL(int)         RTVfsIoStrmSgWrite(RTVFSIOSTREAM hVfsIos, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbWritten)
+{
+    RTVFSIOSTREAMINTERNAL *pThis = hVfsIos;
+    AssertPtrReturn(pThis, VERR_INVALID_HANDLE);
+    AssertReturn(pThis->uMagic == RTVFSIOSTREAM_MAGIC, VERR_INVALID_HANDLE);
+    AssertPtr(pSgBuf);
+    AssertReturn(fBlocking || VALID_PTR(pcbWritten), VERR_INVALID_PARAMETER);
+
+    return pThis->pOps->pfnWrite(pThis->pvThis, -1 /*off*/, pSgBuf, fBlocking, pcbWritten);
+}
+
+
+RTDECL(int)         RTVfsIoStrmFlush(RTVFSIOSTREAM hVfsIos)
+{
+    RTVFSIOSTREAMINTERNAL *pThis = hVfsIos;
+    AssertPtrReturn(pThis, VERR_INVALID_HANDLE);
+    AssertReturn(pThis->uMagic == RTVFSIOSTREAM_MAGIC, VERR_INVALID_HANDLE);
+
+    return pThis->pOps->pfnFlush(pThis->pvThis);
+}
+
+
+RTDECL(RTFOFF)      RTVfsIoStrmPoll(RTVFSIOSTREAM hVfsIos, uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr,
+                                    uint32_t *pfRetEvents)
+{
+    RTVFSIOSTREAMINTERNAL *pThis = hVfsIos;
+    AssertPtrReturn(pThis, VERR_INVALID_HANDLE);
+    AssertReturn(pThis->uMagic == RTVFSIOSTREAM_MAGIC, VERR_INVALID_HANDLE);
+
+    return pThis->pOps->pfnPollOne(pThis->pvThis, fEvents, cMillies, fIntr, pfRetEvents);
+}
+
+
+RTDECL(RTFOFF)      RTVfsIoStrmTell(RTVFSIOSTREAM hVfsIos)
+{
+    RTVFSIOSTREAMINTERNAL *pThis = hVfsIos;
+    AssertPtrReturn(pThis, -1);
+    AssertReturn(pThis->uMagic == RTVFSIOSTREAM_MAGIC, -1);
+
+    RTFOFF off;
+    int rc = pThis->pOps->pfnTell(pThis->pvThis, &off);
+    if (RT_FAILURE(rc))
+        off = rc;
+    return off;
+}
+
+
+
 RTDECL(int) RTVfsNewFile(PCRTVFSFILEOPS pFileOps, size_t cbInstance, uint32_t fOpen, RTVFS hVfs,
                          PRTVFSFILE phVfsFile, void **ppvInstance)