### IDataStream

  IDataStream provides a facility for C++ classes to read or write their state to or from an external place - a file, memory, or other destination. Similar facilities in other systems are called internalization and externalization, or flatten and resurrection. An IDataStream object represents the place from or to which objects may be read or written.

  This class does not support multi-threaded applications.

  Do not derive from this class.

  The primary functions for reading and writing objects from an IDataStream are the following global function:

      readObject()
      writeObject()
      readAliasedObject()
      writeAliasedObject()

  Other related classes are IMStreamable, IStreamModule, IStreamContextFrame, IStreamInFrame, and IStreamOutFrame.

### IDataStream - Member Functions and Data by Group

### Constructors & Destructor

Class constructors and destructor. This classes constructors are all private to prevent construction of these objects on the stack. Use factory methods to create instances of this class on the heap.

~IDataStream

      public:
      ~IDataStream()

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Factory methods

Creation of IDataStream objects. Also see IFile::createStream() for the creation of an IDataStream that targets files.

createMemoryStream

      public:
      static IDataStream*
        createMemoryStream( int encoding = kInteroperableBinary )

  Create an IDataStream that writes and reads data to a temporary memory buffer. The buffer is automaticallly allocated and grows as required to hold the data.

  This form of IDataStream is commonly used to test the streaming operators for other (user) classes. Returns an IDataStream pointer to the created memory stream.

  encoding
    The type of stream encoding to use. Default to kInteroperableBinary.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Read and Write Array

These methods read and write array of primitive types.

readBytes

      public:
      void readBytes(char* data, unsigned long howMany)

  Read an array of bytes from the data stream.

  data
    address of the buffer into which the data will be placed.
  howMany
    the number of bytes to read from the stream.

Exception

  IInvalidDataOnStream | the data found on the stream was not of the correct type. (DD) IEndOfStream the operation reached the end of the stream.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

readDoubles

      public:
      void readDoubles(double* data, unsigned long howMany)

  read an array of Doubles (64bit floating points) from the IDataStream

  data
    the address of the array into which the data will be read.
  howMany
    the number of doubles to be read.

Exception

  IInvalidDataOnStream | the data found on the stream was not of the correct type. (DD) IEndOfStream the operation reached the end of the stream.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

readFloats

      public:
      void readFloats(float* data, unsigned long howMany)

  Read an array of floating point values from an IDataStream.

  data
    the address of the array into which the data will be read.
  howMany
    the number of floats to be read from the stream.

Exception

  IInvalidDataOnStream | the data found on the stream was not of the correct type. (DD) IEndOfStream the operation reached the end of the stream.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

readLongs

      public:
      void readLongs(long* data, unsigned long howMany)

  read an array of longs from an IDataStream.

  data
    the address of the array into which the data will be read.
  howMany
    the number of longs to be read.

Exception

  IInvalidDataOnStream | the data found on the stream was not of the correct type. (DD) IEndOfStream the operation reached the end of the stream.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

readShorts

      public:
      void readShorts(short* data, unsigned long howMany)

  Read an array of shorts (16 bit values) from an IDataStream.

  data
    the address of the array into which the data will be read
  howMany
    the number of shorts to be read from the stream.

Exception

  IInvalidDataOnStream | the data found on the stream was not of the correct type. (DD) IEndOfStream the operation reached the end of the stream.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

writeBytes

      public:
      void writeBytes(const char* data, unsigned long howMany)

  Write an array of bytes to an IDataStream.

  data
    address of the buffer containing the data to be written to the stream.
  howMany
    number of bytes to write to the stream.

Exception

  IInvalidDataOnStream | the data found on the stream was not of the correct type. (DD) IEndOfStream the operation reached the end of the stream.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

writeDoubles

      public:
      void
        writeDoubles( const double* data,
                      unsigned long howMany )

  Write an array of doubles (64 bit floating point values) to an IDataStream.

  data
    address of the buffer containing the data to be written.
  howMany
    the number of doubles to be written to the stream.

Exception

  IInvalidDataOnStream | the data found on the stream was not of the correct type. (DD) IEndOfStream the operation reached the end of the stream.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

writeFloats

      public:
      void writeFloats(const float* data, unsigned long howMany)

  Write an array of floats to an IDataStream.

  data
    the address of the buffer containing the data to be written to the stream.
  howMany
    the number of floats to be written.

Exception

  IInvalidDataOnStream | the data found on the stream was not of the correct type. (DD) IEndOfStream the operation reached the end of the stream.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

writeLongs

      public:
      void writeLongs(const long* data, unsigned long howMany)

  Write an array of longs to an IDataStream.

  data
    the address of the buffer holding the data to be written to the stream.
  howMany
    the number of longs to be written.

Exception

  IInvalidDataOnStream | the data found on the stream was not of the correct type. (DD) IEndOfStream the operation reached the end of the stream.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

writeShorts

      public:
      void writeShorts(const short* data, unsigned long howMany)

  Write an array of shorts to an IDataStream.

  data
    address of the buffer containing the data to write to the IDataStream.
  howMany
    number of shorts to be written.

Exception

  IInvalidDataOnStream | the data found on the stream was not of the correct type. (DD) IEndOfStream the operation reached the end of the stream.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Read and Write Primitive Types

These methods read and write primitive types.

readByte

      public:
      char readByte()

  Read one byte of data from the stream. Also see the global stream-in function <<=, which will perform the same operation, but is more convenient to use.

Return
  the data read from the stream

Exception

  IInvalidDataOnStream | the data found on the stream was not of the correct type. (DD) IEndOfStream the operation reached the end of the stream.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

readDouble

      public:
      double readDouble()

  Read a double (64 bit floating point) from the IDataStream.

Return
  the data read from the stream

Exception

  IInvalidDataOnStream | the data found on the stream was not of the correct type. (DD) IEndOfStream the operation reached the end of the stream.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

readFloat

      public:
      float readFloat()

  Read a floating point value from an IDataStream. See also the global operator <<=(float &, IDataSteam &), which provides a more convenient way to read data from an IDataStream

Return
  the data read from the stream.

Exception

  IInvalidDataOnStream | the data found on the stream was not of the correct type. (DD) IEndOfStream the operation reached the end of the stream.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

readLong

      public:
      long readLong()

  read a long from an IDataStream. The global operator <<=(long &, IDataStream &) provides a more convenient way to perform this operation.

Exception

  IInvalidDataOnStream | the data found on the stream was not of the correct type. (DD) IEndOfStream the operation reached the end of the stream.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

readShort

      public:
      short readShort()

  read a short (16 bit) value from an IDataStream. The global operator <<=(short &, IDataStream &) provides a more convenient way to perform this operation.

Return
  the value read from the stream.

Exception

  IInvalidDataOnStream | the data found on the stream was not of the correct type. (DD) IEndOfStream the operation reached the end of the stream.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

writeByte

      public:
      void writeByte(char source)

  write a byte to an IDataStream. The global operator >>=(char, IDataStream) provides a more convenient way to perform this operation.

  source
    the data to be written.

Exception

  IInvalidDataOnStream | the data found on the stream was not of the correct type. (DD) IEndOfStream the operation reached the end of the stream.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

writeDouble

      public:
      void writeDouble(double source)

  Write a double precision floating point value to an IDataStream. The global operator >>= (double, IDataStream &) provides a more convenient way to perform this operation.

  source
    the value to be written to the stream.

Exception

  IInvalidDataOnStream | the data found on the stream was not of the correct type. (DD) IEndOfStream the operation reached the end of the stream.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

writeFloat

      public:
      void writeFloat(float source)

  Write a floating point value to an IDataStream. The global streaming operator >>=(float, IDataStream &) provides a more convenient way of performing this operation.

  source
    the value to be written to the stream.

Exception

  IInvalidDataOnStream | the data found on the stream was not of the correct type. (DD) IEndOfStream the operation reached the end of the stream.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

writeLong

      public:
      void writeLong(long source)

  Write a long to an IDataStream. The global streaming operator >>= (long, IDataStream &) provides a more convenient way to perform this operation.

  source
    the value to be written to the stream.

Exception

  IInvalidDataOnStream | the data found on the stream was not of the correct type. (DD) IEndOfStream the operation reached the end of the stream.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

writeShort

      public:
      void writeShort(short source)

  Write a short (16 bit) value to an IDataStream. The global streaming operator >>=(short, IDataStream) provides a more convenient way of performing this operation.

  source
    the value to be written to the stream.

Exception

  IInvalidDataOnStream | the data found on the stream was not of the correct type. (DD) IEndOfStream the operation reached the end of the stream.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Stream Control

These methods affect the state of the the stream rather than the data which is in it.

flush

      public:
      void flush()

  Forces all data out through the stream buffer.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

reset

      public:
      void reset()

  Resets the stream back to the beginning.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### IDataStream - Enumerations

EStreamEncoding

      enum EStreamEncoding { kInteroperableBinary,
                             kRawBinary,
                             kDebug }

  Defines encoding types.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### IDataStream - Associated Globals

operator <<=

      void operator <<=(long& c, IDataStream& s)

  Read a long value from an IDataStream. The value is returned to the caller by reference.

operator <<=

      void operator <<=(unsigned long& c, IDataStream& s)

  Read a unsigned long value from an IDataStream. The value is returned to the caller by reference.

operator <<=

      void operator <<=(unsigned short& c, IDataStream& s)

  Read a unsigned short value from an IDataStream. The value is returned to the caller by reference.

operator <<=

      void operator <<=(double& c, IDataStream& s)

  Read a double value from an IDataStream. The value is returned to the caller by reference.

operator <<=

      void operator <<=(IMStreamable& c, IDataStream& s)

  Read a IMStreamable value from an IDataStream. The value is returned to the caller by reference.

operator <<=

      void operator <<=(signed char& c, IDataStream& s)

  Read a signed char value from an IDataStream. The value is returned to the caller by reference.

operator <<=

      void operator <<=(unsigned char& c, IDataStream& s)

  Read a unsigned char value from an IDataStream. The value is returned to the caller by reference.

operator <<=

      void operator <<=(float& c, IDataStream& s)

  Read a float value from an IDataStream. The value is returned to the caller by reference.

operator <<=

      void operator <<=(short& c, IDataStream& s)

  Read a short value from an IDataStream. The value is returned to the caller by reference.

operator <<=

      void operator <<=(char& c, IDataStream& s)

  Read a char value from an IDataStream. The value is returned to the caller by reference.

operator >>=

      void operator >>=(signed char c, IDataStream& s)

  Write a signed char value to an IDataStream.

operator >>=

      void operator >>=(unsigned short c, IDataStream& s)

  Write a unsigned short value to an IDataStream.

operator >>=

      void operator >>=(short c, IDataStream& s)

  Write a short value to an IDataStream.

operator >>=

      void operator >>=(unsigned long c, IDataStream& s)

  Write a unsigned long value to an IDataStream.

operator >>=

      void operator >>=(char c, IDataStream& s)

  Write a char value to an IDataStream.

operator >>=

      void operator >>=(unsigned char c, IDataStream& s)

  Write a unsigned char value to an IDataStream.

operator >>=

      void operator >>=(float c, IDataStream& s)

  Write a float value to an IDataStream.

operator >>=

      void operator >>=(long c, IDataStream& s)

  Write a long value to an IDataStream.

operator >>=

      void operator >>=(double c, IDataStream& s)

  Write a double value to an IDataStream.

operator >>=

      void operator >>=(const IMStreamable& object, IDataStream& s)

  Write an IMStreamable object to an IDataStream.

readAliasedObject

      void readAliasedObject(AType *& theResult, IDataStream& theStream)

  Polymorphically read an object from an IDataStream. "AType" must descend from IMStreamable and IMRefCounted.

readObject

      void readObject(AType *& theResult, IDataStream& theStream)

  Polymorphically read an object from an IDataStream. "AType" must descend from IMStreamable.

writeAliasedObject

      void writeAliasedObject(const AType* theObject, IDataStream& theStream)

  Polymorphically write an object to an IDataStream. "AType" must descend from IMStreamable and IMRefCounted.

writeObject

      void writeObject(const AType* theObject, IDataStream& theStream)

  Polymorphically write an object to an IDataStream. "AType" must descend from IMStreamable.

### IDataStream - Inherited Member Functions and Data

#### Inherited Public Functions

  IDataStream

  -     IStreamIO* streamIO() const

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  - None

#### Inherited Protected Data

  - None