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