[Gnash-commit] gnash ChangeLog server/stream.h

[Sandro Santilli]

CVSROOT:        /sources/gnash
Module name:    gnash
Changes by:     Sandro Santilli <strk>  07/12/05 11:31:52

Modified files:
        .              : ChangeLog 
        server         : stream.h 

Log message:
        document align reads and bitwise reads, add a couple of WARNING for 
possible bugs.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/gnash/ChangeLog?cvsroot=gnash&r1=1.5091&r2=1.5092
http://cvs.savannah.gnu.org/viewcvs/gnash/server/stream.h?cvsroot=gnash&r1=1.36&r2=1.37

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/gnash/gnash/ChangeLog,v
retrieving revision 1.5091
retrieving revision 1.5092
diff -u -b -r1.5091 -r1.5092
--- ChangeLog   5 Dec 2007 10:57:29 -0000       1.5091
+++ ChangeLog   5 Dec 2007 11:31:52 -0000       1.5092
@@ -1,5 +1,10 @@
 2007-12-05 Sandro Santilli <address@hidden>
 
+       * server/stream.h: document align reads and bitwise
+         reads, add a couple of WARNING for possible bugs.
+
+2007-12-05 Sandro Santilli <address@hidden>
+
        * server/stream.h: document align() and get_position().
        * testsuite/server/StreamTest.cpp: add tests for
          stream::get_position()

Index: server/stream.h
===================================================================
RCS file: /sources/gnash/gnash/server/stream.h,v
retrieving revision 1.36
retrieving revision 1.37
diff -u -b -r1.36 -r1.37
--- server/stream.h     5 Dec 2007 10:57:29 -0000       1.36
+++ server/stream.h     5 Dec 2007 11:31:52 -0000       1.37
@@ -45,8 +45,12 @@
 
 /// SWF stream wrapper class
 //
-/// This class is used for loading variable-length data from
-/// a stream, and keeping track of SWF tag boundaries.
+/// This class is used for loading variable-length data
+/// from a stream, and keeping track of SWF tag boundaries.
+///
+/// Provides 'aligned' and 'bitwise' read functions:
+/// - aligned reads always start on a byte boundary
+/// - bitwise reads can cross byte boundaries
 /// 
 class DSOEXPORT stream
 {
@@ -58,40 +62,68 @@
        /// Reads a bit-packed unsigned integer from the stream
        /// and returns it.  The given bitcount determines the
        /// number of bits to read.
+       //
+       /// bitwise read
+       ///
        unsigned read_uint(unsigned short bitcount);
 
        /// \brief
        /// Reads a single bit off the stream
        /// and returns it.  
+       //
+       /// bitwise read
+       ///
        bool read_bit();
 
        /// \brief
        /// Reads a bit-packed little-endian signed integer
        /// from the stream.  The given bitcount determines the
        /// number of bits to read.
+       //
+       /// bitwise read
+       ///
        int     read_sint(unsigned short bitcount);
 
-       /// \brief
-       /// Reads a little-endian decimal point value in the
-       /// format that the first half is before the decimal
-       /// point and the second half is after the decimal.
-       /// _fixed is 32 bits, short_fixed is 16. The _sfixed
-       /// versions read a signed fixed value.
+       /// Read a 16.16 fixed point signed value
+       //
+       /// aligned read
+       ///
        float   read_fixed();
+
+       /// Read a 16.16 fixed point unsigned value
+       //
+       /// aligned read
+       ///
        float   read_ufixed();
+
+       /// Read a 8.8 fixed point unsigned value
+       //
+       /// aligned read
+       ///
        float   read_short_ufixed();
+
+       /// Read a 8.8 fixed point signed value
+       //
+       /// aligned read
+       ///
        float   read_short_sfixed();
 
-       /// \brief
-       /// Read floating point values, not in the fixed format.
+       /// Read a 16bit floating point value
+       //
+       /// aligned read
+       ///
        float   read_float();
 
-       /// \brief
-       /// Read 64-bit double values.
+       /// Read a 64-bit double value
+       //
+       /// aligned read
+       ///
        long double read_d64();
 
        /// Consume all bits of current byte
        //
+       /// This method is implicitly called by all 'aligned' reads.
+       ///
        /// NOTE:
        /// The position returned by get_position() won't be changed
        /// by calls to this function, altought any subsequent reads
@@ -103,39 +135,56 @@
                // m_current_byte = 0; // this is not needed
        }
 
-       /// \brief
        /// Read <count> bytes from the source stream and copy that data to 
<buf>.
-       /// Implicitely aligns to the next byte.
+       //
+       /// aligned read
+       ///
        unsigned read(char *buf, unsigned count);
        
-       /// \brief
        /// Read a aligned unsigned 8-bit value from the stream.                
+       //
+       /// aligned read
+       ///
        uint8_t  read_u8();
 
-       /// \brief
        /// Read a aligned signed 8-bit value from the stream.          
+       //
+       /// aligned read
+       ///
        int8_t   read_s8();
 
-       /// \brief
        /// Read a aligned unsigned 16-bit value from the stream.               
+       //
+       /// aligned read
+       ///
        boost::uint16_t read_u16();
 
-       /// \brief
        /// Read a aligned signed 16-bit value from the stream.         
+       //
+       /// aligned read
+       ///
        boost::int16_t  read_s16();
 
-       /// \brief
        /// Read a aligned unsigned 32-bit value from the stream.               
+       //
+       /// aligned read
+       ///
        boost::uint32_t read_u32();
 
        /// \brief
        /// Read a aligned signed 32-bit value from the stream.         
+       //
+       /// aligned read
+       ///
        boost::int32_t  read_s32();
 
        /// \brief
        /// Read a variable length unsigned 32-bit value from the stream.
        /// These values continue until either the high bit is not set or
        /// until 5 bytes have been read.
+       //
+       /// aligned read
+       ///
        boost::uint32_t read_V32()
        {
                boost::uint32_t res = read_u8();
@@ -157,6 +206,9 @@
        /// \brief
        /// Skip a variable length unsigned 32-bit value in the stream.
        /// This is faster than doing the bitwise arithmetic of full reading.
+       ///
+       /// aligned read
+       ///
        void skip_V32()
        {
                if (!(read_u8() & 0x80))
@@ -175,9 +227,11 @@
        //
        /// If the byte == 0xff, read the lenght in 
        /// next two bytes.
-       //
+       ///
        /// Takes care of integrity check (ensureByte)
        ///
+       /// aligned read
+       ///
        unsigned read_variable_count()
        {
                ensureBytes(1);
@@ -194,6 +248,9 @@
        /// Reads *and new[]'s* the string from the given file.
        /// Ownership passes to the caller; caller must delete[] the
        /// string when it is done with it.
+       ///
+       /// aligned read
+       ///
        char*   read_string();  
 
        /// \brief
@@ -201,6 +258,8 @@
        /// assigns it to the given std::string, overriding any
        /// previous value of it.
        ///
+       /// aligned read
+       ///
        void    read_string(std::string& to);
 
        /// \brief
@@ -209,6 +268,8 @@
        /// string when it is done with it.
        /// Length of string is read from the first byte.
        ///
+       /// aligned read
+       ///
        char*   read_string_with_length();
 
        /// Reads a sized string into a provided std::string.
@@ -218,6 +279,8 @@
        /// @param to
        ///     Output argument. Any previous value will be overriden.
        ///
+       /// aligned read
+       ///
        void    read_string_with_length(std::string& to);
 
        /// Reads a sized string into a provided std::string.
@@ -229,6 +292,8 @@
        /// @param to
        ///     Output argument. Any previous value will be overriden.
        ///
+       /// aligned read
+       ///
        void    read_string_with_length(unsigned len, std::string& to);
 
        /// Return our current (byte) position in the input stream.
@@ -242,9 +307,8 @@
        ///
        unsigned long get_position();
 
-       /// Set the file position to the given value.
+       /// Set the file position to the given value (byte aligned)
        //
-       ///
        /// If we're scanning a tag, don't allow seeking past
        /// the end or before start of it.
        ///
@@ -259,7 +323,10 @@
        /// Return the file position of the end of the current tag.
        unsigned long get_tag_end_position();
 
-       /// Return the tag type.
+       /// Open an SWF tag and return it's type.
+       //
+       /// aligned read
+       ///
        SWF::tag_type   open_tag();
 
        /// Seek to the end of the most-recently-opened tag.
@@ -274,6 +341,11 @@
        ///     - skipping given number of bytes reaches end of
        ///       current tag, if any.
        ///
+       /// WARNING: alignment is not specified here, the method uses
+       ///          get_position() which is known NOT to consider
+       ///          a fully-read byte as already "skipped"
+       ///          TODO: force alignment and see what happens !!
+       ///
        bool skip_bytes(unsigned num)
        {
                // there's probably a better way, but
@@ -285,6 +357,7 @@
        /// Discard all bytes up to end of tag
        void skip_to_tag_end()
        {
+               // set_position will call align...
                set_position(get_tag_end_position());
        }
 
@@ -298,6 +371,10 @@
        ///
        /// NOTE: if GNASH_TRUST_SWF_INPUT is defined this function is a no-op 
        ///
+       /// WARNING: this function is BOGUS as it will consider the current
+       ///          byte as available no matter if bits have been read from
+       ///          it or not. TODO: consider consumed bits and see what 
happens.
+       ///
        void ensureBytes(unsigned long needed)
        {
 #ifndef GNASH_TRUST_SWF_INPUT