Changeset 33903 in vbox for trunk/include

Timestamp:

Nov 9, 2010 2:44:55 PM (14 years ago)

Author:

vboxsync

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

67559

Message:

iprt: More VFS and gunzip code.

Location:

trunk/include/iprt

Files:

• err.h (modified) (1 diff)
• vfs.h (modified) (5 diffs)
• vfslowlevel.h (modified) (3 diffs)

trunk/include/iprt/err.h

@@ -1294 +1294 @@
 /** The compression method is unsupported. */
 #define VERR_ZIP_UNSUPPORTED_METHOD             (-954)
+/** The compressed data started with a bad header. */
+#define VERR_ZIP_BAD_HEADER                     (-955)
 /** @} */
 

trunk/include/iprt/vfs.h

@@ -211 +211 @@
  * @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.
+ * @param   pcbRead         Where to always 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
  */
@@ -227 +227 @@
  * @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.
+ * @param   pcbWritten      Where to always 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
  */
@@ -240 +241 @@
  *
  * @returns IPRT status code.
+ * @retval  VINF_SUCCESS and the number of bytes read written to @a pcbRead.
+ * @retval  VINF_TRY_AGAIN if @a fBlocking is @c false, @a pcbRead is not NULL,
+ *          and no data was available. @a *pcbRead will be set to 0.
+ * @retval  VINF_EOF when trying to read __beyond__ the end of the stream and
+ *          @a pcbRead is not NULL (it will be set to the number of bytes read,
+ *          or 0 if the end of the stream was reached before this call).
+ *          When the last byte of the read request is the last byte in the
+ *          stream, this status code will not be used.  However, VINF_EOF is
+ *          returned when attempting to read 0 bytes while standing at the end
+ *          of the stream.
+ * @retval  VERR_EOF when trying to read __beyond__ the end of the stream and
+ *          @a pcbRead is NULL.
+ *
  * @param   hVfsIos         The VFS I/O stream handle.
  * @param   pSgBuf          Pointer to a scatter buffer descriptor.  The number
@@ -246 +260 @@
  * @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
+ * @param   pcbRead         Where to always store the number of bytes actually
+ *                          read.  This can be NULL if @a fBlocking is true.
+ * @sa      RTFileSgRead, RTSocketSgRead, RTPipeRead, RTPipeReadBlocking
  */
 RTDECL(int)         RTVfsIoStrmSgRead(RTVFSIOSTREAM hVfsIos, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbRead);
@@ -262 +276 @@
  * @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.
+ * @param   pcbRead         Where to always store the number of bytes actually
+ *                          written.  This can be NULL if @a fBlocking is true.
  * @sa      RTFileSgWrite, RTSocketSgWrite
  */

trunk/include/iprt/vfslowlevel.h

@@ -429 +429 @@
      * Reads from the file/stream.
      *
-     * @returns IPRT status code.
+     * @returns IPRT status code. See RTVfsIoStrmRead.
      * @param   pvThis      The implementation specific file data.
      * @param   off         Where to read at, -1 for the current position.
@@ -436 +436 @@
      * @param   fBlocking   If @c true, the call is blocking, if @c false it
      *                      should not block.
-     * @param   pcbRead     Where return the number of bytes actually read.  If
-     *                      NULL, try read all and fail if incomplete.
-     * @sa      RTFileRead, RTFileReadAt.
+     * @param   pcbRead     Where return the number of bytes actually read.
+     *                      This is set it 0 by the caller.  If NULL, try read
+     *                      all and fail if incomplete.
+     * @sa      RTVfsIoStrmRead, RTVfsIoStrmSgRead, RTVfsFileRead,
+     *          RTVfsFileReadAt, RTFileRead, RTFileReadAt.
      */
     DECLCALLBACKMEMBER(int, pfnRead)(void *pvThis, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbRead);
@@ -453 +455 @@
      * @param   fBlocking   If @c true, the call is blocking, if @c false it
      *                      should not block.
-     * @param   pcbWrite    Where to return the number of bytes actually
-     *                      written.  If  NULL, try write it all and fail if
-     *                      incomplete.
+     * @param   pcbWritten  Where to return the number of bytes actually
+     *                      written.  This is set it 0 by the caller.  If
+     *                      NULL, try write it all and fail if incomplete.
      * @sa      RTFileWrite, RTFileWriteAt.
      */