common/stream.h

   1 /* ScummVM - Graphic Adventure Engine
   2  *
   3  * ScummVM is the legal property of its developers, whose names
   4  * are too numerous to list here. Please refer to the COPYRIGHT
   5  * file distributed with this source distribution.
   6  *
   7  * This program is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU General Public License
   9  * as published by the Free Software Foundation; either version 2
  10  * of the License, or (at your option) any later version.
  11
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  20  *
  21  * $URL$
  22  * $Id$
  23  *
  24  */
  25
  26 #ifndef COMMON_STREAM_H
  27 #define COMMON_STREAM_H
  28
  29 #include "common/scummsys.h"
  30
  31 namespace Common {
  32
  33 class String;
  34 class MemoryReadStream;
  35
  36 /**
  37  * Virtual base class for both ReadStream and WriteStream.
  38  */
  39 class Stream {
  40 public:
  41         virtual ~Stream() {}
  42
  43         /**
  44          * Returns true if an I/O failure occurred.
  45          * This flag is never cleared automatically. In order to clear it,
  46          * client code has to call clearErr() explicitly.
  47          */
  48         virtual bool err() const { return false; }
  49
  50         /**
  51          * Reset the I/O error status as returned by err().
  52          * For a ReadStream, also reset the end-of-stream status returned by eos().
  53          */
  54         virtual void clearErr() {}
  55 };
  56
  57 /**
  58  * Generic interface for a writable data stream.
  59  */
  60 class WriteStream : virtual public Stream {
  61 public:
  62         /**
  63          * Write data into the stream. Subclasses must implement this
  64          * method; all other write methods are implemented using it.
  65          *
  66          * @param dataPtr       pointer to the data to be written
  67          * @param dataSize      number of bytes to be written
  68          * @return the number of bytes which were actually written.
  69          */
  70         virtual uint32 write(const void *dataPtr, uint32 dataSize) = 0;
  71
  72         /**
  73          * Commit any buffered data to the underlying channel or
  74          * storage medium; unbuffered streams can use the default
  75          * implementation.
  76          *
  77          * @return true on success, false in case of a failure
  78          */
  79         virtual bool flush() { return true; }
  80
  81         /**
  82          * Finalize and close this stream. To be called right before this
  83          * stream instance is deleted. The goal here is to enable calling
  84          * code to detect and handle I/O errors which might occur when
  85          * closing (and this flushing, if buffered) the stream.
  86          *
  87          * After this method has been called, no further writes may be
  88          * performed on the stream. Calling err() is allowed.
  89          *
  90          * By default, this just flushes the stream.
  91          */
  92         virtual void finalize() {
  93                 flush();
  94         }
  95
  96
  97         // The remaining methods all have default implementations; subclasses
  98         // need not (and should not) overload them.
  99
 100         void writeByte(byte value) {
 101                 write(&value, 1);
 102         }
 103
 104         void writeSByte(int8 value) {
 105                 write(&value, 1);
 106         }
 107
 108         void writeUint16LE(uint16 value) {
 109                 writeByte((byte)(value & 0xff));
 110                 writeByte((byte)(value >> 8));
 111         }
 112
 113         void writeUint32LE(uint32 value) {
 114                 writeUint16LE((uint16)(value & 0xffff));
 115                 writeUint16LE((uint16)(value >> 16));
 116         }
 117
 118         void writeUint16BE(uint16 value) {
 119                 writeByte((byte)(value >> 8));
 120                 writeByte((byte)(value & 0xff));
 121         }
 122
 123         void writeUint32BE(uint32 value) {
 124                 writeUint16BE((uint16)(value >> 16));
 125                 writeUint16BE((uint16)(value & 0xffff));
 126         }
 127
 128         void writeSint16LE(int16 value) {
 129                 writeUint16LE((uint16)value);
 130         }
 131
 132         void writeSint32LE(int32 value) {
 133                 writeUint32LE((uint32)value);
 134         }
 135
 136         void writeSint16BE(int16 value) {
 137                 writeUint16BE((uint16)value);
 138         }
 139
 140         void writeSint32BE(int32 value) {
 141                 writeUint32BE((uint32)value);
 142         }
 143
 144         /**
 145          * Write the given string to the stream.
 146          * This writes str.size() characters, but no terminating zero byte.
 147          */
 148         void writeString(const String &str);
 149 };
 150
 151
 152 /**
 153  * Generic interface for a readable data stream.
 154  */
 155 class ReadStream : virtual public Stream {
 156 public:
 157         /**
 158          * Returns true if a read failed because the stream has been reached.
 159          * This flag is cleared by clearErr().
 160          * For a SeekableReadStream, it is also cleared by a successful seek.
 161          */
 162         virtual bool eos() const = 0;
 163
 164         /**
 165          * Read data from the stream. Subclasses must implement this
 166          * method; all other read methods are implemented using it.
 167          *
 168          * @param dataPtr       pointer to a buffer into which the data is read
 169          * @param dataSize      number of bytes to be read
 170          * @return the number of bytes which were actually read.
 171          */
 172         virtual uint32 read(void *dataPtr, uint32 dataSize) = 0;
 173
 174
 175         // The remaining methods all have default implementations; subclasses
 176         // in general should not overload them.
 177
 178         /**
 179          * DEPRECATED
 180          * Default implementation for backward compatibility
 181          */
 182         inline bool ioFailed() { return (eos() || err()); }
 183
 184         /**
 185          * Read an unsigned byte from the stream and return it.
 186          * Performs no error checking. The return value is undefined
 187          * if a read error occurred (for which client code can check by
 188          * calling err() and eos() ).
 189          */
 190         byte readByte() {
 191                 byte b = 0;
 192                 read(&b, 1);
 193                 return b;
 194         }
 195
 196         /**
 197          * Read a signed byte from the stream and return it.
 198          * Performs no error checking. The return value is undefined
 199          * if a read error occurred (for which client code can check by
 200          * calling err() and eos() ).
 201          */
 202         int8 readSByte() {
 203                 int8 b = 0;
 204                 read(&b, 1);
 205                 return b;
 206         }
 207
 208         /**
 209          * Read an unsigned 16-bit word stored in little endian (LSB first) order
 210          * from the stream and return it.
 211          * Performs no error checking. The return value is undefined
 212          * if a read error occurred (for which client code can check by
 213          * calling err() and eos() ).
 214          */
 215         uint16 readUint16LE() {
 216                 uint16 a = readByte();
 217                 uint16 b = readByte();
 218                 return a | (b << 8);
 219         }
 220
 221         /**
 222          * Read an unsigned 32-bit word stored in little endian (LSB first) order
 223          * from the stream and return it.
 224          * Performs no error checking. The return value is undefined
 225          * if a read error occurred (for which client code can check by
 226          * calling err() and eos() ).
 227          */
 228         uint32 readUint32LE() {
 229                 uint32 a = readUint16LE();
 230                 uint32 b = readUint16LE();
 231                 return (b << 16) | a;
 232         }
 233
 234         /**
 235          * Read an unsigned 16-bit word stored in big endian (MSB first) order
 236          * from the stream and return it.
 237          * Performs no error checking. The return value is undefined
 238          * if a read error occurred (for which client code can check by
 239          * calling err() and eos() ).
 240          */
 241         uint16 readUint16BE() {
 242                 uint16 b = readByte();
 243                 uint16 a = readByte();
 244                 return a | (b << 8);
 245         }
 246
 247         /**
 248          * Read an unsigned 32-bit word stored in big endian (MSB first) order
 249          * from the stream and return it.
 250          * Performs no error checking. The return value is undefined
 251          * if a read error occurred (for which client code can check by
 252          * calling err() and eos() ).
 253          */
 254         uint32 readUint32BE() {
 255                 uint32 b = readUint16BE();
 256                 uint32 a = readUint16BE();
 257                 return (b << 16) | a;
 258         }
 259
 260         /**
 261          * Read a signed 16-bit word stored in little endian (LSB first) order
 262          * from the stream and return it.
 263          * Performs no error checking. The return value is undefined
 264          * if a read error occurred (for which client code can check by
 265          * calling err() and eos() ).
 266          */
 267         int16 readSint16LE() {
 268                 return (int16)readUint16LE();
 269         }
 270
 271         /**
 272          * Read a signed 32-bit word stored in little endian (LSB first) order
 273          * from the stream and return it.
 274          * Performs no error checking. The return value is undefined
 275          * if a read error occurred (for which client code can check by
 276          * calling err() and eos() ).
 277          */
 278         int32 readSint32LE() {
 279                 return (int32)readUint32LE();
 280         }
 281
 282         /**
 283          * Read a signed 16-bit word stored in big endian (MSB first) order
 284          * from the stream and return it.
 285          * Performs no error checking. The return value is undefined
 286          * if a read error occurred (for which client code can check by
 287          * calling err() and eos() ).
 288          */
 289         int16 readSint16BE() {
 290                 return (int16)readUint16BE();
 291         }
 292
 293         /**
 294          * Read a signed 32-bit word stored in big endian (MSB first) order
 295          * from the stream and return it.
 296          * Performs no error checking. The return value is undefined
 297          * if a read error occurred (for which client code can check by
 298          * calling err() and eos() ).
 299          */
 300         int32 readSint32BE() {
 301                 return (int32)readUint32BE();
 302         }
 303
 304         /**
 305          * Read the specified amount of data into a malloc'ed buffer
 306          * which then is wrapped into a MemoryReadStream.
 307          * The returned stream might contain less data than requested,
 308          * if reading more failed, because of an I/O error or because
 309          * the end of the stream was reached. Which can be determined by
 310          * calling err() and eos().
 311          */
 312         MemoryReadStream *readStream(uint32 dataSize);
 313
 314 };
 315
 316
 317 /**
 318  * Interface for a seekable & readable data stream.
 319  *
 320  * @todo Get rid of SEEK_SET, SEEK_CUR, or SEEK_END, use our own constants
 321  */
 322 class SeekableReadStream : virtual public ReadStream {
 323 public:
 324
 325         /**
 326          * Obtains the current value of the stream position indicator of the
 327          * stream.
 328          *
 329          * @return the current position indicator, or -1 if an error occurred.
 330          */
 331         virtual int32 pos() const = 0;
 332
 333         /**
 334          * Obtains the total size of the stream, measured in bytes.
 335          * If this value is unknown or can not be computed, -1 is returned.
 336          *
 337          * @return the size of the stream, or -1 if an error occurred
 338          */
 339         virtual int32 size() const = 0;
 340
 341         /**
 342          * Sets the stream position indicator for the stream. The new position,
 343          * measured in bytes, is obtained by adding offset bytes to the position
 344          * specified by whence. If whence is set to SEEK_SET, SEEK_CUR, or
 345          * SEEK_END, the offset is relative to the start of the file, the current
 346          * position indicator, or end-of-file, respectively. A successful call
 347          * to the seek() method clears the end-of-file indicator for the stream.
 348          *
 349          * @param offset        the relative offset in bytes
 350          * @param whence        the seek reference: SEEK_SET, SEEK_CUR, or SEEK_END
 351          * @return true on success, false in case of a failure
 352          */
 353         virtual bool seek(int32 offset, int whence = SEEK_SET) = 0;
 354
 355         /**
 356          * TODO: Get rid of this??? Or keep it and document it
 357          * @return true on success, false in case of a failure
 358          */
 359         virtual bool skip(uint32 offset) { return seek(offset, SEEK_CUR); }
 360
 361         /**
 362          * Reads at most one less than the number of characters specified
 363          * by bufSize from the and stores them in the string buf. Reading
 364          * stops when the end of a line is reached (CR, CR/LF or LF), and
 365          * at end-of-file or error. The newline, if any, is retained (CR
 366          * and CR/LF are translated to LF = 0xA = '\n'). If any characters
 367          * are read and there is no error, a `\0' character is appended
 368          * to end the string.
 369          *
 370          * Upon successful completion, return a pointer to the string. If
 371          * end-of-file occurs before any characters are read, returns NULL
 372          * and the buffer contents remain unchanged.  If an error occurs,
 373          * returns NULL and the buffer contents are indeterminate.
 374          * This method does not distinguish between end-of-file and error;
 375          * callers must use err() or eos() to determine which occurred.
 376          *
 377          * @note This methods is closely modeled after the standard fgets()
 378          *       function from stdio.h.
 379          *
 380          * @param buf   the buffer to store into
 381          * @param bufSize       the size of the buffer
 382          * @return a pointer to the read string, or NULL if an error occurred
 383          */
 384         virtual char *readLine_NEW(char *s, size_t bufSize);
 385
 386
 387         /**
 388          * Reads a full line and returns it as a Common::String. Reading
 389          * stops when the end of a line is reached (CR, CR/LF or LF), and
 390          * at end-of-file or error.
 391          *
 392          * Upon successful completion, return a string with the content
 393          * of the line, *without* the end of a line marker. This method
 394          * does not indicate whether an error occured. Callers must use
 395          * err() or eos() to determine whether an exception occurred.
 396          */
 397         virtual String readLine();
 398 };
 399
 400 /**
 401  * SubReadStream provides access to a ReadStream restricted to the range
 402  * [currentPosition, currentPosition+end).
 403  * Manipulating the parent stream directly /will/ mess up a substream.
 404  * Likewise, manipulating two substreams of a parent stream will cause them to
 405  * step on each others toes.
 406  */
 407 class SubReadStream : virtual public ReadStream {
 408 protected:
 409         ReadStream *_parentStream;
 410         bool _disposeParentStream;
 411         uint32 _pos;
 412         uint32 _end;
 413         bool _eos;
 414 public:
 415         SubReadStream(ReadStream *parentStream, uint32 end, bool disposeParentStream = false)
 416                 : _parentStream(parentStream),
 417                   _disposeParentStream(disposeParentStream),
 418                   _pos(0),
 419                   _end(end),
 420                   _eos(false) {
 421                 assert(parentStream);
 422         }
 423         ~SubReadStream() {
 424                 if (_disposeParentStream) delete _parentStream;
 425         }
 426
 427         virtual bool eos() const { return _eos; }
 428         virtual bool err() const { return _parentStream->err(); }
 429         virtual void clearErr() { _eos = false; _parentStream->clearErr(); }
 430         virtual uint32 read(void *dataPtr, uint32 dataSize);
 431 };
 432
 433 /*
 434  * SeekableSubReadStream provides access to a SeekableReadStream restricted to
 435  * the range [begin, end).
 436  * The same caveats apply to SeekableSubReadStream as do to SeekableReadStream.
 437  */
 438 class SeekableSubReadStream : public SubReadStream, public SeekableReadStream {
 439 protected:
 440         SeekableReadStream *_parentStream;
 441         uint32 _begin;
 442 public:
 443         SeekableSubReadStream(SeekableReadStream *parentStream, uint32 begin, uint32 end, bool disposeParentStream = false);
 444
 445         virtual int32 pos() const { return _pos - _begin; }
 446         virtual int32 size() const { return _end - _begin; }
 447
 448         virtual bool seek(int32 offset, int whence = SEEK_SET);
 449 };
 450
 451 /**
 452  * This is a wrapper around SeekableSubReadStream, but it adds non-endian
 453  * read methods whose endianness is set on the stream creation.
 454  */
 455 class SeekableSubReadStreamEndian : public SeekableSubReadStream {
 456 public:
 457         bool _bigEndian;
 458
 459         SeekableSubReadStreamEndian(SeekableReadStream *parentStream, uint32 begin, uint32 end, bool bigEndian = false, bool disposeParentStream = false)
 460                 : SeekableSubReadStream(parentStream, begin, end, disposeParentStream), _bigEndian(bigEndian) {
 461         }
 462
 463         inline uint16 readUint16() {
 464                 return (_bigEndian) ? readUint16BE() : readUint16LE();
 465         }
 466
 467         inline uint32 readUint32() {
 468                 return (_bigEndian) ? readUint32BE() : readUint32LE();
 469         }
 470
 471         inline int16 readSint16() {
 472                 return (int16)readUint16();
 473         }
 474
 475         inline int32 readSint32() {
 476                 return (int32)readUint32();
 477         }
 478 };
 479
 480 /**
 481  * Wrapper class which adds buffering to any given ReadStream.
 482  * Users can specify how big the buffer should be, and whether the
 483  * wrapped stream should be disposed when the wrapper is disposed.
 484  */
 485 class BufferedReadStream : virtual public ReadStream {
 486 protected:
 487         ReadStream *_parentStream;
 488         bool _disposeParentStream;
 489         byte *_buf;
 490         uint32 _pos;
 491         uint32 _bufSize;
 492         uint32 _realBufSize;
 493
 494 public:
 495         BufferedReadStream(ReadStream *parentStream, uint32 bufSize, bool disposeParentStream = false);
 496         ~BufferedReadStream();
 497
 498         virtual bool eos() const { return (_pos == _bufSize) && _parentStream->eos(); }
 499         virtual bool err() const { return _parentStream->err(); }
 500         virtual void clearErr() { _parentStream->clearErr(); }
 501
 502         virtual uint32 read(void *dataPtr, uint32 dataSize);
 503 };
 504
 505 /**
 506  * Wrapper class which adds buffering to any given SeekableReadStream.
 507  * @see BufferedReadStream
 508  */
 509 class BufferedSeekableReadStream : public BufferedReadStream, public SeekableReadStream {
 510 protected:
 511         SeekableReadStream *_parentStream;
 512 public:
 513         BufferedSeekableReadStream(SeekableReadStream *parentStream, uint32 bufSize, bool disposeParentStream = false);
 514
 515         virtual int32 pos() const { return _parentStream->pos() - (_bufSize - _pos); }
 516         virtual int32 size() const { return _parentStream->size(); }
 517
 518         virtual bool seek(int32 offset, int whence = SEEK_SET);
 519 };
 520
 521
 522
 523 /**
 524  * Simple memory based 'stream', which implements the ReadStream interface for
 525  * a plain memory block.
 526  */
 527 class MemoryReadStream : public SeekableReadStream {
 528 private:
 529         const byte * const _ptrOrig;
 530         const byte *_ptr;
 531         const uint32 _size;
 532         uint32 _pos;
 533         byte _encbyte;
 534         bool _disposeMemory;
 535         bool _eos;
 536
 537 public:
 538
 539         /**
 540          * This constructor takes a pointer to a memory buffer and a length, and
 541          * wraps it. If disposeMemory is true, the MemoryReadStream takes ownership
 542          * of the buffer and hence free's it when destructed.
 543          */
 544         MemoryReadStream(const byte *dataPtr, uint32 dataSize, bool disposeMemory = false) :
 545                 _ptrOrig(dataPtr),
 546                 _ptr(dataPtr),
 547                 _size(dataSize),
 548                 _pos(0),
 549                 _encbyte(0),
 550                 _disposeMemory(disposeMemory),
 551                 _eos(false) {}
 552
 553         ~MemoryReadStream() {
 554                 if (_disposeMemory)
 555                         free(const_cast<byte *>(_ptrOrig));
 556         }
 557
 558         void setEnc(byte value) { _encbyte = value; }
 559
 560         uint32 read(void *dataPtr, uint32 dataSize);
 561
 562         bool eos() const { return _eos; }
 563         void clearErr() { _eos = false; }
 564
 565         int32 pos() const { return _pos; }
 566         int32 size() const { return _size; }
 567
 568         bool seek(int32 offs, int whence = SEEK_SET);
 569 };
 570
 571
 572 /**
 573  * This is a wrapper around MemoryReadStream, but it adds non-endian
 574  * read methods whose endianness is set on the stream creation.
 575  */
 576 class MemoryReadStreamEndian : public Common::MemoryReadStream {
 577 private:
 578 public:
 579         bool _bigEndian;
 580         MemoryReadStreamEndian(const byte *buf, uint32 len, bool bigEndian = false) : MemoryReadStream(buf, len), _bigEndian(bigEndian) {}
 581
 582         inline uint16 readUint16() {
 583                 return (_bigEndian) ? readUint16BE() : readUint16LE();
 584         }
 585
 586         inline uint32 readUint32() {
 587                 return (_bigEndian) ? readUint32BE() : readUint32LE();
 588         }
 589
 590         inline int16 readSint16() {
 591                 return (int16)readUint16();
 592         }
 593
 594         inline int32 readSint32() {
 595                 return (int32)readUint32();
 596         }
 597 };
 598
 599 /**
 600  * Simple memory based 'stream', which implements the WriteStream interface for
 601  * a plain memory block.
 602  */
 603 class MemoryWriteStream : public WriteStream {
 604 private:
 605         byte *_ptr;
 606         const uint32 _bufSize;
 607         uint32 _pos;
 608 public:
 609         MemoryWriteStream(byte *buf, uint32 len) : _ptr(buf), _bufSize(len), _pos(0) {}
 610
 611         uint32 write(const void *dataPtr, uint32 dataSize) {
 612                 // Write at most as many bytes as are still available...
 613                 if (dataSize > _bufSize - _pos)
 614                         dataSize = _bufSize - _pos;
 615                 memcpy(_ptr, dataPtr, dataSize);
 616                 _ptr += dataSize;
 617                 _pos += dataSize;
 618                 return dataSize;
 619         }
 620
 621         uint32 pos() const { return _pos; }
 622         uint32 size() const { return _bufSize; }
 623 };
 624
 625 /**
 626  * A sort of hybrid between MemoryWriteStream and Array classes. A stream
 627  * that grows as it's written to.
 628  */
 629 class MemoryWriteStreamDynamic : public Common::WriteStream {
 630 private:
 631         uint32 _capacity;
 632         uint32 _size;
 633         byte *_ptr;
 634         byte *_data;
 635         uint32 _pos;
 636         bool _disposeMemory;
 637
 638         void ensureCapacity(uint32 new_len) {
 639                 if (new_len <= _capacity)
 640                         return;
 641
 642                 byte *old_data = _data;
 643
 644                 _capacity = new_len + 32;
 645                 _data = new byte[_capacity];
 646                 _ptr = _data + _pos;
 647
 648                 if (old_data) {
 649                         // Copy old data
 650                         memcpy(_data, old_data, _size);
 651                         delete[] old_data;
 652                 }
 653
 654                 _size = new_len;
 655         }
 656 public:
 657         MemoryWriteStreamDynamic(bool disposeMemory = false) : _capacity(0), _size(0), _ptr(0), _data(0), _pos(0), _disposeMemory(disposeMemory) {}
 658
 659         ~MemoryWriteStreamDynamic() {
 660                 if (_disposeMemory)
 661                         delete[] _data;
 662         }
 663
 664         uint32 write(const void *dataPtr, uint32 dataSize) {
 665                 ensureCapacity(_pos + dataSize);
 666                 memcpy(_ptr, dataPtr, dataSize);
 667                 _ptr += dataSize;
 668                 _pos += dataSize;
 669                 if (_pos > _size)
 670                         _size = _pos;
 671                 return dataSize;
 672         }
 673
 674         uint32 pos() const { return _pos; }
 675         uint32 size() const { return _size; }
 676
 677         byte *getData() { return _data; }
 678 };
 679
 680 }       // End of namespace Common
 681
 682 #endif