IStreamInFrame

This class is part of the streaming systems facilities for release-to-release data compatibility (RRDC).

RRDC allows a new version of a class to read in instance data streamed by an earlier version AND also allows an older class implementation to read data written by a newer implementation.

The streaming system is described in more detail in the description for classes IMStreamable and IDataStream.

For any application class that supports RRDC, the override of IMStreamable::readFromStream() must declare a local instance of IStreamInFrame before streaming in the member data of the class. The scope of this local variable must include all of the stream-ins of the member data.

In addition, readFromStream() function for any class that is in a second or greater release, and has extended the data it streams, must make a check at the point that it has read all of the data that would have been written by the older releases. If the stream was written by an older version, and thus does not contain the additional data, the readFromStream function must set the state of the object to a reasonable value and not attempt to stream in the missing data. IStreamInFrame::atEnd() allows this check to be made.

Use of stream frames is required in classes, even in their first release, if RRDC may be required for subsequent releases.

Example:

//
//  An example of a class and readFromStream function for the first
//    release of the class.  RRDC with future releases is allowed for,
//    through the use of IStreamInFrame.
//
class myClass: public IMStreamable {
    ...
    int              fData1;
    someType   fData2;
    ...
};

void myClass::readFromStream(IDataStream &fromWhere) { IStreamInFrame frame(fromWhere); fData1 <<= fromWhere; fData2 <<= fromWhere; }; // When the IStreamInFrame goes out of scope, as it does here, // any extra data that may have been written by some future, unknown to us at this time, // version of myClass will be automatically skipped, leaving the stream position // correct for the next object to be streamed in.


IStreamInFrame - Member Functions and Data by Group

Constructors & Destructor

The constructor and destructor for IStreamInFrame.


[view class]
~IStreamInFrame
public:
~IStreamInFrame()
Destructor. IStreamInFrame objects are always allocated on the stack, so the destructor is invoked automatically when the variable goes out of scope.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IStreamInFrame
public:
IStreamInFrame(IDataStream& aStream)
Create a new instances of an IStreamInFrame. This will always be a local (stack) variable within the readFromStream() method of a streamable class.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Stream Info

These methods allow users to query information about the stream.


[view class]
atEnd
public:
bool atEnd()
Checks whether all of the data that was written by a class's writeToStream() function within the context of an IStreamOutFrame has been read within the context of this IStreamInFrame.

This function (and class) is only used within the implementation of a readFromStream() function of a streamable class.

The readFromStream() function for any class that is in a 2nd or greater release and has extended the data that it writes to a stream should call atEnd() at the point(s) where all of the data written by earlier stream formats has been read. A return value of true indicates that the stream data was indeed written by an earlier version, and that there is no more data available to be read by this stream-in function. When this occurs, the readFromStream function should default all data items that have not yet been read, without reading any additional values from the stream.

Return
TRUE if at end, FALSE otherwise.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IStreamInFrame - Inherited Member Functions and Data

Inherited Public Functions

Inherited Public Data

Inherited Protected Functions

Inherited Protected Data