Streaming Overview

Purpose

Streams abstract the external storage of data (typically objects).

Architectural relationships

The Streaming API is abstract. It defines interfaces for reading and writing data to and from storage, but not what that storage is. Derived classes in other APIs provide particular implementations of streams:

file streams, as defined in the File Stores API
streams used as part of a network of related streams, called a store, as defined in the Stores API
memory-based streams, as defined in the Memory Streams API
encrypted streams, as defined in the Encrypted Streams And Stores API

Description

The API has two key concepts: stream, and stream operators.

Stream

A stream is a representation of an object as a sequence of bytes. Streams are accessed by means of write streams, which allow data to be written to them, and read streams, which allow data to be read.

Data written to a stream should be in an external format: i.e. not depend on machine-specific properties such as endianness and padding. C++ classes designed to work with streams implement a function to externalise their state, and similarly an internalise function to set their state from a stream. The convention is to call these functions ExternalizeL() and InternalizeL() respectively.

Write streams are represented by the abstract class RWriteStream, and read streams by the abstract class RReadStream.

Stream operators

The stream operators define (using templates) << and >> so that objects can be written to streams using the format astream << anobject astream << anobject, and internalised using astream >> anobject. These translate into calls to the object's ExternalizeL() and InternalizeL() functions respectively. The operators are also defined so that they can be used with basic types such as TInt8, TReal32, etc.