[1809] | 1 | /*
|
---|
| 2 | -----------------------------------------------------------------------------
|
---|
| 3 | This source file is part of OGRE
|
---|
| 4 | (Object-oriented Graphics Rendering Engine)
|
---|
| 5 | For the latest info, see http://www.ogre3d.org/
|
---|
| 6 |
|
---|
| 7 | Copyright (c) 2000-2005 The OGRE Team
|
---|
| 8 | Also see acknowledgements in Readme.html
|
---|
| 9 |
|
---|
| 10 | This program is free software; you can redistribute it and/or modify it under
|
---|
| 11 | the terms of the GNU Lesser General Public License as published by the Free Software
|
---|
| 12 | Foundation; either version 2 of the License, or (at your option) any later
|
---|
| 13 | version.
|
---|
| 14 |
|
---|
| 15 | This program is distributed in the hope that it will be useful, but WITHOUT
|
---|
| 16 | ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
|
---|
| 17 | FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
|
---|
| 18 |
|
---|
| 19 | You should have received a copy of the GNU Lesser General Public License along with
|
---|
| 20 | this program; if not, write to the Free Software Foundation, Inc., 59 Temple
|
---|
| 21 | Place - Suite 330, Boston, MA 02111-1307, USA, or go to
|
---|
| 22 | http://www.gnu.org/copyleft/lesser.txt.
|
---|
| 23 | -----------------------------------------------------------------------------
|
---|
| 24 | */
|
---|
| 25 | #ifndef __DataStream_H__
|
---|
| 26 | #define __DataStream_H__
|
---|
| 27 |
|
---|
| 28 | #include "OgrePrerequisites.h"
|
---|
| 29 | #include "OgreString.h"
|
---|
| 30 | #include "OgreSharedPtr.h"
|
---|
| 31 | #include <istream>
|
---|
| 32 |
|
---|
| 33 | namespace Ogre {
|
---|
| 34 |
|
---|
| 35 | /** General purpose class used for encapsulating the reading of data.
|
---|
| 36 | @remarks
|
---|
| 37 | This class performs basically the same tasks as std::basic_istream,
|
---|
| 38 | except that it does not have any formatting capabilities, and is
|
---|
| 39 | designed to be subclassed to receive data from multiple sources,
|
---|
| 40 | including libraries which have no compatiblity with the STL's
|
---|
| 41 | stream interfaces. As such, this is an abstraction of a set of
|
---|
| 42 | wrapper classes which pretend to be standard stream classes but
|
---|
| 43 | can actually be implemented quite differently.
|
---|
| 44 | @par
|
---|
| 45 | Generally, if a plugin or application provides an ArchiveFactory,
|
---|
| 46 | it should also provide a DataStream subclass which will be used
|
---|
| 47 | to stream data out of that Archive implementation, unless it can
|
---|
| 48 | use one of the common implementations included.
|
---|
| 49 | @note
|
---|
| 50 | Ogre makes no guarantees about thread safety, for performance reasons.
|
---|
| 51 | If you wish to access stream data asynchronously then you should
|
---|
| 52 | organise your own mutexes to avoid race conditions.
|
---|
| 53 | */
|
---|
| 54 | class _OgreExport DataStream
|
---|
| 55 | {
|
---|
| 56 | protected:
|
---|
| 57 | /// The name (e.g. resource name) that can be used to identify the source fot his data (optional)
|
---|
| 58 | String mName;
|
---|
| 59 | /// Size of the data in the stream (may be 0 if size cannot be determined)
|
---|
| 60 | size_t mSize;
|
---|
| 61 | #define OGRE_STREAM_TEMP_SIZE 128
|
---|
| 62 | public:
|
---|
| 63 | /// Constructor for creating unnamed streams
|
---|
| 64 | DataStream() : mSize(0) {}
|
---|
| 65 | /// Constructor for creating named streams
|
---|
| 66 | DataStream(const String& name) : mName(name), mSize(0) {}
|
---|
| 67 | /// Returns the name of the stream, if it has one.
|
---|
| 68 | const String& getName(void) { return mName; }
|
---|
| 69 | virtual ~DataStream() {}
|
---|
| 70 | // Streaming operators
|
---|
| 71 | template<typename T> DataStream& operator>>(T& val);
|
---|
| 72 | /** Read the requisite number of bytes from the stream,
|
---|
| 73 | stopping at the end of the file.
|
---|
| 74 | @param buf Reference to a buffer pointer
|
---|
| 75 | @param count Number of bytes to read
|
---|
| 76 | @returns The number of bytes read
|
---|
| 77 | */
|
---|
| 78 | virtual size_t read(void* buf, size_t count) = 0;
|
---|
| 79 | /** Get a single line from the stream.
|
---|
| 80 | @remarks
|
---|
| 81 | The delimiter character is not included in the data
|
---|
| 82 | returned, and it is skipped over so the next read will occur
|
---|
| 83 | after it. The buffer contents will include a
|
---|
| 84 | terminating character.
|
---|
| 85 | @note
|
---|
| 86 | If you used this function, you <b>must</b> open the stream in <b>binary mode</b>,
|
---|
| 87 | otherwise, it'll produce unexpected results.
|
---|
| 88 | @param buf Reference to a buffer pointer
|
---|
| 89 | @param maxCount The maximum length of data to be read, excluding the terminating character
|
---|
| 90 | @param delim The delimiter to stop at
|
---|
| 91 | @returns The number of bytes read, excluding the terminating character
|
---|
| 92 | */
|
---|
| 93 | virtual size_t readLine(char* buf, size_t maxCount, const String& delim = "\n");
|
---|
| 94 |
|
---|
| 95 | /** Returns a String containing the next line of data, optionally
|
---|
| 96 | trimmed for whitespace.
|
---|
| 97 | @remarks
|
---|
| 98 | This is a convenience method for text streams only, allowing you to
|
---|
| 99 | retrieve a String object containing the next line of data. The data
|
---|
| 100 | is read up to the next newline character and the result trimmed if
|
---|
| 101 | required.
|
---|
| 102 | @note
|
---|
| 103 | If you used this function, you <b>must</b> open the stream in <b>binary mode</b>,
|
---|
| 104 | otherwise, it'll produce unexpected results.
|
---|
| 105 | @param
|
---|
| 106 | trimAfter If true, the line is trimmed for whitespace (as in
|
---|
| 107 | String.trim(true,true))
|
---|
| 108 | */
|
---|
| 109 | virtual String getLine( bool trimAfter = true );
|
---|
| 110 |
|
---|
| 111 | /** Returns a String containing the entire stream.
|
---|
| 112 | @remarks
|
---|
| 113 | This is a convenience method for text streams only, allowing you to
|
---|
| 114 | retrieve a String object containing all the data in the stream.
|
---|
| 115 | */
|
---|
| 116 | virtual String getAsString(void);
|
---|
| 117 |
|
---|
| 118 | /** Skip a single line from the stream.
|
---|
| 119 | @note
|
---|
| 120 | If you used this function, you <b>must</b> open the stream in <b>binary mode</b>,
|
---|
| 121 | otherwise, it'll produce unexpected results.
|
---|
| 122 | @param delim The delimiter(s) to stop at
|
---|
| 123 | @returns The number of bytes skipped
|
---|
| 124 | */
|
---|
| 125 | virtual size_t skipLine(const String& delim = "\n");
|
---|
| 126 |
|
---|
| 127 | /** Skip a defined number of bytes. This can also be a negative value, in which case
|
---|
| 128 | the file pointer rewinds a defined number of bytes. */
|
---|
| 129 | virtual void skip(long count) = 0;
|
---|
| 130 |
|
---|
| 131 | /** Repositions the read point to a specified byte.
|
---|
| 132 | */
|
---|
| 133 | virtual void seek( size_t pos ) = 0;
|
---|
| 134 |
|
---|
| 135 | /** Returns the current byte offset from beginning */
|
---|
| 136 | virtual size_t tell(void) const = 0;
|
---|
| 137 |
|
---|
| 138 | /** Returns true if the stream has reached the end.
|
---|
| 139 | */
|
---|
| 140 | virtual bool eof(void) const = 0;
|
---|
| 141 |
|
---|
| 142 | /** Returns the total size of the data to be read from the stream,
|
---|
| 143 | or 0 if this is indeterminate for this stream.
|
---|
| 144 | */
|
---|
| 145 | size_t size(void) const { return mSize; }
|
---|
| 146 |
|
---|
| 147 | /** Close the stream; this makes further operations invalid. */
|
---|
| 148 | virtual void close(void) = 0;
|
---|
| 149 |
|
---|
| 150 |
|
---|
| 151 | };
|
---|
| 152 |
|
---|
| 153 | /** Shared pointer to allow data streams to be passed around without
|
---|
| 154 | worrying about deallocation
|
---|
| 155 | */
|
---|
| 156 | typedef SharedPtr<DataStream> DataStreamPtr;
|
---|
| 157 |
|
---|
| 158 | /// List of DataStream items
|
---|
| 159 | typedef std::list<DataStreamPtr> DataStreamList;
|
---|
| 160 | /// Shared pointer to list of DataStream items
|
---|
| 161 | typedef SharedPtr<DataStreamList> DataStreamListPtr;
|
---|
| 162 |
|
---|
| 163 | /** Common subclass of DataStream for handling data from chunks of memory.
|
---|
| 164 | */
|
---|
| 165 | class _OgreExport MemoryDataStream : public DataStream
|
---|
| 166 | {
|
---|
| 167 | protected:
|
---|
| 168 | /// Pointer to the start of the data area
|
---|
| 169 | uchar* mData;
|
---|
| 170 | /// Pointer to the current position in the memory
|
---|
| 171 | uchar* mPos;
|
---|
| 172 | /// Pointer to the end of the memory
|
---|
| 173 | uchar* mEnd;
|
---|
| 174 | /// Do we delete the memory on close
|
---|
| 175 | bool mFreeOnClose;
|
---|
| 176 | public:
|
---|
| 177 |
|
---|
| 178 | /** Wrap an existing memory chunk in a stream.
|
---|
| 179 | @param pMem Pointer to the exising memory
|
---|
| 180 | @param size The size of the memory chunk in bytes
|
---|
| 181 | @param freeOnClose If true, the memory associated will be destroyed
|
---|
| 182 | when the stream is destroyed.
|
---|
| 183 | */
|
---|
| 184 | MemoryDataStream(void* pMem, size_t size, bool freeOnClose = false);
|
---|
| 185 |
|
---|
| 186 | /** Wrap an existing memory chunk in a named stream.
|
---|
| 187 | @param name The name to give the stream
|
---|
| 188 | @param pMem Pointer to the exising memory
|
---|
| 189 | @param size The size of the memory chunk in bytes
|
---|
| 190 | @param freeOnClose If true, the memory associated will be destroyed
|
---|
| 191 | when the stream is destroyed.
|
---|
| 192 | */
|
---|
| 193 | MemoryDataStream(const String& name, void* pMem, size_t size,
|
---|
| 194 | bool freeOnClose = false);
|
---|
| 195 |
|
---|
| 196 | /** Create a stream which pre-buffers the contents of another stream.
|
---|
| 197 | @remarks
|
---|
| 198 | This constructor can be used to intentionally read in the entire
|
---|
| 199 | contents of another stream, copying them to the internal buffer
|
---|
| 200 | and thus making them available in memory as a single unit.
|
---|
| 201 | @param sourceStream Another DataStream which will provide the source
|
---|
| 202 | of data
|
---|
| 203 | @param freeOnClose If true, the memory associated will be destroyed
|
---|
| 204 | when the stream is destroyed.
|
---|
| 205 | */
|
---|
| 206 | MemoryDataStream(DataStream& sourceStream,
|
---|
| 207 | bool freeOnClose = true);
|
---|
| 208 |
|
---|
| 209 | /** Create a stream which pre-buffers the contents of another stream.
|
---|
| 210 | @remarks
|
---|
| 211 | This constructor can be used to intentionally read in the entire
|
---|
| 212 | contents of another stream, copying them to the internal buffer
|
---|
| 213 | and thus making them available in memory as a single unit.
|
---|
| 214 | @param sourceStream Weak reference to another DataStream which will provide the source
|
---|
| 215 | of data
|
---|
| 216 | @param freeOnClose If true, the memory associated will be destroyed
|
---|
| 217 | when the stream is destroyed.
|
---|
| 218 | */
|
---|
| 219 | MemoryDataStream(DataStreamPtr& sourceStream,
|
---|
| 220 | bool freeOnClose = true);
|
---|
| 221 |
|
---|
| 222 | /** Create a named stream which pre-buffers the contents of
|
---|
| 223 | another stream.
|
---|
| 224 | @remarks
|
---|
| 225 | This constructor can be used to intentionally read in the entire
|
---|
| 226 | contents of another stream, copying them to the internal buffer
|
---|
| 227 | and thus making them available in memory as a single unit.
|
---|
| 228 | @param name The name to give the stream
|
---|
| 229 | @param sourceStream Another DataStream which will provide the source
|
---|
| 230 | of data
|
---|
| 231 | @param freeOnClose If true, the memory associated will be destroyed
|
---|
| 232 | when the stream is destroyed.
|
---|
| 233 | */
|
---|
| 234 | MemoryDataStream(const String& name, DataStream& sourceStream,
|
---|
| 235 | bool freeOnClose = true);
|
---|
| 236 |
|
---|
| 237 | /** Create a named stream which pre-buffers the contents of
|
---|
| 238 | another stream.
|
---|
| 239 | @remarks
|
---|
| 240 | This constructor can be used to intentionally read in the entire
|
---|
| 241 | contents of another stream, copying them to the internal buffer
|
---|
| 242 | and thus making them available in memory as a single unit.
|
---|
| 243 | @param name The name to give the stream
|
---|
| 244 | @param sourceStream Another DataStream which will provide the source
|
---|
| 245 | of data
|
---|
| 246 | @param freeOnClose If true, the memory associated will be destroyed
|
---|
| 247 | when the stream is destroyed.
|
---|
| 248 | */
|
---|
| 249 | MemoryDataStream(const String& name, const DataStreamPtr& sourceStream,
|
---|
| 250 | bool freeOnClose = true);
|
---|
| 251 |
|
---|
| 252 | /** Create a stream with a brand new empty memory chunk.
|
---|
| 253 | @param size The size of the memory chunk to create in bytes
|
---|
| 254 | @param freeOnClose If true, the memory associated will be destroyed
|
---|
| 255 | when the stream is destroyed.
|
---|
| 256 | */
|
---|
| 257 | MemoryDataStream(size_t size, bool freeOnClose = true);
|
---|
| 258 | /** Create a named stream with a brand new empty memory chunk.
|
---|
| 259 | @param name The name to give the stream
|
---|
| 260 | @param size The size of the memory chunk to create in bytes
|
---|
| 261 | @param freeOnClose If true, the memory associated will be destroyed
|
---|
| 262 | when the stream is destroyed.
|
---|
| 263 | */
|
---|
| 264 | MemoryDataStream(const String& name, size_t size,
|
---|
| 265 | bool freeOnClose = true);
|
---|
| 266 |
|
---|
| 267 | ~MemoryDataStream();
|
---|
| 268 |
|
---|
| 269 | /** Get a pointer to the start of the memory block this stream holds. */
|
---|
| 270 | uchar* getPtr(void) { return mData; }
|
---|
| 271 |
|
---|
| 272 | /** Get a pointer to the current position in the memory block this stream holds. */
|
---|
| 273 | uchar* getCurrentPtr(void) { return mPos; }
|
---|
| 274 |
|
---|
| 275 | /** @copydoc DataStream::read
|
---|
| 276 | */
|
---|
| 277 | size_t read(void* buf, size_t count);
|
---|
| 278 | /** @copydoc DataStream::readLine
|
---|
| 279 | */
|
---|
| 280 | size_t readLine(char* buf, size_t maxCount, const String& delim = "\n");
|
---|
| 281 |
|
---|
| 282 | /** @copydoc DataStream::skipLine
|
---|
| 283 | */
|
---|
| 284 | size_t skipLine(const String& delim = "\n");
|
---|
| 285 |
|
---|
| 286 | /** @copydoc DataStream::skip
|
---|
| 287 | */
|
---|
| 288 | void skip(long count);
|
---|
| 289 |
|
---|
| 290 | /** @copydoc DataStream::seek
|
---|
| 291 | */
|
---|
| 292 | void seek( size_t pos );
|
---|
| 293 |
|
---|
| 294 | /** @copydoc DataStream::tell
|
---|
| 295 | */
|
---|
| 296 | size_t tell(void) const;
|
---|
| 297 |
|
---|
| 298 | /** @copydoc DataStream::eof
|
---|
| 299 | */
|
---|
| 300 | bool eof(void) const;
|
---|
| 301 |
|
---|
| 302 | /** @copydoc DataStream::close
|
---|
| 303 | */
|
---|
| 304 | void close(void);
|
---|
| 305 |
|
---|
| 306 | /** Sets whether or not to free the encapsulated memory on close. */
|
---|
| 307 | void setFreeOnClose(bool free) { mFreeOnClose = free; }
|
---|
| 308 | };
|
---|
| 309 |
|
---|
| 310 | /** Shared pointer to allow memory data streams to be passed around without
|
---|
| 311 | worrying about deallocation
|
---|
| 312 | */
|
---|
| 313 | typedef SharedPtr<MemoryDataStream> MemoryDataStreamPtr;
|
---|
| 314 |
|
---|
| 315 | /** Common subclass of DataStream for handling data from
|
---|
| 316 | std::basic_istream.
|
---|
| 317 | */
|
---|
| 318 | class _OgreExport FileStreamDataStream : public DataStream
|
---|
| 319 | {
|
---|
| 320 | protected:
|
---|
| 321 | /// Reference to source stream
|
---|
| 322 | std::ifstream* mpStream;
|
---|
| 323 | bool mFreeOnClose;
|
---|
| 324 | public:
|
---|
| 325 | /** Construct stream from an STL stream
|
---|
| 326 | @param s Pointer to source stream
|
---|
| 327 | @param freeOnClose Whether to delete the underlying stream on
|
---|
| 328 | destruction of this class
|
---|
| 329 | */
|
---|
| 330 | FileStreamDataStream(std::ifstream* s,
|
---|
| 331 | bool freeOnClose = true);
|
---|
| 332 | /** Construct named stream from an STL stream
|
---|
| 333 | @param name The name to give this stream
|
---|
| 334 | @param s Pointer to source stream
|
---|
| 335 | @param freeOnClose Whether to delete the underlying stream on
|
---|
| 336 | destruction of this class
|
---|
| 337 | */
|
---|
| 338 | FileStreamDataStream(const String& name,
|
---|
| 339 | std::ifstream* s,
|
---|
| 340 | bool freeOnClose = true);
|
---|
| 341 |
|
---|
| 342 | /** Construct named stream from an STL stream, and tell it the size
|
---|
| 343 | @remarks
|
---|
| 344 | This variant tells the class the size of the stream too, which
|
---|
| 345 | means this class does not need to seek to the end of the stream
|
---|
| 346 | to determine the size up-front. This can be beneficial if you have
|
---|
| 347 | metadata about the contents of the stream already.
|
---|
| 348 | @param name The name to give this stream
|
---|
| 349 | @param s Pointer to source stream
|
---|
| 350 | @param size Size of the stream contents in bytes
|
---|
| 351 | @param freeOnClose Whether to delete the underlying stream on
|
---|
| 352 | destruction of this class
|
---|
| 353 | */
|
---|
| 354 | FileStreamDataStream(const String& name,
|
---|
| 355 | std::ifstream* s,
|
---|
| 356 | size_t size,
|
---|
| 357 | bool freeOnClose = true);
|
---|
| 358 |
|
---|
| 359 | ~FileStreamDataStream();
|
---|
| 360 |
|
---|
| 361 | /** @copydoc DataStream::read
|
---|
| 362 | */
|
---|
| 363 | size_t read(void* buf, size_t count);
|
---|
| 364 | /** @copydoc DataStream::readLine
|
---|
| 365 | */
|
---|
| 366 | size_t readLine(char* buf, size_t maxCount, const String& delim = "\n");
|
---|
| 367 |
|
---|
| 368 | /** @copydoc DataStream::skip
|
---|
| 369 | */
|
---|
| 370 | void skip(long count);
|
---|
| 371 |
|
---|
| 372 | /** @copydoc DataStream::seek
|
---|
| 373 | */
|
---|
| 374 | void seek( size_t pos );
|
---|
| 375 |
|
---|
| 376 | /** @copydoc DataStream::tell
|
---|
| 377 | */
|
---|
| 378 | size_t tell(void) const;
|
---|
| 379 |
|
---|
| 380 | /** @copydoc DataStream::eof
|
---|
| 381 | */
|
---|
| 382 | bool eof(void) const;
|
---|
| 383 |
|
---|
| 384 | /** @copydoc DataStream::close
|
---|
| 385 | */
|
---|
| 386 | void close(void);
|
---|
| 387 |
|
---|
| 388 |
|
---|
| 389 | };
|
---|
| 390 |
|
---|
| 391 | /** Common subclass of DataStream for handling data from C-style file
|
---|
| 392 | handles.
|
---|
| 393 | @remarks
|
---|
| 394 | Use of this class is generally discouraged; if you want to wrap file
|
---|
| 395 | access in a DataStream, you should definitely be using the C++ friendly
|
---|
| 396 | FileStreamDataStream. However, since there are quite a few applications
|
---|
| 397 | and libraries still wedded to the old FILE handle access, this stream
|
---|
| 398 | wrapper provides some backwards compatibility.
|
---|
| 399 | */
|
---|
| 400 | class _OgreExport FileHandleDataStream : public DataStream
|
---|
| 401 | {
|
---|
| 402 | protected:
|
---|
| 403 | FILE* mFileHandle;
|
---|
| 404 | public:
|
---|
| 405 | /// Create stream from a C file handle
|
---|
| 406 | FileHandleDataStream(FILE* handle);
|
---|
| 407 | /// Create named stream from a C file handle
|
---|
| 408 | FileHandleDataStream(const String& name, FILE* handle);
|
---|
| 409 | ~FileHandleDataStream();
|
---|
| 410 |
|
---|
| 411 | /** @copydoc DataStream::read
|
---|
| 412 | */
|
---|
| 413 | size_t read(void* buf, size_t count);
|
---|
| 414 |
|
---|
| 415 | /** @copydoc DataStream::skip
|
---|
| 416 | */
|
---|
| 417 | void skip(long count);
|
---|
| 418 |
|
---|
| 419 | /** @copydoc DataStream::seek
|
---|
| 420 | */
|
---|
| 421 | void seek( size_t pos );
|
---|
| 422 |
|
---|
| 423 | /** @copydoc DataStream::tell
|
---|
| 424 | */
|
---|
| 425 | size_t tell(void) const;
|
---|
| 426 |
|
---|
| 427 | /** @copydoc DataStream::eof
|
---|
| 428 | */
|
---|
| 429 | bool eof(void) const;
|
---|
| 430 |
|
---|
| 431 | /** @copydoc DataStream::close
|
---|
| 432 | */
|
---|
| 433 | void close(void);
|
---|
| 434 |
|
---|
| 435 | };
|
---|
| 436 | }
|
---|
| 437 | #endif
|
---|
| 438 |
|
---|