IStream.h

00001 /***************************************************************************
00002  *                                                                         *
00003  *   (c) Art Tevs, MPI Informatik Saarbruecken                             *
00004  *       mailto: <tevs@mpi-sb.mpg.de>                                      *
00005  *                                                                         *
00006  *   This program is free software; you can redistribute it and/or modify  *
00007  *   it under the terms of the GNU General Public License as published by  *
00008  *   the Free Software Foundation; either version 2 of the License, or     *
00009  *   (at your option) any later version.                                   *
00010  *                                                                         *
00011  ***************************************************************************/
00012 
00013 
00014 #ifndef _NR_I_STREAM_H_
00015 #define _NR_I_STREAM_H_
00016 
00017 
00018 //----------------------------------------------------------------------------------
00019 // Includes
00020 //----------------------------------------------------------------------------------
00021 #include "Prerequisities.h"
00022 
00023 namespace nrEngine{
00024 
00025         //! Stream is an interface for stream objects (files, urls, ...)
00026         /**
00027         * IStream represents an interface for every kind of stream objects.
00028         * Stream objects should be able to pass the data from somewhere else
00029         * to the requester (e.g. engine). The interface is similar to the
00030         * std::istream object so you can think it is like a wrapper.
00031         *
00032         * Good example for such stream objects could be a file stream. In the
00033         * standard c++ library you already have got the ifstream which can be
00034         * reimplemented for this interface.
00035         *
00036         *
00037         * \ingroup gp
00038         **/
00039         class _NRExport IStream {
00040         public:
00041 
00042                 //! Start position for the seeking
00043                 enum {
00044 
00045                         //! Compute new cursor position from the beginning
00046                         START,
00047 
00048                         //! Seek from the current position
00049                         CURRENT,
00050 
00051                         //! NEw position is computed from the end of file
00052                         END
00053                 };
00054 
00055                 /**
00056                 * Empty default constructor.
00057                 * @param streamBufSize Size of the buffer for this stream. Only buffered streams.
00058                 **/
00059                 IStream(uint32 streamBufSize = STREAM_BUFFER_SIZE);
00060 
00061                 /**
00062                 * Constructor allows specify a name for the stream
00063                 * @param name Name of the stream
00064                 * @param streamBufSize Size of the buffer for this stream. Only buffered streams.
00065                 **/
00066                 IStream(const std::string& name, uint32 streamBufSize = STREAM_BUFFER_SIZE);
00067 
00068                 /**
00069                 * Virtual destructor allows to derive new classes from this interface
00070                 **/
00071                 virtual ~IStream();
00072 
00073                 /**
00074                 * Return the name of the stream
00075                 **/
00076                 virtual const std::string& getName()    { return mName; }
00077 
00078                 /**
00079                 * Streaming operator to stream the data to the variable
00080                 **/
00081                 template<typename T> IStream& operator>>(T& val);
00082 
00083                 /**
00084                 * Get the size of the buffer (only for buffered streams)
00085                 **/
00086                 NR_FORCEINLINE int32 getBufferSize() const { return mStreamBufSize; }
00087 
00088                 /**
00089                 * Read data from the stream (like read from stdio.h).
00090                 *
00091                 * @param buf Here the readed data will be stored
00092                 * @param count Number of bytes to be readed
00093                 *
00094                 * @return Count fo readed bytes.
00095                 * @note <i>buf</i> should have at least size <i>count</i>
00096                 **/
00097                 size_t read(void *buf, size_t count);
00098 
00099                 /**
00100                 * Same as read but allows reading of specified count of
00101                 * elements instead of bytes.
00102                 *
00103                 * @param buf Buffer where to store the readed data
00104                 * @param size Size of each element to be readed
00105                 * @param nmemb Count of elements
00106                 *
00107                 * @return Number of successfully readed elements (not bytes)
00108                 **/
00109                 virtual size_t read(void *buf, size_t size, size_t nmemb) = 0;
00110 
00111                 /**
00112                 * Same as read, but reads the line until it found
00113                 * the delimiter string in the data
00114                 **/
00115                 virtual size_t readDelim(void* buf, size_t count, const std::string& delim = std::string("\n")) = 0;
00116 
00117                 /**
00118                 * Returns the current byte offset from the beginning
00119                 * in other words position of the stream cursor
00120                 **/
00121                 virtual size_t tell() const = 0;
00122 
00123                 /**
00124                 * Returns true if end of the stream is reached
00125                 **/
00126                 virtual bool eof() const = 0;
00127 
00128                 /**
00129                 * Return the full data containing in the stream only if we were
00130                 * able to retrieve the data. If the stream is buffered, so it
00131                 * should return the content of the whole buffer and retrieve new data.
00132                 * @param count Return count of bytes returned by the function
00133                 **/
00134                 virtual byte* getData(size_t& count) const = 0;
00135 
00136                 /**
00137                 * Only for text-only streams. You have the abbility to return the whole
00138                 * stream content as a string
00139                 **/
00140                 virtual std::string getAsString();
00141 
00142                 /**
00143                 * Read a line from the stream. Only usefull for text-only-streams
00144                 **/
00145                 virtual std::string getLine();
00146 
00147                 /**
00148                 * Seek the read pointer to specified position.
00149                 *
00150                 * @param offset Number of bytes to jump
00151                 * @param whence From where we should compute the new position
00152                 *                               CURRENT, START, END
00153                 * @return false if error occurs (e.g. eof or wrong whence position)
00154                 **/
00155                 virtual bool seek(int32 offset, int32 whence = CURRENT) = 0;
00156 
00157                 /**
00158                 * Returns the size of the stream (ength of the data in the stream)
00159                 * If size could not be determined, so return 0
00160                 **/
00161                 size_t size() const { return mSize; }
00162 
00163                 /**
00164                 * Close the stream. After you close it no operations like seek, or read
00165                 * are valid anymore. The stream is also automaticly closed if
00166                 * you call the destructor.
00167                 **/
00168                 virtual void close () = 0;
00169 
00170                 //! Default size of the buffer
00171                 static const uint32 STREAM_BUFFER_SIZE = 256;
00172 
00173         protected:
00174 
00175                 //! Name of the stream
00176                 std::string     mName;
00177 
00178                 //! Size of the stream in bytes. If size could not be determined so 0
00179                 size_t  mSize;
00180 
00181                 //! Our stream buffer should be of this size
00182                 uint32 mStreamBufSize;
00183 
00184                 //! Buffer to hold the data.
00185                 byte*   mBuffer;
00186 
00187         };
00188 
00189 }; // end namespace
00190 
00191 #endif

Generated on Wed Sep 12 23:19:42 2007 for nrEngine by  doxygen 1.5.1