libbase/IOChannel.h

   1 // IOChannel.h - a virtual IO channel, for Gnash
   2 //
   3 //   Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010 Free Software
   4 //   Foundation, Inc
   5 //
   6 // This program is free software; you can redistribute it and/or modify
   7 // it under the terms of the GNU General Public License as published by
   8 // the Free Software Foundation; either version 3 of the License, or
   9 // (at your option) any later version.
  10 //
  11 // This program is distributed in the hope that it will be useful,
  12 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 // GNU General Public License for more details.
  15 //
  16 // You should have received a copy of the GNU General Public License
  17 // along with this program; if not, write to the Free Software
  18 // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  19
  20
  21 #ifndef GNASH_IOCHANNEL_H
  22 #define GNASH_IOCHANNEL_H
  23
  24 #include "dsodefs.h" // DSOEXPORT
  25 #include "GnashException.h" // for IOException inheritance
  26
  27 #include <string>
  28 #include <boost/cstdint.hpp> // for boost int types
  29 #include <ios>
  30
  31 namespace gnash {
  32
  33 /// Exception signalling an IO error
  34 class DSOEXPORT IOException : public GnashException {
  35 public:
  36     IOException(const std::string& s) : GnashException(s) {}
  37     IOException() : GnashException("IO error") {}
  38 };
  39
  40 /// A virtual IO channel
  41 class DSOEXPORT IOChannel
  42 {
  43 public:
  44
  45     virtual ~IOChannel() {}
  46
  47     /// \brief Read a 32-bit word from a little-endian stream.
  48     ///    returning it as a native-endian word.
  49     //
  50     /// Throw IOException on error
  51     ///
  52     boost::uint32_t read_le32();
  53
  54     /// Read a 16-bit word from a little-endian stream.
  55     //
  56     /// Throw IOException on error
  57     ///
  58     boost::uint16_t read_le16();
  59
  60     /// Read a single byte from the stream
  61     //
  62     /// Throw IOException on error
  63     ///
  64     boost::uint8_t read_byte();
  65
  66     /// Read the given number of bytes from the stream
  67     //
  68     /// Return the number of bytes actually read.
  69     /// EOF might cause it to be < num.
  70     ///
  71     /// Throw IOException on error
  72     ///
  73     virtual std::streamsize read(void* dst, std::streamsize num)=0;
  74
  75     /// Read at most the given number of bytes w/out blocking
  76     //
  77     /// Throw IOException on error
  78     ///
  79     /// @return The number of bytes actually read.
  80     ///         A short count may mean EOF was hit or
  81     ///         data didn't arrive yet.
  82     ///
  83     /// Default implementation proxies the call to the
  84     /// blocking version.
  85     ///
  86     virtual std::streamsize readNonBlocking(void* dst, std::streamsize num)
  87     {
  88         return read(dst, num);
  89     }
  90
  91     /// Write the given number of bytes to the stream
  92     //
  93     /// Throw IOException on error/unsupported op.
  94     ///
  95     virtual std::streamsize write(const void* src, std::streamsize num);
  96
  97     /// \brief
  98     /// Read up to max_length characters, returns the number of characters
  99     /// read, or -1 if the string length is longer than max_length.
 100     //
 101     /// Stops at the first \0 character if it comes before max_length.
 102     ///
 103     /// Guarantees termination of the string.
 104     ///
 105     /// @return the number of characters read, or -1 no null-termination
 106     ///         was found within max_length
 107     ///
 108     /// Throw IOException on error
 109     ///
 110     int    read_string(char* dst, int max_length);
 111
 112     /// Read a 32-bit float from a little-endian stream.
 113     //
 114     /// NOTE: this currently relies on host FP format being the
 115         ///       same as the Flash one (presumably IEEE 754).
 116     ///
 117     /// Throw IOException on error
 118     ///
 119     float read_float32();
 120
 121     /// Return current stream position
 122     //
 123     /// Throw IOException on error
 124     ///
 125     virtual std::streampos tell() const = 0;
 126
 127     /// Seek to the specified position
 128     //
 129     ///
 130     /// Throw IOException on error
 131     ///
 132     /// @return true on success, or false on failure.
 133     ///
 134     virtual bool seek(std::streampos p) = 0;
 135
 136     /// Seek to the end of the stream
 137     //
 138     /// Throw IOException on error
 139     ///
 140     virtual void go_to_end() = 0;
 141
 142     /// Return true if the end of the stream has been reached.
 143     //
 144     /// Throw IOException on error
 145     ///
 146     virtual bool eof() const = 0;
 147
 148     /// Return true if the stream is in an error state
 149     //
 150     /// When the stream is in an error state there's nothing
 151     /// you can do about it, just delete it and log the error.
 152     virtual bool bad() const = 0;
 153
 154     /// Get the size of the stream (unreliably).
 155     //
 156     /// Size of stream is unreliable as not all input
 157     /// channels have a mechanism to advertise size,
 158     /// and some have one but isn't necessarely truthful
 159     /// (a few HTTP severs are bogus in this reguard).
 160     ///
 161     /// @return unreliable input size, (size_t)-1 if not known.
 162     ///
 163     virtual size_t size() const { return static_cast<size_t>(-1); }
 164
 165 };
 166
 167 } // namespace gnash
 168
 169 #endif // GNASH_IOCHANNEL_H
 170
 171
 172 // Local Variables:
 173 // mode: C++
 174 // indent-tabs-mode: t
 175 // End: