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