libbase/IOChannel.h

   1 // IOChannel.h - a virtual IO channel, for Gnash
   2 //
   3 //   Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012
   4 //   Free Software 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 <string>
  25 #include <ios> // for std::streamsize
  26 #include <cstdint> // for boost int types
  27
  28 #include "dsodefs.h" // DSOEXPORT
  29 #include "GnashException.h" // for IOException inheritance
  30
  31 namespace gnash {
  32
  33 /// Exception signalling an IO error
  34 class DSOEXPORT IOException : public GnashException
  35 {
  36 public:
  37     IOException(const std::string& s) : GnashException(s) {}
  38     IOException() : GnashException("IO error") {}
  39 };
  40
  41 /// A virtual IO channel
  42 class DSOEXPORT IOChannel
  43 {
  44 public:
  45
  46     virtual ~IOChannel() {}
  47
  48     /// \brief Read a 32-bit word from a little-endian stream.
  49     ///    returning it as a native-endian word.
  50     //
  51     /// Throw IOException on error
  52     ///
  53     std::uint32_t read_le32();
  54
  55     /// Read a 16-bit word from a little-endian stream.
  56     //
  57     /// Throw IOException on error
  58     ///
  59     std::uint16_t read_le16();
  60
  61     /// Read a single byte from the stream
  62     //
  63     /// Throw IOException on error
  64     ///
  65     std::uint8_t read_byte();
  66
  67     /// Read the given number of bytes from the stream
  68     //
  69     /// Return the number of bytes actually read.
  70     /// EOF might cause it to be < num.
  71     ///
  72     /// Throw IOException on error
  73     ///
  74     virtual std::streamsize read(void* dst, std::streamsize num)=0;
  75
  76     /// Read at most the given number of bytes w/out blocking
  77     //
  78     /// Throw IOException on error
  79     ///
  80     /// @return The number of bytes actually read.
  81     ///         A short count may mean EOF was hit or
  82     ///         data didn't arrive yet.
  83     ///
  84     /// Default implementation proxies the call to the
  85     /// blocking version.
  86     ///
  87     virtual std::streamsize readNonBlocking(void* dst, std::streamsize num)
  88     {
  89         return read(dst, num);
  90     }
  91
  92     /// Write the given number of bytes to the stream
  93     //
  94     /// Throw IOException on error/unsupported op.
  95     ///
  96     virtual std::streamsize write(const void* src, std::streamsize num);
  97
  98     /// \brief
  99     /// Read up to max_length characters, returns the number of characters
 100     /// read, or -1 if the string length is longer than max_length.
 101     //
 102     /// Stops at the first \0 character if it comes before max_length.
 103     ///
 104     /// Guarantees termination of the string.
 105     ///
 106     /// @return the number of characters read, or -1 no null-termination
 107     ///         was found within max_length
 108     ///
 109     /// Throw IOException on error
 110     ///
 111     int    read_string(char* dst, int max_length);
 112
 113     /// Return current stream position
 114     //
 115     /// Throw IOException on error
 116     ///
 117     virtual std::streampos tell() const = 0;
 118
 119     /// Seek to the specified position
 120     //
 121     ///
 122     /// Throw IOException on error
 123     ///
 124     /// @return true on success, or false on failure.
 125     ///
 126     virtual bool seek(std::streampos p) = 0;
 127
 128     /// Seek to the end of the stream
 129     //
 130     /// Throw IOException on error
 131     ///
 132     virtual void go_to_end() = 0;
 133
 134     /// Return true if the end of the stream has been reached.
 135     //
 136     /// Throw IOException on error
 137     ///
 138     virtual bool eof() const = 0;
 139
 140     /// Return true if the stream is in an error state
 141     //
 142     /// When the stream is in an error state there's nothing
 143     /// you can do about it, just delete it and log the error.
 144     virtual bool bad() const = 0;
 145
 146     /// Get the size of the stream (unreliably).
 147     //
 148     /// Size of stream is unreliable as not all input
 149     /// channels have a mechanism to advertise size,
 150     /// and some have one but isn't necessarely truthful
 151     /// (a few HTTP severs are bogus in this reguard).
 152     ///
 153     /// @return unreliable input size, (size_t)-1 if not known.
 154     ///
 155     virtual size_t size() const { return static_cast<size_t>(-1); }
 156
 157 };
 158
 159 } // namespace gnash
 160
 161 #endif // GNASH_IOCHANNEL_H
 162
 163
 164 // Local Variables:
 165 // mode: C++
 166 // indent-tabs-mode: t
 167 // End: